Skip to content
Molto

Dependencies

Exact versions, the two dependency tables, the three kinds of recipe, Molto.lock and the caches behind them.

[deps]
sqlite = "3.53.4"                        # a registry coordinate, at exactly that version
gtk    = "4.14.0"                        # a platform package: each platform's own GTK
http   = { path = "modules/http" }       # a directory you are working on

[dev-deps]
moltest = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }  # only ever in tests/
molto add sqlite                        # the newest release, written into the manifest as exact
molto add sqlite@3.53.4                 # that one
molto add git+https://github.com/moltobuild/moltest#v0.3.0 -d   # a git tag, into [dev-deps]
molto add tinytest --dev --path ../tt   # a local directory, into [dev-deps]
molto remove sqlite

Development dependencies worth knowing

Three packages of the Molto ecosystem exist to be taken as [dev-deps]. None of them reaches what you ship:

Package What it is
moltest The test framework molto new sets up: it registers the tests and owns main() (mode = "single")
moltest_coverage Ends molto test --profile coverage with a report, lcov and JSON, and an optional floor
moltest_mock Fakes for [[test.isolated]] files, the tests that link without the sources they replace
[dev-deps]
moltest          = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }
moltest_coverage = { git = "https://github.com/moltobuild/moltest-coverage", tag = "v0.2.1" }
moltest_mock     = { git = "https://github.com/moltobuild/moltest-mock", tag = "v0.4.0" }

Four rules carry most of the behaviour

Versions are exact. ^, ~ and >= are refused, not interpreted. A range would let a release nobody read enter a build without a diff.

One version per package, across both tables at once. A test binary links src/ objects together with test objects, and two versions there are duplicate symbols.

Dev dependencies are not transitive, and their include directories are placed only on the command line that compiles tests/. A src/ file that includes one fails to compile, on the first build. That is the enforcement, not a documented convention.

Both tables fail closed. An unknown key, two sources, a range, or a key that is specified but unimplemented (artifact, optional, features, default_features) is an error naming the dependency — the opposite of most of the manifest, which drops what it does not know.

Declaring one

[deps]
yyjson = "1.2.32"                                              # shorthand for { version = … }
sqlite = { git = "https://github.com/sqlite/sqlite", tag = "3.50.0" }
http   = { path = "modules/http" }
zlib   = { archive = "https://…", sha256 = "…" }
fast   = { version = "2.0.0", registry = "myorg" }

[registries]
myorg = "https://registry.example.com"

Source keys, exactly one required: version, git, path or archive. Modifiers: branch / tag / rev alongside git and at most one of them, sha256 required with archive, and registry which must be declared in [registries].

The flags of molto add spell the same keys, so what you type and what lands in the manifest match. add and remove edit lines rather than rewriting the file: comments, alignment and key order survive, re-adding a name at a new version replaces it in place, and any edit that would leave an unreadable manifest is refused before the file is touched.

recipe.toml

A dependency that is not a Molto package describes itself with a recipe: served by the registry for a coordinate, or at the root of the source for a path or git dependency — one without it is refused with exactly that message. A recipe takes one of three forms, declared rather than inferred:

form What it describes Consumed by Molto
source Sources to fetch and compile as part of your build — SQLite, zlib, libpng Yes
platform Files each platform’s own repository already publishes — GTK Yes
binary An artifact already built and stored in the registry — toolchains and tools By pickup

A source recipe

schema  = 1
form    = "source"
kind    = "package"
name    = "sqlite"
version = "3.53.4"
target  = "any"

[source]
archive = "https://sqlite.org/2025/sqlite-amalgamation-3530400.zip"
sha256  = "…"
compression_format = "zip"                     # zip | tar | tar.gz | tar.bz2 | tar.xz | tar.zst
strip_prefix = "sqlite-amalgamation-3530400"

[build]
system = "none"                                # make | cmake | autotools | meson | none

[artifacts]
type    = "source"                             # source | static | shared
sources = ["sqlite3.c"]
exclude = ["shell.c"]
include = ["."]
link    = ["m", "pthread"]
defines = ["SQLITE_THREADSAFE=1"]

Only [artifacts] type = "source" can be consumed today. Molto compiles the drop as its own translation units, merging the recipe’s includes, defines, flags and links into the build. static and shared are refused with a message, and so is any [build] system other than none: no build system is ever run. Nothing in Molto invokes make, cmake or meson.

A recipe never carries a script. Not for unpacking, not for building. That is why compression_format names a bounded set and [build] names a system rather than a command line — a recipe that could run a string would make every dependency a remote execution.

compression_format is declared, never inferred: a URL may end in .zip and serve a tarball. Absent means infer from the extension, for recipes written before the key existed.

[[provide]] covers the library whose configure only writes one header that upstream already ships under another name — libpng’s pnglibconf.h, pcre2’s config.h. It copies a file the source contains into place before anything compiles, reading none of it and running nothing:

[[provide]]
file = "pnglibconf.h"
from = "scripts/pnglibconf.h.prebuilt"

A platform recipe

molto add gtk

GTK is the case neither other form can serve: building it means running its own build system, and re-hosting it would make the registry redistribute binaries it did not build. Every platform already publishes it, so a platform recipe pins, for each one, the exact files that platform’s repository serves — each with its SHA-256 — and what a consumer compiles and links with:

Platform Files Runtime
Ubuntu, Fedora, Arch The development packages: headers and .pc The host’s own GTK, linked by soname
Windows MSYS2 packages, the whole closure Bundled; DLLs copied beside the executable
macOS (arm64) Homebrew bottles, the whole closure Bundled, found through an rpath

The host is asked first: when pkg-config finds GTK with its headers, that is what is used and nothing is downloaded. Otherwise Molto picks the platform this machine matches, downloads the files with curl into its cache, verifies every digest, and unpacks them itself — .deb, .rpm, pacman packages and bottles. No package manager runs, and nothing inside a package does: maintainer scripts and install hooks are never read. Bottles are relocated and signed again, because their library paths name Homebrew’s own prefix.

A recipe like this is long, so it is generated rather than written: a script reads each repository’s index and pins the closure. The specification is RFC-0022.

[about] is where a dependency’s licence comes from, and molto metadata reports exactly what it finds there. A recipe declaring none produces a component with no licenses field — silence rather than a claim.

Resolution

  1. Read [deps], [dev-deps], and Molto.lock if it is there.
  2. For a coordinate, ask the registry once per name. Without @<version>, molto add picks the newest by semver precedence, not string order, and writes that number into the manifest.
  3. Fetch what is not cached, walk each recipe’s own [deps], and repeat.
  4. Refuse a resolution the lock disagrees with; write Molto.lock otherwise.

Two versions of one package is your decision, not Molto’s. There is no range to widen and no highest version to pick, so the message’s whole job is to say who asked for what:

molto: sqlite is required at two versions
    3.50.3  ← your Project.toml
    3.53.4  ← required by http 1.2.0

Molto.lock

Generated, committed, sorted by name, every list ordered — so its diff is worth reading, which is the whole point of committing it.

version = 1
root = "app"

[[package]]
name = "a"
version = "1.0.0"
source = "registry+https://…"
checksum = "…"                # omitted for a path dependency, never written empty
scopes = ["runtime", "dev"]
dependencies = ["b"]

A lock that is absent, unreadable, not valid TOML, or from a newer format is treated identically: resolve again. A lock whose direct dependencies no longer match the manifest is stale, and re-resolved rather than patched.

The caches

Path (Linux and macOS) What
~/.cache/molto/sources/<name>/<version>/<target> A fetched tree, once per coordinate, stamped on completion
~/.cache/molto/objects Objects compiled from dependencies, keyed by the full compile command
~/.cache/molto/platforms/<name>/<version>/<platform> A platform package, unpacked and stamped
~/.cache/molto/downloads The files platform packages are made from, by digest
~/.config/molto/credentials.toml The registry token, mode 0600

On Windows all of it lives under %APPDATA%\molto, the cache in cache\ beneath it. $MOLTO_CACHE relocates the cache, $MOLTO_HOME everything. A directory without its stamp is the remains of an interrupted fetch: removed, not read.

The object cache covers dependencies only. Reusing an object requires knowing that the source and every header it includes are identical, and for a dependency the coordinate answers for the whole immutable tree. A project’s own sources are mutable and their header graph is unknown until the compiler has run — that is ccache’s problem, and Molto does not try to be one. A path dependency is excluded for the same reason: its bytes are whatever is on disk right now.

Fetching shells out to curl, tar, unzip and git — the same reasoning as shelling out to a compiler rather than linking one — and to zstd for platform packages, which every Linux they serve has in its base install and which Molto fetches once into its cache on Windows.

The registry

Reads are public; only publishing needs a token. molto login exchanges email and password for one, or stores one pasted from the account page with --token. The token never appears in argv: ps is world-readable, so the header goes through a curl config file created 0600 and deleted afterwards.

molto publish sends the blob first and the row last; --pack <dir> makes the archive first. A source or platform recipe is the whole artifact, so it is sent alone, with no archive at all. --dry-run reads and checks without sending, which is the only way to check a recipe — a published coordinate is immutable.