Skip to content
Molto

The manifest

Every key Project.toml reads, what it emits on the command line, and the limits it refuses to exceed.

One Project.toml sits at the root of a project. Every command searches the current directory and its ancestors for it, so molto build works from any subdirectory. The same file builds on Linux, Windows and macOS: nothing in it is per platform.

The rule the whole file rests on:

Molto discovers your sources; it does not discover your build settings.

Every .c, .cpp and .cc file under src/ and tests/ is compiled automatically — you never list files. Include paths, defines, link libraries and test layout are only what this file says. Nothing is inferred from the directory layout, and there is no fallback to a Makefile.

Relative paths in include and test.sources resolve against the project root, never the directory you ran the command from. flags is passed verbatim by contract and is never rewritten.

What molto new writes

A library by default — molto new my_lib:

[package]
name = "my_lib"
version = "0.1.0"
artifact = "static"

[target]
std = "c17"
include = ["include"]

[profile.debug]
opt_level = 0
debug_info = true

[profile.release]
opt_level = 3
debug_info = false

[test]
mode = "single"   # moltest registers the tests and owns main()

[dev-deps]
moltest = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }

molto new my_app --bin writes the same without artifact, [test] and [dev-deps], and a src/main.c instead of a library and its test. Either is a complete project: there is no second file and no generator step.

[package]

Key Type Notes
name string Required. snake_case, must start with a lowercase letter
version string Free-form; defaults to 0.0.0. Must be semver for a shared library
artifact string executable (default), static or shared. source is refused
description string One line saying what the package is
license string An SPDX expression: MIT, MIT OR Apache-2.0, Apache-2.0 WITH LLVM-exception
homepage string URL
repository string URL
authors array At most 8 entries

name and version reach every translation unit as MOLTO_PKG_NAME and MOLTO_PKG_VERSION, so a program can report its own version without a header to keep in step.

artifact decides what lands in build/<profile>/:

artifact Linux macOS
executable (default) greet greet
static libgreet.a libgreet.a
shared libgreet.so.1.2.3, plus libgreet.so.1 and libgreet.so libgreet.1.2.3.dylib, plus libgreet.1.dylib and libgreet.dylib

On Windows an executable is greet.exe. The three names of a shared library are what a loader reads: a program linked against libgreet.so.1 keeps running when 1.2.3 is replaced by 1.9.0, and does not when it is replaced by 2.0.0. Tests link the objects of src/ either way, so a library is tested exactly like a program; molto run on one refuses, because there is nothing to run.

The last five keys reach no compile line: they are what a catalogue shows and what molto metadata reads to name your licence. [package] fails closed — an unknown key in it is an error naming the key, because a licence dropped in silence would publish a package that claims no licence at all.

[target]

Key Type Emits
compiler string Nothing directly — gcc, g++, clang, llvm or msvc. Absent means autodetect
std string -std= for C sources
cpp_std string -std= for C++ sources
requires array Nothing — capabilities that must prove they compile
include array -I, relative to the project root
defines array -D, in the right form per compiler
link array -l, names without the prefix
flags array Verbatim, to both the compiler and the linker
host array The include directories and link flags of a library the host already has

compiler is a vendor preference, not a binary. Naming a vendor rather than a path is what keeps a manifest portable: gcc is version 9 on one machine and 14 on another. Anything outside that list is an error.

std selects the mode; requires states what has to actually work. Accepting -std=c2x is not the same as implementing it — a compiler may take the flag and still reject [[nodiscard]]. Molto asks pickup which local toolchain proves each capability by compiling a program that uses it, and caches the answer in .bin/wsdb. --refresh-toolchain asks again.

Omitting std inherits the compiler’s default, which differs by toolchain and version. Declare it.

host names a library by capability, never by path — host = ["gtk+-3.0"] — and pkg-config answers where its headers and libraries are on this machine. A value with a / in it is refused: a path is one machine’s layout, and a capability is the same word everywhere. For a library Molto should fetch when the machine lacks it, use a platform package instead.

For a linker flag that is not a library — -Wl,..., or -pthread at compile time — use flags, not link.

Molto picks the C driver for .c and the C++ driver for .cpp and .cc, both from the same resolved toolchain, so a mixed project never mixes compilers. A C++ project whose toolchain has no C++ driver is reported up front, not discovered at link time.

[test]

Key Type Notes
mode string per_file (default) or single
sources array Extra sources compiled for tests only; directories are walked
defines, include, flags array Applied only when compiling tests/
[[test.isolated]] file, replaces table array A test file linked alone, without the sources it replaces

per_file builds one executable per file under tests/, each linked against the project’s objects minus src/main.c, and each supplying its own main(). Output lands in build/<profile>/tests/<name>.

single links everything into one executable at build/<profile>/tests/<package>_tests. That is what a framework which registers its cases and owns main() needs — moltest, taken as a development dependency, reaches the test build by itself.

[[test.isolated]] is for faking a function: the file links into an executable of its own, without the sources it names, so a fake (moltest-mock, fff, or one written by hand) can stand in for them:

[[test.isolated]]
file     = "tests/test_network.c"
replaces = ["src/socket.c"]      # or "dep:src/x.c" in a dependency, or "dep" for all of it

A framework kept in the tree rather than in [dev-deps] is not compiled at all unless sources names it — the most common reason a test build fails on the framework’s own symbols.

[profile.*]

Five profiles exist: debug (the default), release, bench, custom and coverage. Select one with --profile; output goes to build/<profile>/.

Key Type Notes
opt_level integer -O
debug_info bool -g
defines, include, flags array Added on top of [target], never replacing it

Defaults when the table is absent:

Profile opt_level debug_info
debug 0 true
release 3 false
bench 3 false
custom 2 true
coverage 0 true

coverage is also always instrumented: Molto adds --coverage to the compile and link lines of src/ and tests/ itself, and molto test --profile coverage leaves the counters under build/coverage/. Dependencies are not instrumented, so the figure is your code’s. With moltest, moltest-coverage turns them into a report and an optional floor; otherwise point gcovr or lcov at build/coverage/. It needs a GCC- or Clang-compatible compiler.

custom is the place for anything else, sanitizers included — profile flags reach the link line too:

[profile.custom]
opt_level  = 0
debug_info = true
flags      = ["-fsanitize=address,undefined", "-fno-omit-frame-pointer"]

Changing any compile setting triggers a recompile: Molto records the exact command per object and rebuilds when it differs.

[env]

[env]
MY_APP_LOG = "debug"

Keys are variable names and values must be strings. They are exported into the compiler and linker invocations, and into the program under molto run and molto test. They are set only in the child process, so Molto’s own environment is never modified and one project’s [env] cannot leak into another.

Limits

Exceeding one is a manifest error, never a silent truncation — dropping a flag would produce a green build using options you did not ask for.

Limit
Entries in defines / include / flags / requires / test.sources 16
Length of one such entry 95 characters
Entries in link, and the length of one 32 / 63 characters
Entries in [env] 32
[env] name / value length 63 / 255 characters
description / homepage / repository length 255 characters
license length 63 characters
Entries in authors, and the length of one 8 / 127 characters

Unknown keys are dropped without warning

A typo in a key name simply disappears. If a setting seems to have no effect, check its spelling first.

The manifest tolerates unknown keys because RFC-0003 specifies tables this binary does not implement yet, and refusing them would reject manifests that are valid by design.

The exceptions fail closed: [package], [deps] and [dev-deps], where an unknown key, two sources or a version range is an error naming it, and format.json and linter.json. A dependency read wrong is a dependency that silently is not there.

Specified but not implemented

Table or key What happens today
More than one target per project A library and the program that uses it needs two; a manifest describes one
package.artifact = "source" Hard error: serving sources is a recipe’s business
dep.artifact, optional, features, default_features Refused, not ignored
[features], [build-deps], [workspace] Not read
target.triple, per-OS tables Not read — molto build --target picks the platform
profile.lto, strip, sanitizers, warnings_as_errors Not read — sanitizers go in a profile’s flags

Coming from a Makefile

Read CFLAGS and LDFLAGS, and put each piece under the key that owns it. Against a Makefile passing -Iinclude -D_DEFAULT_SOURCE -Wall -Wextra -Wpedantic -pthread and building its tests with a framework that owns main():

[target]
std      = "c2x"
requires = ["attr_nodiscard"]
defines  = ["_DEFAULT_SOURCE"]
include  = ["include"]
flags    = ["-Wall", "-Wextra", "-Wpedantic", "-pthread"]

[test]
mode = "single"

[dev-deps]
moltest = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }

That is Molto’s own manifest, minus the profiles and the isolated tests: the repository builds itself with its own tool.

Troubleshooting

Symptom Cause Fix
fatal error: 'pkg/foo.h' file not found No include path declared include = ["include"]
Tests fail to link, missing or duplicate main The framework owns main() mode = "single"
Tests fail on the framework’s own headers It lives outside src/ Put it in [dev-deps], or test.sources
Expected warnings missing flags not declared flags = ["-Wall", "-Wextra"]
An #ifdef never fires defines not declared Add it to [target].defines
undefined reference to sqrt, pthread_create Library not linked link = ["m", "pthread"]
unknown compiler '…' compiler names a binary Use a vendor, or drop the key
a shared library needs a major version artifact = "shared" without semver Give version a major
has nothing to run molto run on a library molto test runs what exercises it
A key seems to do nothing Typo, or not implemented Check it against the tables above
not inside a molto workspace No manifest here or above molto init