3 · CLI reference

Synopsis

amc [options] file1.am [file2.am ...] -o <output>     # compile
amc <subcommand> [args...]                            # other commands

The compiler always emits a .c file. To produce a native binary, follow up with gcc:

amc hello.am -o hello                                    # → hello.c
gcc -Iruntime hello.c -lgc -lm -o hello           # → hello (binary)
./hello

The runtime headers live in runtime/ at the project root.

Subcommands

Each subcommand handles its own flags and exit codes; consult the referenced chapter or --help for the full surface.

amc package <action> (alias amc pkg)

Project-local package operations. All actions read/write amalgame.toml (deps) and amalgame.lock (resolved Git SHAs) in the current working directory.

amc test auto-installs any missing deps before running the suite, and links each package's [stdlib].sources vendored C objects into every test binary — backends like SQLite "just work" without manual gcc flags. Since v0.5.3, .cpp / .cc / .cxx sources are compiled with g++ (and the final test link goes through g++ when any package contributes C++), so DuckDB-style packages vendoring a C++ amalgamation work out of the box too.

amalgame.toml manifest reference

A package's amalgame.toml describes both its own metadata ([package]) and the surface it contributes to consumers ([stdlib]). A user project's amalgame.toml typically has just [package] + [dependencies].

[package]
name              = "amalgame-database-duckdb"
version           = "0.1.0"
license           = "Apache-2.0"
required-amalgame = ">=0.5.3"   # refuses install on older amc
schema-version    = 1           # refuses install on amc < this schema

[stdlib]
class     = "DuckDB"
header    = "runtime/Amalgame_Database_DuckDB.h"
namespace = "Amalgame.Database.DuckDB"
sources   = ["runtime/Amalgame_Database/duckdb/duckdb.cpp"]
cflags    = ""                  # extra flags for .c sources
cxxflags  = "-O3 -DNDEBUG -std=c++17"  # extra flags for .cpp/.cc/.cxx
libs      = ["stdc++"]          # bare names → -l<name> at link time

[stdlib.functions]
Open     = { returns = "AmalgameDuckDB*" }
Close    = { returns = "void" }
# Optional `returns_generic` (v0.8.40+) carries the AM-level
# generic shape so chained `.Get(i).Get(j)…` on the consumer side
# infers typed casts instead of falling through to `(void*)`.
# Example: `QueryAll` returning rows-of-columns of strings.
QueryAll = { returns = "AmalgameList*", returns_generic = "List<List<string>>" }
# …

required-amalgame operators (v0.6.0+)

The constraint string follows npm/Cargo conventions. Examples:

Unrecognised operators are treated as "no constraint" (returns true) to keep older amc binaries compatible with future syntax extensions.

Auto-resolve amc package add <pkg> (v0.6.0+)

When the @<tag> suffix is omitted on an indexed shortname, amc fetches the index and picks the latest tag whose required-amalgame is satisfied by the running amc:

$ amc package add duckdb
Auto-resolved 'duckdb' → 'duckdb@v0.1.1' (latest compatible with amc 0.6.0)
…

Full git URLs still require an explicit @<tag> — the index is the SoT for "what amc knows about", and unindexed repos opt out of auto-resolve by design.

If no version is compatible (e.g. all indexed tags require a newer amc than you have installed), the command errors with a hint to run amc package versions <pkg> for the full constraint list.

Options

Any positional argument ending in .am is treated as an input file. Unknown options error out with a usage message.

Exit codes

The compiler tries to make progress past resolver warnings — you'll often see a .c file generated alongside diagnostics. Treat exit status as the source of truth, not the presence of the .c file.

Multi-file compilation

Pass several .am files; the compiler merges them, runs all passes across the union, and emits a single .c file:

amc lexer.am parser.am main.am -o myapp

The first file's namespace directive determines the C symbol prefix for the whole compilation unit, so put the most authoritative file first (or make sure all files share the same namespace).

main.am's Program.Main becomes the binary's entry point. If multiple files declare Program.Main, the C compiler will reject the duplicate symbols at link time — only one entry point per executable.

Library mode

amc --lib mylib.am -o mylib
# → mylib.c (no int main, marked "[Library]")
gcc -Iruntime -c mylib.c -o mylib.o
# Link mylib.o from a host program — see chapter 5 for C interop.

Auto-detection: a file without any Program.Main is treated as a library automatically (no --lib flag needed).

amc build / run / watch (since v0.7.9)

The first-class compile verb. amc build runs amc on the entry file and invokes gcc with the right flags (runtime headers, lib/libamalgame.a, installed package facade archives, vendored package .o files, [stdlib].libs declared by each package). The result is a runnable binary — no separate gcc step.

amc build hello.am             # produces ./hello
amc build -o myapp src/main.am # explicit output
amc build -v hello.am          # verbose: prints the gcc command
amc build -g hello.am          # debug build (-O0 -g for `amc dap`)

The -g / --debug flag (v0.8.0+) swaps -O2 for -O0 -g on both the single-stage gcc link and the C++ two-stage path (DuckDB etc.). The cgen emits #line N "foo.am" directives at every statement, so DWARF carries .am filenames and line numbers — debuggers set breakpoints on .am source directly, no source maps. See amc dap in chapter 6 and the debugger workflow at the end of chapter 6.

amc run chains a build with Process.Run on the resulting binary. Args after the -- sentinel pass through to the user program's argv:

amc run hello.am               # build then run, no user args
amc run server.am -- --port 8080 --verbose

amc watch builds once, then polls the entry's mtime every 500 ms and rebuilds on change. With --run, it also re-execs the binary after each successful rebuild — handy for dev loops:

amc watch --run server.am      # rebuild + restart on save
amc watch hello.am             # rebuild only (manual ./hello to run)

v1 watches only the entry file explicitly named on the command line. Transitive imports are out of scope until the Amalgame.IO.FileWatcher package gains an event-based mode (post-D in the roadmap).

The bare-args form amc foo.am -o foo still works (emits foo.c only — no gcc step) and stays supported for the edge cases where users want to splice their own gcc command (CI cross-compile, custom flags, embedded targets).

Typical workflows

Smoke-test a single file

amc build hello.am && ./hello   # since v0.7.9
# OR the explicit two-step form
amc hello.am -o hello
gcc -Iruntime hello.c -lgc -lm -lz -o hello
./hello

Type-check on save (editor integration)

amc --check --no-color foo.am
echo $?     # 0 = OK, 1 = errors printed on stderr

Build a multi-file project

Since v0.7.9 the single-entry amc build covers most cases — amc resolves import statements transitively from the entry, so you typically only need:

amc build src/main.am          # → ./main

For older v0.7.x (or when you want explicit control over the file list), the two-step form still works:

amc \
    src/util/strings.am \
    src/util/collections.am \
    src/server/router.am \
    src/main.am \
    -o build/app

gcc -O2 -Iruntime build/app.c -lgc -lm -o build/app

Rebuild the compiler itself

./build_amc.sh        # ~5s, full self-host (runs amc on its own sources)

That script's behaviour is described in chapter 6.

Environment

The CLI is hermetic — it doesn't read environment variables. The compile-side runtime headers come from gcc -I<runtime-dir>.

Debugging the compiler

If amc produces invalid C, narrow the input by deleting half until the failure disappears, then file an issue with the minimal repro. Useful flags during triage:

• --quiet to silence "OK" messages and focus on errors
• --no-color so the snippet output stays grep-friendly
• Inspect the emitted .c file directly — naming follows <Namespace>_<Class>_<Method> and is easy to grep.

For deeper internals (how the pipeline walks the AST, where to add a new builtin, how the CGen emits a feature), see chapter 7.