ocaml-toolchain.toml and riot toolchain

Riot separates two concerns that are often muddled together:

• what toolchain the workspace expects
• how that toolchain gets installed locally

Those concerns meet in:

• ocaml-toolchain.toml
• riot toolchain

The file: declare intent

ocaml-toolchain.toml is where the workspace records what compiler/toolchain shape it expects.

That is important because a compiler version is not ambient trivia. It affects:

• build behavior
• runtime assumptions
• cross-machine reproducibility

The config file is where that expectation becomes explicit.

The command: materialize the toolchain

riot toolchain is the operational side of the same story.

It is how the local machine moves from:

• “the workspace wants this”

to:

• “this toolchain is installed and usable here”

The most common operation is:

riot toolchain install

Why this split is good

Keeping declaration and installation separate is healthy:

• config stays reviewable
• the local machine can catch up explicitly
• the docs can explain the intended toolchain without conflating it with one machine’s state

That makes the system easier to reason about.

When you end up on this page

Most people land here when:

• a workspace is new
• a machine is new
• the compiler version changes
• the toolchain behavior feels surprising

In all of those cases, the question is the same: “what compiler is Riot trying to use, and how does it get there?”