Getting Started with Diskuv OCaml

Table of Contents

Introduction

This section is about getting started with Diskuv OCaml. We will begin by giving you a brief overview of where to learn about OCaml, show you what you will get with the Diskuv OCaml distribution, and finish with how to get the Diskuv OCaml distribution installed on your system.

About OCaml

There are a few webpage that you should have bookmarked as you learn about OCaml. The first is the official OCaml website’s What’s OCaml? which has a comprehensive list of features that OCaml provides (the sales pitch!), and a good summary of OCaml:

OCaml is a general purpose programming language with an emphasis on expressiveness and safety. Developed for more than 20 years at Inria by a group of leading researchers, it has an advanced type system that helps catch your mistakes without getting in your way. It’s used in environments where a single mistake can cost millions and speed matters, is supported by an active community, and has a rich set of libraries and development tools.

Then we recommend reading Part 1 of the free online book Real World OCaml. It will guide you through the language and explore each of OCaml’s major features. However Windows users will not be able to run the book’s code. Instead we suggest you install Diskuv OCaml (discussed next section) and then follow along in our Beyond Basics section.

Once you start writing your own code you will need to know where to look to find libraries (called packages in OCaml). We recommend just browsing the packages at OCamlPro’s OCaml Documentation Hub since it is fairly comprehensive, reasonably up-to-date and has links to most package’s documentation. Just click on its Packages tab and do a text search with Ctrl-F or ⌘-F:

OCamlPro OCaml Documentation Hub Main Index

OCamlPro OCaml Documentation Hub Package Info for AHROCKSDB.0.3.3

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

Discord Server chat room

About Diskuv OCaml

Diskuv OCaml is an OCaml distribution focused on a) secure, cross-platform software development and b) ease of use for language learners and professional developers.

Diskuv, a company creating safe communications solutions, adopted the OCaml language because OCaml is the thought leader for formally verified software (a fancy term for proving that software is secure) while being portable due to compatibility with the C language. However, OCaml development used to require a lot of tribal knowledge. For example the Unison File Sychronizer which can synchronize folders between different operating systems (pretty cool!) was developed in OCaml and has been available on macOS, Linux and Windows for decades. Yet the defacto Windows distribution of OCaml was deprecated in 2021. The online book Real World OCaml solved much of the tribal knowledge problem but you will likely run into some roadblocks. Several companies and groups have filled the void (Jane Street, OCaml Labs, OCaml Pro and Facebook among others). Diskuv OCaml provides a few critical functions:

  1. A way to install a coherent set of software that has been vetted to work together. Especially but not only on Windows.

  2. A way to upgrade that software, usually in response to security patches or critical bug fixes.

  3. A support channel when things go wrong.

Note

The first releases (0.1.x and 0.2.x) of Diskuv OCaml support Windows 64-bit systems only, and should be considered preview releases.

The Diskuv OCaml distribution includes the following OCaml components:

and it also includes some C-language components for the cross-platform tooling we will be releasing in the future:

  • cmake

    CMake, the standard high-level build tool for C and C++ projects

  • ninja

    Ninja, a low level build tool primarily for C projects

  • vcpkg

    vcpkg, a C/C++ package manager for acquiring and managing libraries

The Diskuv OCaml distribution will automatically install the following components if missing from your system:

  • git

    Git, the standard version control for getting, saving and sharing source code.

  • cl, link

    Visual Studio Build Tools, the official Microsoft tools for building modern C/C++ apps for Windows

How to Install

Note

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 2 (two) hours. The Diskuv OCaml 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

Warning

Be prepared to wait for at least 2 hours for the installer to finish. In the meantime you can still use your computer for other things like web browsing.

  1. Open PowerShell (press the Windows key ⊞, type “PowerShell” and then Open Windows PowerShell).

  2. Run the following in PowerShell to download and install the distribution from its Git repository:

    PS> [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;

PS> (Test-Path -Path ~\DiskuvOCamlProjects) -or $(ni ~\DiskuvOCamlProjects -ItemType Directory);

PS> iwr `
  "https://gitlab.com/api/v4/projects/diskuv%2Fdiskuv-ocaml/packages/generic/distribution-portable/0.3.3/distribution-portable.zip" `
  -OutFile "$env:TEMP\diskuv-ocaml-distribution.zip"; `
  if ($LastExitCode -ne 0) { bitsadmin /transfer downloadDiskuvOCamlJob /download /priority normal `
  "https://gitlab.com/api/v4/projects/diskuv%2Fdiskuv-ocaml/packages/generic/distribution-portable/0.3.3/distribution-portable.zip" `
  "$env:TEMP\diskuv-ocaml-distribution.zip" };

PS> Expand-Archive `
  -Path "$env:TEMP\diskuv-ocaml-distribution.zip" `
  -DestinationPath ~\DiskuvOCamlProjects `
  -Force;

PS> ~\DiskuvOCamlProjects\diskuv-ocaml\installtime\windows\install-world.bat -SkipProgress;

    Depending on your Windows “User Account Control” settings your machine may prompt to click “Yes” to install Visual Studio Installer and Git for Windows; you will only be prompted if you or an Administator has not installed those two programs already. The rest of the installation is completely click-free:

    _images/Intro-install-world.png

Install is done! What next?

You have completed the installation of Diskuv OCaml. 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.

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

  3. You may get some harmless warnings (ex. failed to lock file) that you can safely ignore. Now let us try to enter some basic OCaml expressions … be sure to include the ;; and then press ENTER after each line:

    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 Base package, for example, you will get an error:

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

  5. Leave the utop application by typing:

utop #> #quit ;;

Beyond Basics is the topic of the next section.

Indices and tables