Environment variables

Everything the compiler, the generated runtimes and the test harness read from the environment.

Moggi reads three groups: its own variables (below), the host toolchain variables it honors when locating java, dotnet and friends, and a few variables the test harness sets. Nothing else is consulted — there is no configuration file, and no per-project settings beyond the compile cache.

Two MOGGI_* names in the source are not environment variables: MOGGI_PROJECT_ROOT is a PHP constant the test harness defines, and MOGGI_TRACE_FRAME_LIMIT is the frame cap emitted into the generated runtimes. Setting either in the environment has no effect.

Moggi’s own variables

MOGGI_ROOT

Overrides where the standard library is looked for. <MOGGI_ROOT>/lib is tried first, and is only accepted if it actually contains base.moggi. Without it the compiler looks for lib/ beside its own installation — for a distribution that is <installation>/lib, next to bin/ — and then next to its own sources in a checkout. Set it when the compiler has been relocated away from its lib/.

MOGGI_MICRO_SFX

Names the micro PHP runtime that moggi compile --backend php --native appends the packaged PHAR to — the PHP counterpart of GraalVM’s native-image for jvm. It accepts the runtime file itself, or a directory holding micro.sfx. A distribution that bundles PHP carries one under runtime/php-native/, which is where the compiler looks when this is unset, so setting it is only needed in a checkout, for an installation whose runtime lives somewhere else, or for the --native test smoke. Without a runtime, --native on php fails with an error naming this variable; it is never a silent fallback to the PHAR.

MOGGI_ALLOW_LOCAL_SOURCES

A release’s source (§4.3 of the registry spec) is the bytes of a package from another origin when the registry does not serve its blob. The release that names it is attacker-controlled in the case that matters — a registry answering 404 for blobs/<digest> can name any source — so the client fetches only ordinary https URLs: git remote helpers (ext::sh -c …), file://, and bare paths are refused. Set this variable to a truthy value (1, true, yes, on) to allow local paths and file:// URLs as well, which is what reproducing a package from a checkout needs. A local source that does not pack to the blob digest reports the expected digest but withholds the one it produced.

MOGGI_REGISTRY and MOGGI_REGISTRY_NPUB

MOGGI_REGISTRY selects the registry for install, update, build, verify and publish; it may be an https URL or a directory, which is how a mirror, a checkout and the canonical registry are one code path.

A registry’s signature proves the root is internally consistent, not that it is the registry you meant. MOGGI_REGISTRY_NPUB pins the signing key, and any difference is refused; without a pin the first key seen for a base is remembered and every later change is refused, so a key that changes after first contact is always an error rather than a silent trust refresh.

MOGGI_ALLOW_STALE_REGISTRY

A signed root carries version and expires (RFC 3339), and the client refuses a root that is past its expiry or below the highest version it has already accepted for that base. That is what makes a frozen or replayed root visible: a signature over an old root verifies exactly as well as one over the current root, so freshness has to be signed and checked rather than assumed.

Set this variable to a truthy value (1, true, yes, on) to waive both checks — for a development registry whose clock or counters are not maintained, or to accept a deliberate downgrade. The highest version seen is still recorded while the waiver is on, so a later run without it compares against the real high-water mark.

MOGGI_CACHE_DIR

Root of the project cache. Defaults to ./.moggi in the current working directory. Trailing slashes are trimmed. One root holds everything moggi keeps between runs, each kind of thing under a directory named for what put it there:

<cache>/fingerprint                                    the compiler that filled the rest
<cache>/compile/<backend>/<source-mirror>.<kind>.mogc  a compilation entry
<cache>/compile/artifacts/<key>.blob                   a whole-project artifact
<cache>/compile/docs-index/<key>.json                  the mogdoc/moogle index
<cache>/docs/                                          `moggi mogdoc serve` output
<cache>/catalog/<registry-key>/                        fetched registry metadata
<cache>/packages/<name>/<digest>/                      an unpacked package
<cache>/runtime/<key>/                                 an artifact a host tool fetched
<cache>/test/                                          the test harness's scratch trees

One compiler owns the tree. fingerprint hashes the compiler’s own sources; a compiler whose fingerprint does not match drops what the compiler derives (compile/, docs/) and keeps what it merely found (catalog/, packages/, runtime/ — all addressed by digest), which is why clearing the cache is never required after upgrading. moggi cache info shows each area and its size, and moggi cache clear [<area>] drops one at a time:

moggi mogdoc serve reuses the same variable as its default output root, writing to <cache>/docs unless --output overrides it.

MOGGI_NO_CACHE

Set it to any value other than empty or 0 to disable cache reads and writes:

MOGGI_NO_CACHE=1 php moggi.php run app.mog

--no-cache / --cache on the command line take precedence over this variable. Useful when bisecting a codegen bug and you want certainty that nothing is being reused.

Host toolchain variables

Read only to find the host executables, and nothing about them is Moggi-specific: the jvm backend uses JAVA_HOME the way any Java tool does, and the dotnet backend uses DOTNET_ROOT the way the SDK does. Both fall back to PATH. Moggi never sets them.

Resolution differs by tool: java and native-image use JAVA_HOME first and fall back to PATH; javap tries command -v first and only then the *_HOME variables; dotnet uses DOTNET_ROOT first, then PATH.

The --backend dotnet fast path assembles with CoreCLR ilasm, which the .NET SDK does not put on PATH by itself. It is found in this order, with no setting of its own: ilasm on PATH, then the runtime.<rid>.microsoft.netcore.ilasm package in the NuGet caches ($NUGET_PACKAGES, $HOME/.nuget/packages, $DOTNET_ROOT/packages), then a one-time Microsoft.NET.Sdk.IL restore that puts that package in the user NuGet cache. When none of them yields a binary — offline, or a platform the RID mapping (<os>-<arch> from PHP_OS_FAMILY and php_uname('m')) does not cover — packaging falls back to dotnet build --no-restore in a workspace under $XDG_CACHE_HOME/moggi, or $HOME/.cache/moggi, or the system temp dir, whichever is writable first.

Test harness

The complete list of what the test harness reads. None is required: every one has a working default.

A case invokes the compiler in-process, or spawns moggi.php for the packaged backends, so the compiler’s own variables apply to a run exactly as they apply to moggi itself.

See development/testing.md for how a run uses them.