---
tags: drafts
---

# OCaml Platform RFC (draft)

Recent initiatives have accentuated painpoints related to the installation and usage of OCaml Platform. These painpoints also echo common users feedback and conclusions drawn from the OCaml survey.

This document is an RFC on solutions to address these painpoints and define a clear roadmap for the OCaml Platform.

We assume there are already some plans for the future of OCaml Platform. It is not our goal to challenge what has already been carefully thought-off, but rather to align everyone on the vision for OCaml Platform and understand how the issues described here are going to be solved. Hence, all of the suggestions in this document should be understood as merely conversation starters.

The list of OCaml Platform tools is well detailed [here](https://ocaml.org/platform/), but to be specific, we are considering the following subset to be the typical tools installed in a development environment:

- Opam - Package manager
- Dune - Build system
- Utop - OCaml toplevel
- Merlin - Syntax completion
- Odoc - Documentation generator
- Mdx - Markdown code block execution
- LSP - OCaml's Language server protocol
- OCamlformat - OCaml formatter
- Dune-release - CLI to release packages on Opam

We are intentionnally ommitting Platform tools such as `ppxlib` as they are to be installed as a library with Opam, and are less impacted by the problems we are discussing here.

### Problems

#### The installation of the Platform is not unified

- Of all the Platform tools, Opam is a special case. It can be installed from pre-compiled binaries, and the rest of the tools depend on Opam to be present. This causes the initial setup to be split in two parts: Opam installation, and the other tools installation.

- The fragmentation of the platform tools in ~10 different tools is a barrier for new users.

- It is not obvious for new users what the ideal project setup is and how to make it compatible with platform tools.

- Some tools need to be installed in the current switch (dune, utop), while others can be global.

#### The installation of the Platform tools is not the same on all platforms

- Opam is not installable on Windows (without Cygwin that is), hence the setup of OCaml Platform is not the same depending on the platform.

#### Some tools depend on the project or environment

- Ocamlformat's version depends on the user's project version. This causes users to have multiple ocamlformat installed, typically, one per opam switch

- Ocamllsp depends on merlin, which will depend on the OCaml compiler version. This will cause users to have multiple versions of merlin and ocamllsp installed, typically, one per opam switch.

#### Some tools can conflict with the project dependencies

- The tools can only be installed from Opam for now. They also have a lot of dependencies, this causes the tools to conflict with users projects in some cases, and some of the tools conflict with each other (e.g. the latest versions ocamlformat and mdx are not compatible)

#### The Platform installation is too long

- Between the installation of Opam, the compilation of the compiler, the installation and compilation of all of the tools, the setup can take 15 minutes. This is not acceptable in the context of VSCode for instance, where we want to install everything for the user: they would open VSCode and need to wait 15min.

- The creation of new projects, with a local sandbox (local opam switch) takes 2 to 5 minutes.

### Requirements

From the list of problems above, we derive a list of requirements for OCaml Platform

- The installation of OCaml Platform should be fast
- The installation of OCaml Platform should be a single step
- The Platform tools should be independent of the users' projets or environment
- The latest versions of all of the platform tools should be usable at the same time
- The creation of new projects with local sandboxes should be fast and straightforward

### Solutions

#### Installation speed

- The compiler should be cached
- Need to make the compiler relocatable
- Long term solution
- OR Need to apply the "path trick" Esy uses to relocate a pre-compiled compiler
- Short term solution
- The compiler should be downloaded instead of compiled
- Need to create a CI that compiles all of the versions of the compiler and store them on a server.
- The compiled platform tools should be cached
- Need to store/install the platform tools outside of the current sandbox
- Who would this impact? VSCode extension, LSP itself, Emacs users?

#### Installation ease

- Create a script to install the platform tools
- Who manages updates?
- How to uninstall?
- OCaml Platform would still be fragmented
- OR Create a CLI that aggregates the platform tools
- Can it be Dune?
- There's already a subcommand dune utop. Could we have one for other platform tools?
- But then it depends on Opam, and Dune so the setup is still splitted in several steps
- Also, we don't think Dune maintainers will want to deal with binary installation
- Can it be opam?
- As a plugin? But then it depends on Opam, so the setup is still splitted in several steps
- Another tool?

#### Dependency conflicts

- The platform tools should not have any dependencies (apart from Dune?)
- OR The platform tools should be distributed as pre-compiled binaries and are not intended to be installed with Opam
- OR The platform tools should be installed from Opam in a dedicated switch, and then extracted outside of this switch

### Proposed Solution

In this section, we describe a solution that tries to address all of the requirements of the ideal user path, while picking what seems like a reasonable set of solutions from the above list. There could be many solutions to the existing problems, and this proposed solution is only there as an example.

We propose to develop a new tool called ocaml-platform (the name is not important). This tool has the following properties:

- Is installable from pre-compiled binaries.
- Knows how to install opam on both Unix and Windows
- Knows how to create new switches quickly
- Could use an opam plugin that downloads and relocates compilers to create switches
- Can install platform tools on the user's system
- Downloads pre-compiled binary for the tools
- OR Uses the fast switch creation method to compile the platform tools from sources
- Knows how to create a new project that use the platform tools
- Can delegate this task to another platform tool
- Can act as proxy for platform tools
- Think gcloud or aws that provide subcommands for each of the services, where each service has a state (alpha, beta, etc.) and its own API.
- Can proxy to different version of a tool (for merlin, ocamlformat or ocamllsp)
- When proxying, if the tool or the correct version is not installed, install it automatically

With this tool, installing OCaml platform and starting a new project could look like this:

brew install tap/ocaml/up # Or winget install ocaml/up
ocamlup setup # Install Opam, downloads the compiler, the latest versions of platform tools, etc.
ocamlup init # Create a new project, with a local opam switch, with a setup that is compatible with platform tools

And it could be used like this:

ocaml-platform lsp # Start the LSP server compatible with the current switche's ocaml version
ocaml-platform format # Run the ocamlformat binary compatible with the current project's ocamlformat version
ocaml-platform build # Install dune in the current switch if not present and run it

## bootstrap process

- local switch setup
- fine if the user already has a sandbox
- problem is for users that dont have an opam switch. Need to create a switch for first time users.

There are two possibilities on VS Code startup:

- opam exists and is initialised
- current status quo works -- just use it

- opam isnt initialised
- this is the first time user case that wont
- our ideal situation is a project-local installation.
- if we compile a local switch then we need to compile a local compiler.
-