DkML

About OCaml

There are a few webpages that you should bookmark as you learn about OCaml. The first is the official OCaml website's About OCaml which has a comprehensive list of features that OCaml provides (the sales pitch!), and a good summary of OCaml:

OCaml mixes power and pragmatism in a way that makes it ideal for building complex software systems. What makes OCaml special is that it occupies a sweet spot in programming language design. It provides a combination of efficiency, expressiveness, and practicality that is matched by no other language. That is in large part because OCaml is an elegant combination of language features that have been developed over the last 40 years.

Then we recommend reading the first five chapters of the online textbook OCaml Programming - Correct + Efficient + Beautiful. The textbook has Youtube videos that can be watched independently of the textbook. The textbook and the videos will guide you through the language and explore each of OCaml's major features.

Once you start writing your own code you will need to know where to look to find libraries (called packages in OCaml). We recommend browsing the packages at OCaml Packages since it is official, reasonably up-to-date and has most packages' documentation.

Finally, if you hit a roadblock the best place to go is the Discord chat rooms and ask your question on the #beginners channel:

About DkML

The DkML distribution is an open-source set of software that supports software development in pure OCaml. The distribution's strengths are its:

• full compatibility with OCaml standards like Opam, Dune and ocamlfind
• laser focus on "native" development (desktop software, mobile apps and embedded software) through support for the standard native compilers like Visual Studio and Xcode
• ease-of-use through simplified installers and simple productivity commands; high school students should be able to use it
• security through reproducibility, versioning and from-source builds

These alternatives may be better depending on your use case:

• Developing in a Javascript first environment? Have a look at Esy and Reason
• Developing operating system kernels? Have a look at Mirage OS
• Developing Linux server software like web servers? Plain old OCaml on Debian, etc. works well
• Writing compilers or proofs? Plain old OCaml works really well
• Wanting quick installations? Use anything but DkML! DkML will conduct from-source builds unless it can guarantee (and code sign) the binaries are reproducible. Today that means a lot of compiling.

DkML officially supports Windows 64-bit machines and is slated to support macOS machines.

The DkML installer will install the basic OCaml system that includes:

• ocamlc: The batch compiler
• ocaml: The toplevel system or REPL. There is also a full-featured toplevel; see utop below
• ocamlrun: The runtime system
• ocamlopt: The native-code compiler
• ocamllex, ocamlyacc: Lexer and parser generators
• ocamldep: The dependency generator
• ocamldoc: The documentation generator
• ocamldebug: The debugger
• ocamlprof: The profiler
• ocamlmklib: The mixed C/OCaml library maker

The OCaml platform tools will also be installed:

• opam: Opam, the standard package manager for OCaml
• dune: Dune, the standard build tool for OCaml
• utop: UTop, the standard "toplevel" for interactively running OCaml code
• ocamllsp: OCaml Language Server for use with OCaml friendly IDEs like Visual Studio Code and Emacs
• ocamlformat and ocamlformat-rpc: OCamlFormat, the standard auto-formatter for OCaml code
• ocp-indent: ocp-indent, the standard indenter for mixed OCaml/non-OCaml documents
• findlib: Findlib, the standard library manager for OCaml modules
• flexdll: FlexDLL for expert users who are creating dynamic plugins

The DkML installer will also automatically install the following components if missing from your system:

• git: Git, the standard version control for getting, saving and sharing source code.
• cl and link: Visual Studio Build Tools, the official Microsoft tools for building modern C/C++ apps for Windows

Sponsor

Thanks to the OCaml Software Foundation for its economic support of DkML.

How to Install

These instructions are currently only for Windows developers.

Requirements

• 64-bit Windows 10 or 64-bit Windows 11. More operating systems will be coming.
• A fast internet connection. You will be downloading tens of gigabytes of data.
• 30GB of disk space.
• Administrator access on your computer to install the Microsoft C compilers. If you use a shared or restricted PC, please ask your PC administrator if they can follow the Windows Administrator Installation instructions; after that you and others on the PC can install without Administrator access.
• You don't need to watch the installation, but you do need to keep your computer powered on for at least one and a half (1.5) hours. The DkML installer will be downloading and doing intensive compilation during these hours, and you are free to do other things on your computer while it downloads and compiles.

Installation Instructions

Briefly review the following:

• Do not use the installer if you have a space in your username (ex. C:\Users\Jane Smith).

• You need to stay at your computer and press "Yes" for any Windows security popups; after the DkML installer finishes with two programs (Visual Studio Installer and Git for Windows) you can leave your computer for the remaining one and a half (1.5) hours.

• First time installations may get a notification printed in red. If you see it, reboot your computer and then restart your installation so that Visual Studio Installer can complete. The notification looks like:

- FATAL [118acf2a]. The machine needs rebooting.
- ...
- >>> The machine needs rebooting. <<<
-         ...
-         FATAL [5f927a8b].
-         A transient failure occurred.
-         ...
-         >>> A transient failure occurred. <<<

• You may be asked to accept a certificate from Open Source Developer, Gerardo Grignoli for the gsudo executable that was issued by Certum Code Signing CA SHA2.

Then run the latest Windows 64-bit installer.

Install is done! What next?

You have completed the installation of DkML. Let us try some of the things you can do right now.

1. Open PowerShell (press the Windows key ⊞, type "PowerShell" and then Open Windows PowerShell). Do not re-use an old PowerShell window since it will know nothing about the new installation you just did.

2. Run the utop application.

   Copy

   PS> utop
   > ─┬───────────────────────────────┬─
   >  │ Welcome to utop version 2.9.0 │
   >  └───────────────────────────────┘
   >
   > Type #utop_help for help about using utop.
   >
   > ─( 19:03:24 )─< command 0 >─{ counter: 0 }─
   > utop #

   You may get some harmless warnings (ex. "failed to lock file") that you can safely ignore.

3. Now let us try to enter some basic OCaml expressions ... be sure to include the ;; and then press ENTER after each line:

   Copy

   utop #> 3.5 +. 6. ;;
   > - : float = 9.5
   utop #> 30_000_000 / 300_000 ;;
   > - : int = 100
   utop #> let square x = x * x ;;
   > val square : int -> int = <fun>
   utop #> square 2 ;;
   > - : int = 4
   utop #> square (square 2) ;;
   > - : int = 16

4. You probably want to do a lot more than that! You may want to edit your code in a easy-to-use editor with syntax highlighting, type inspection and auto-complete (an "integrated development environment" or more simply an IDE). You may also want to use other people's code packages. Right now if you tried to use the Graphics package, for example, you will get an error:

   Copy

   utop #> open Graphics ;;
   > Error: Unbound module Graphics

5. Leave the utop application by typing:

   Copy

   utop #> #quit ;;

   Remember that if you get harmless warnings (ex. "failed to lock file") you can safely ignore them.

6. Continue with Beyond Basics, which is the next topic. It will tell you how to do important things like setting up your IDE. Please starting read it!