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 |