Skip to content
Riot Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.
Install Riot GitHub

RFD0027 - Toolchain Manifest Contract

  • Feature Name: toolchain_manifest_contract
  • Start Date: 2026-03-30
  • Status: implemented

Summary

Section titled “Summary”

This RFD makes riot require manifest.json inside published OCaml toolchain tarballs and use it as the authoritative toolchain identity input to cache hashing.

From this point forward, published toolchains use the Riot toolchain suffixing scheme 5.5.0-riot.<N> (for example 5.5.0-riot.1) to force explicit rebuild epochs. scripts/toolchain/ocaml.sh defaults that suffix to riot.1 when packaging is not explicitly overridden, so consumers resolve and download the Riot artifact family by default.

The contract is:

  • Release toolchains published for ./scripts/toolchain/ocaml.sh must include manifest.json.
  • The file must contain a non-empty toolchain_fingerprint.
  • riot-toolchain must validate manifest presence on install and reject archives that do not contain it.
  • Planner cache keys for downloaded/non-local toolchains must be derived from that fingerprint instead of probing selected filesystem paths.
  • Local source toolchains (explicit Path installs / vendored compiler) remain supported and continue to use path-based fallback hashing.

Motivation

Section titled “Motivation”

Recent cross-compilation failures were traceable to toolchain tarballs drifting from the compiler artifact set expected by the build process (missing sysroot headers/libs). A manifest fingerprint makes it explicit when a compiler bundle is semantically different even if file layout is similar.

This RFD removes ad-hoc probing as the primary identity and makes cache behavior depend on a stable build artifact description carried in the release tarball.

Mechanism

Section titled “Mechanism”
  1. vendor/ocaml/cross/package.sh writes manifest.json during packaging and archives it into every tarball.
  2. riot-toolchain:
    • validates manifest.json after extraction for downloaded toolchains,
    • fails installation if the manifest is missing or invalid,
    • prefers toolchain_fingerprint in hash.
  3. Planner cache keys now fail fast for missing-manifest non-local toolchains, forcing users to install from a republished artifact.

Migration

Section titled “Migration”
  • Re-publish affected OCaml toolchains after this change and upload to CDN.
  • Invalidate stale local toolchain cache directories under ~/.riot/toolchains/... if users previously installed legacy tarballs without manifests.
  • Publish and consume only Riot version-family toolchains by default:
    • bootstrap.py, packages/riot-toolchain, packages/riot-model, and ocaml-toolchain.toml default to 5.5.0-riot.1.
    • Explicitly setting OCAML_VERSION/[toolchain].version remains the override for newer epochs (for example 5.5.0-riot.2).