lang::mote
lang/src/mote.mo
Mote manifests, read by the self-hosted compiler.
A mote is Monad's unit of distribution (plans/packaging/ package-system.md): a directory with a mote.toml and a src/ tree.
This module answers the two questions module resolution asks -- which
mote does this file belong to, and which motes did that mote declare --
so that use can be checked against the manifest rather than against
whatever happens to exist on disk.
Built on lang.toml's parser, following lang/src/toml.mo's own
pattern: own types, own glue over Toml.parse, no shared
serialize/deserialize class machinery.
pub struct MoteManifest {
name : String,
/// `[mote] version`, or `""` when the manifest declares none. A git or
/// registry dependency's `mote.lock` entry needs it (`package-system`
/// §2b), and the lock is written from the DEPENDENCY's own manifest,
/// so this has to be readable rather than assumed.
version : String,
/// The mote's directory as a `Path`. The working directory is spelled
/// `.` -- an empty `Path` is never constructed -- and every join from it
/// goes through `Path.child_under`, which keeps the spellings this walk
/// has always produced (`src/lib.mo`, never `./src/lib.mo`).
dir : Path,
deps : List String,
/// Where each declared dependency COMES FROM: the parsed source of
/// every `[dependencies]`/`[dev-dependencies]` entry that names one
/// (`path`, `git`, or a registry version). An entry naming none -- an
/// empty table, or `workspace = true` before inheritance resolves it
/// -- is declared but has no entry here; an entry that is malformed
/// has its error in `dep_errors` instead.
deps_full : List (Pair String Dependency),
/// `(name, message)` for each dependency entry that cannot be read as
/// a source: `path` and `git` together, more than one of `tag`/
/// `branch`/`rev`, a git-only key without `git`, or a non-string value.
/// The parse is pure and stays total, so the error is carried rather
/// than failing the whole manifest; `validate_module_deps`
/// (lang/module.mo) reports it when a `use` reaches that dependency.
dep_errors : List (Pair String String),
/// Where each declared dependency LIVES: `(name, dir)` pairs, computed
/// from `deps_full`. A `path` dependency's `dir` is its `path` joined
/// onto this mote's own `dir`, so it is usable as a path exactly as
/// stored. Any other source is ABSENT from this list -- a git
/// dependency until its checkout is resolved, a registry one until a
/// registry exists -- which resolution reads as "declared, but not
/// located": the name still satisfies `declares` (so a `use` on it is
/// legal), it just has no directory to resolve into. There is no
/// sentinel directory, because an empty `Path` is never constructed.
///
/// Without this, a dependency resolved purely by the NAME convention
/// (`mote_relative_file`: the mote's directory is its name, at the
/// working directory), which is only true from a checkout root. This
/// is what `resolve_module_file` consults on its miss path, and it is
/// what makes resolution key off the mote root rather than the CWD.
dep_dirs : List (Pair String Path),
/// `[features]` entries, in manifest order.
features : List (Pair String (List String)),
/// Optional/feature policy for each `[dependencies]`, `[dev-dependencies]`
/// and `[script-dependencies]` entry, keyed by dependency name.
dep_policies : List (Pair String DepPolicy),
/// C libraries this mote links against, from `[link] libs = [...]`.
/// A LINK-time property of the package, not of any one declaration:
/// which C functions a module calls is `#[extern "c"]`'s business,
/// but what the linker is handed is the mote's, the same way Cargo
/// keeps `-l` flags out of `extern "C"` blocks.
link_libs : List String,
/// pkg-config packages that say WHERE `link_libs` live, from
/// `[link] pkg-config = [...]`. `llvm.link`'s `link_ir` asks
/// `pkg-config --libs-only-L` for these and passes the `-L` flags
/// itself, so a mote's link does not depend on the caller's
/// environment happening to carry the right search path. The names in
/// `link_libs` still supply the `-l` flags.
link_pkgs : List String,
/// Where this mote's library root would be: `[lib] path`, else the
/// conventional `src/lib.mo`. `none` only for an inline mote, which has
/// no `src/` tree at all.
///
/// A PATH, not a promise that the file is there: `manifest_of_table` is
/// pure and cannot probe the filesystem. Whether it exists is
/// `gate_mote_targets`' question (lang/module.mo).
lib_path : Option Path,
/// This mote's runnable scripts, from `[[script]]`. A script is a
/// single source file built with this mote's dependency closure and run
/// by name (`monad script <name>` / `monad s <name>`). A virtual
/// workspace root may declare them too; see `Mote.scripts_at_path`.
scripts : List ScriptTarget,
/// This mote's binary targets, from `[[bin]]` (or the legacy singular
/// `[bin]` spelling, which means the same thing here). Empty only for an
/// inline mote, whose own file IS its binary.
///
/// A manifest with no bin table at all still gets exactly ONE target --
/// the conventional `src/main.mo`, named after the mote -- so
/// `monad build <mote>` works without a manifest edit. Whether that file
/// exists is what `build_target` checks before building it, which is what
/// keeps a default from becoming an invention.
bins : List BinTarget,
/// `[mote] targets = [...]`: the build PROFILES this mote's side effects
/// are implemented for (`"web"` for the browser boundary). Informational
/// only -- availability is enforced per extern/native at codegen
/// (`validate_native_target_availability`), not per mote, because a
/// mote's pure parts (an ABI spec, a generator) must stay usable on
/// every target. Do not confuse it with `Mote.target_roots`, which is
/// about SOURCE files.
targets : List String,
/// Names whose dependency entry said `workspace = true`. Recorded even
/// after resolution so a driver can explain where an inherited edge came
/// from; empty for an ordinary manifest.
inherited : List String,
/// The workspace root whose `[workspace.dependencies]` resolved
/// `inherited`, when one was used. `with_locked_dirs` reads that root's
/// `mote.lock` rather than this mote's own.
workspace_root : Option Path,
}What resolution needs from a mote.toml: who this mote is, where it
lives, and what it declared. [dependencies] and [dev-dependencies]
are merged here -- the distinction is about which TARGETS may use an
edge, and this corpus has no lib/test target split to enforce it
against yet (init/src/tests.mo is an ordinary module). Merging keeps
init pure in its manifest, which is the part that documents intent.
pub struct BinTarget {
/// `[[bin]] path`, or `src/main.mo` when the entry names none, joined
/// onto the mote's own `dir` the same way `dep_dirs` entries are.
path : Path,
/// `[[bin]] name`, or the mote's own name when the entry names none. Not
/// optional: it is what `monad build <mote>` names the output after, so
/// the fallback to a source file's own stem is the FILE compile's rule
/// and no longer this one's.
name : String,
/// `[[bin]] features = [...]`: this target's feature selection.
features : List String,
}One binary target: what monad build selects between.
Both fields are already resolved -- a declared value or the conventional
default, joined onto the mote's own dir -- so a consumer needs no rule
of its own. plans/packaging/package-system.md §2a is the spec.
pub def BinTarget.target_path (b : BinTarget) : PathBinTarget.path, and its name sibling below. Accessors rather than
bare field reads because a #[test] def ... : Bool body reading a field
directly is the shape test-def-struct-field-access-codegen warns about
(the def can be emitted with the FIELD's LLVM type as its return type).
A one-line accessor whose return type IS the field's type costs nothing
and sidesteps it.
pub def BinTarget.target_name (b : BinTarget) : Stringpub def BinTarget.target_features (b : BinTarget) : List Stringpub struct ScriptTarget {
name : String,
path : Path,
mote : Option String,
/// `[[script]] features = [...]`: this script's extra features.
features : List String
}One [[script]] entry: a named single-file program built against the
manifest's dependency closure. path is joined onto the manifest's
directory; mote optionally names the member whose manifest and closure
the script uses (recommended at a virtual workspace root).
pub def ScriptTarget.script_name (t : ScriptTarget) : Stringpub def ScriptTarget.script_path (t : ScriptTarget) : Pathpub def ScriptTarget.script_mote (t : ScriptTarget) : Option Stringpub def ScriptTarget.script_features (t : ScriptTarget) : List Stringpub type Dependency {
path (dir : Path),
git (url : String) (tag : Option String) (branch : Option String) (rev : Option String) (subdir : Option String),
registry (req : String),
}Where a declared dependency comes from: the canonical model of
plans/packaging/package-system.md §2a, which mote.lock shares.
path's dir is already joined onto the declaring mote's dir, the
way dep_dirs entries always were. git's tag, branch and rev
are mutually exclusive, and none of them means the remote's HEAD;
subdir names the mote's directory inside a checkout that holds
several. registry carries its version requirement verbatim -- nothing
resolves one yet. workspace = true is never a constructor here:
inheritance is resolved before a Dependency exists.
pub def Dependency.to_source (d : Dependency) : StringA one-line spelling of the source, in the lockfile's source style:
path+<dir>, git+<url>?tag=v1&subdir=motes/x, registry+<req>.
For display and diagnostics only; nothing parses it back.
pub def MoteManifest.dependency_of (m : MoteManifest) (name : String) : Option DependencyThe dependency named name's parsed source, if its entry named one.
pub def MoteManifest.dep_errors_for (m : MoteManifest) (name : String) : List StringThe errors recorded against the dependency name; empty when its entry
is well-formed or absent.
pub def MoteManifest.dep_dir_of (m : MoteManifest) (name : String) : Option PathThe directory a declared dependency lives in, or none when the mote
does not declare name or its entry carries no path. A dependency
with no path is DECLARED but not LOCATED, which is not an error here:
the name-convention cascade above is still allowed to find it.
A mote's OWN name answers with its own dir, the same "a mote may
always refer to itself" rule MoteManifest.declares already states --
and here it is load-bearing rather than a convenience: prelude
belongs to init (mote_dep_files routes it there, since prelude is
the one module whose NAME is not its FILE name), and init is exactly
the mote that cannot declare itself as a dependency. Without this arm
the prelude of the mote init is unreachable from inside init/
itself, which is why monad check src/list.mo from init/ reported
unknown variable '==' in List.get.
The self arm answers even for the mote whose mote.toml sits in the
working directory: that is precisely the case it exists for, and the
manifest's dir spells that directory ..
pub def Mote.discover_config_target_dir (dir : Path) : IO (Option Path)Walk up from dir for the monad tool's own config, .monad/config.toml,
and answer the [build] target-dir it names, joined onto the config's
directory so the value is usable as stored.
A TOOL setting, not a mote's. Where output goes is a property of the tool
that writes it, so it is read from the tool's config rather than from the
mote.toml of whichever mote is being built -- which also means this walk
has no mote boundary to stop at. That is what makes it the right lookup
for a script-mode file: monad build examples/hello.mo must land where
the rest of the tree does, and examples/ sits under no [mote] for
Mote.discover to find.
A config that names no target dir does not stop the walk, so a nested
.monad/config.toml inherits from the one above it -- the same rule a
manifest used to follow for its workspace.
pub def Mote.target_roots (m : MoteManifest) (fallback : Path) : List PathThe directories a mote's own declared targets live in: the [lib]
root's, then each [[bin]]'s, deduplicated in that order.
This is what a bare monad check/monad test covers, and it covers it
because the alternative was the whole subtree. Walking the mote's
DIRECTORY swept every *.mo under it, and .mo is also GNU gettext's
extension -- so in any project that has run devenv shell (which
materializes .devenv/bash-bash/share/locale/*/LC_MESSAGES/bash.mo),
monad test reported 85 parse failures beside the 2 real files
(plans/implementations/2026-10-04-monad-test-no-path-globs-unrelated- dot-mo-files.md). A declared target is the mote saying where its own
sources are; nothing else under the directory is its business.
fallback (the mote's own directory) is the answer for an inline mote,
which declares no targets at all. An explicit path argument never
reaches here -- monad test . still means that directory, literally.
pub def Mote.native_test_roots (m : MoteManifest) (fallback : Path) : List PathThe subset of target_roots a NATIVE driver may compile. The [lib]
root is always included (a web mote's pure test files still run
natively); a [[bin]] root is included only when the mote's
[mote] targets admit the native profile (absent, or containing
"native"). A targets = ["web"] bin is not native-testable -- that is
the anidoku gap where monad test compiled a web-only bin for the
native driver.
pub def Mote.web_only_bin_file (m : MoteManifest) (file : String) : BoolWhether file is a declared [[bin]] target of a mote whose
[mote] targets exclude the native profile. The native test driver
must not compile such a file (a web-only bin reaches web_* externs);
the root-level filter in native_test_roots cannot exclude it when the
bin and the tests share src/, so the walk filters the FILE too.
pub def Mote.dir_above (dir : Path) : Option PathThe directory one step up in the policy/config walks, which keep going
ABOVE the working directory: . ascends to .. and a ..-relative
directory keeps appending (raw_parent_dir ".." is ., which would
otherwise re-probe the cwd forever). none at the filesystem root.
pub def Mote.manifest_at (dir : Path) : IO (Option MoteManifest)The manifest AT dir, with no walk -- unlike Mote.discover, whose
walk is right for a file's own mote and wrong for a DECLARED dependency:
[dependencies.x] path names x's directory, so a manifest further up
is somebody else's. Resolution needs the dependency's own [lib] path.
pub def Mote.workspace_members (dir : Path) : IO (List Path)Every mote directory belonging to the workspace rooted at dir.
Mirrors the Rust reference's Workspace::resolve_members
(rust/core/src/term/mote.rs): each [workspace] members entry is a
directory relative to the root, except a trailing /*, which
expands ONE level to those children that are themselves motes (a
directory containing a mote.toml). IO.list_dir already returns
entries sorted, so the expansion needs no sort of its own.
List.empty when dir holds no manifest, or one with no
[workspace] members -- a single-mote checkout is not an error,
just a workspace of one, and the caller decides what to do about
that.
A member that does not exist is DROPPED rather than reported: the Rust reference errors, but this is the test runner's path enumeration, where a stale entry should not stop the other members from being tested. The caller sees a shorter list, and the manifest is checked by the Rust host in CI anyway.
pub def Mote.affine_mode_of_path (file : Path) : IO AffineModeHow a mote enforces the affine-by-default usage rule, from
[affine] mode in its nearest mote.toml.
The default -- no manifest, no key, a parse error, or any value other
than "warn" -- is affine_error. A typo must never silently
weaken enforcement, so only one spelling opts out.
This deliberately does not go through Mote.discover. That walk
returns none at a virtual workspace root (a mote.toml with no
[mote]; see Mote.discover_go), which is exactly the manifest a
file outside every member resolves to -- this repository's
examples/, for one. The policy walk stops at the nearest
mote.toml whether or not it declares a [mote], so a workspace
root can carry the fallback and a member can override it.
pub def Mote.scripts_at_path (file : Path) : IO (Option (Pair String (List ScriptTarget)))The nearest manifest and its [[script]] entries, whether or not that
manifest declares [mote] (a virtual workspace root may own scripts).
Mote.discover cannot answer this: it returns none at a virtual root.
pub def Mote.affine_mode_of_text (text : String) : AffineMode[affine] mode in a manifest's text. See Mote.affine_mode_of_path
for why every non-"warn" answer is the strict default.
pub def Mote.manifest_of_table_in_workspace
(dir : Path) (root_dir : Path) (root_table : BTreeMap String Toml.Value)
(table : BTreeMap String Toml.Value) : Option MoteManifestmanifest_of_table with a workspace root in hand: workspace = true
entries are replaced by the root's [workspace.dependencies] entry. Kept
as a separate entry point so callers with no workspace context keep the
pure signature.
pub def Mote.workspace_member_names (root_dir : Path) : IO (List String)pub def Mote.workspace_root_of (dir : Path) (name : String) : IO MoteRootLookupWalk up from dir for the first manifest with a [workspace] table and
decide whether name (the manifest being loaded) belongs to it.
root_found gives the root and its parsed table; root_rejected names a
root that exists but does not list this package; root_none means there
is no root above.
pub def Mote.load_manifest (dir : Path) (text : String) : IO (Option MoteManifest)Read a manifest, resolving workspace = true entries against the
workspace root above it. The pure parse_manifest stays available for
callers with no filesystem; this is the loader's entry point.
pub def Mote.workspace_member_dirs (dir : Path) : IO (Option (List Path))The member directories of the workspace rooted at dir, or none when
dir has no [workspace] table. Used by monad fetch, which is handed a
virtual root and must resolve every member's dependencies.
pub def Mote.manifest_problem (dir : Path) : IO (Option String)The first unresolved-inheritance problem for the manifest at dir, as a
finished diagnostic. none means either there is no such problem or the
manifest uses no workspace = true.
pub def Mote.git_checkout_dir (home : String) (url : String) (commit : String) : String<home>/cache/git/checkouts/<sha256 url>/<commit> -- the one
definition of where a checkout lands, shared with build::git's
writer so a fetch and a resolution cannot disagree.
pub def Mote.with_locked_dirs_at (home : String) (m : MoteManifest) : IO MoteManifestwith_locked_dirs with the cache root given. The test suite needs it:
a fixture fetches into its own directory, and nothing in a test may
depend on the process's $MONAD_HOME.
pub def Mote.any_git_dep (deps : List (Pair String Dependency)) : BoolWhether any declared dependency is a git source -- the gate that keeps the lock read off every ordinary mote's resolution path.
pub def Mote.script_targets_of_text (dir : Path) (text : String) : List ScriptTargetParse a manifest's text for [[script]] entries. Used at a virtual
workspace root, where Mote.discover returns none.
pub def Mote.script_dep_names (root : BTreeMap String Toml.Value) : List StringThe dependency names declared by [script-dependencies.<script>].
They are merged into the owning manifest's closure for resolution, so a
script can use them like any declared dependency.
pub def Mote.script_dep_entries (dir : Path) (root : BTreeMap String Toml.Value) :
List (Pair String ManifestDepEntry)pub def read_file_or_none (path : Path) : IO (Option String)A file's contents, or none when it is not there at all (not_found)
-- "no ~/.monad/active", "no mote.toml in this directory" are the
ordinary states every caller here probes for.
Any OTHER read failure is reported on stderr before it reads as
absent: the callers' own types (Option MoteManifest, a member list)
have no error channel, and an unreadable manifest must not pass
silently for a missing one.
pub def Mote.toolchain_root : IO (Option String)Where an installed toolchain's mote sources live, if there is one.
$MONAD_ROOT first, honoured VERBATIM and deliberately neither
existence- nor shape-checked: an explicit variable is an instruction,
and a user who points it somewhere useless should get an ordinary
"unknown module" listing the candidate paths rather than a silent
fallback to a ~/.monad they may not even have. It is also the one
root a test can install with nothing but a shell variable.
Otherwise monadup's install: $MONAD_HOME (default $HOME/.monad),
the tag its active file names, and <home>/downloads/<tag> -- which
IS existence-checked, because that one is a guess rather than an
instruction.
none, never an error: a development checkout has no ~/.monad, and
resolution reads "no root" as "no candidates from this tier".