OCaml Platform Installer

‼️ Disclaimer: This repository is still in alpha. If you encounter any bugs, please report them. 🔧

The OCaml Platform represents the best way for developers, both new and old, to write software in OCaml. It combines the core OCaml compiler with a coherent set of tools, documentation, libraries and testing resources.

This repository contains an installer for the OCaml Platform tools named ocaml-platform. This installer installs all the tools of the Platform in a switch and aims at offering a simplified workflow to work with the different Platform tools.

Trying the Platform

The official guide Up and Running with OCaml explains how to set up a complete work environment for your OCaml projects. It is a necessary reading for every OCaml newcomer.

This set-up goes through several steps, some of which have to be redone for every new project. The ocaml-platform binary, automates and speeds those steps. However, you still need first to install the few dependencies of the OCaml environment, such as a C compiler (such as gcc) and other system tools: bzip2, make, bubblewrap, patch, curl and unzip. In most architecture, you can install them using your package manager, for example on Ubuntu or Debian:

sudo apt install bzip2 make gcc bubblewrap rsync patch curl unzip

You can now run the installer script (which will call sudo for the final installation step):

bash < <(curl -sL https://github.com/tarides/ocaml-platform-installer/releases/latest/download/installer.sh)

Don't hesitate to have a look at what the script does. In a nutshell, the script will install a static binary into /usr/local/bin/ocaml-platform as well as the opam binary if it isn't already installed. Currently, only Linux and macOS (both amd64 and arm64) are supported. We plan on adding more targets soon.

Then, to install the Platform tools inside your opam switch (if you don't know what is a switch, read the Up and running with OCaml guide):

ocaml-platform

If the tools aren't cached yet, this needs to build OCaml itself and the Platform tools, which takes a few minutes. To understand how ocaml-platform works under the hood, go directly to the Under the hood section.

The advantages of using ocaml-platform

The advantages are the following:

• The dependencies of the Platform tools, which are only needed for the development, are not mixed with the dependencies of your project.
• Installing the Platform tools is very fast if you have already installed them for the same version of OCaml in another switch.

Status

The OCaml Platform tools are defined by the "Active" and "Incubate" projects listed here. Each element of the platform lives at a different point in the lifecycle of being a Platform tool. Some "Incubate" projects might duplicate features that are provided by "Active" projects. The aim of the platform is to limit these duplications as much as possible and to document the one blessed way to be productive in OCaml.

To be more specific, for the first iteration of the OCaml Platform we are considering the following tools (to be revisited later, when the policies for governing how projects can go in and out the platform are ready):

• Package manager: opam
• Build system: dune
• Documentation generator: odoc
• Code formatter: ocamlformat
• Release helper: dune-release
• LSP server: ocaml-lsp
• Editor helper: merlin

Note that the following is not yet distributed but is still in the Platform:

• REPL: utop

Getting started

To clone the project, you can run:

git clone [email protected]:tarides/ocaml-platform-installer.git

To run the test, see the README.

What's under the hood

Another disclaimer: the current implementation is a WIP, so what's under the hood may (or may not) change in the future.

Under the hood, ocaml-platform uses several mechanisms to install and cache the platform tools.

The sandbox switch

The sandbox switch is a switch in which the tools will be compiled. The idea of having a separate switch is that the dependencies of the development tools should not interfere with the dependencies of your project.

The platform tools are normally installed into the sandbox switch. Then, the installed files, except for the libraries, are grouped into new opam packages in the local binary repository (see below).

The libraries are left out to get rid of transitive dependencies, which would defeat the goal of not interfering with the dependencies of the project.

The local binary opam repository

As setting up a switch and building all platform tools there is costly in time, they are cached in a local opam repository. This also allows to install the platform tools purely through opam.

The packages in this repository consists of pre-compiled packages with no libraries, so they don't have to be built and their installation consists only of copying files.

The name of the binary package is the same as the original one, but the version is suffixed with +platform. Moreover, when the binary depends on the version of the compiler that built it, this information is also included in the version. For instance odoc version 2.1.1 built with ocaml 4.13.1 could have version 2.1.1-ocaml4.13.1+platform.

The pipeline

When prompted to install the platform tools, for a given switch, ocaml-platform does the following:

• First, it finds for each tool the latest version compatible with the ocaml version of the switch
• Then, it checks which tools have their version already available in the local binary repo, and which tools need to be built,
• If needed, it creates the sandbox switch, to builds the tools it needs to build, and add to the local repository the new packages.
• Finally, it installs all tools from the local binary repository.

Note that this mechanism makes opam fully aware of ocaml-platform's installed package.

Roadmap

You can read a high-level specification for the OCaml Platform here. Our current plan is to release an installer for the Platform tools in sync with OCaml 5.