Executables

Contract for programs built by clau -o or a project build. Positional inputs, or exactly one selected project target, link into the -o path; a project build links each selected executable target to its manifest output (linking, projects).

Entry selection

The entry is an exported function of arity 1 that receives the argument list.

• FUNCTION defaults to main. Names are unquoted atom text: 1–255 Unicode scalars, valid UTF-8, no control characters and no :. Other spellings are usage errors (CLI, exit 2) or manifest errors (exit 1).
• entry is an optional schema-1 key; older manifests stay valid. The whole manifest is decoded, so a malformed entry fails even in unselected targets.
• CLI --entry overrides the manifest key and requires exactly one selected target. It conflicts with check/print actions and --new-project; those actions ignore manifest entry (as they ignore output).
• An explicit entry is validated in every compiling mode (default, --emit, IR/type inspection), together with ordinary semantic diagnostics.

For project targets the hint also names the manifest key: ... --entry MODULE[:FUNCTION] or with entry = "MODULE[:FUNCTION]" in this target's [[targets]] table of the project manifest ..., for example:

[[targets]]
name = "app"
sources = ["src/*.erl"]
entry = "app:start"   # calls app:start/1; plain "app" calls app:main/1

Arguments

Entry(Argv) receives a proper list of strings (lists of Unicode code points), excluding the program name and the leading runtime options, otherwise unchanged and in order, like escript.

• POSIX: each argument's bytes are decoded as UTF-8; a byte that does not start a valid sequence becomes the code point of that byte (Latin-1 fallback).
• Windows: the CRT's wide (UTF-16) argument vector, split by the same rules as argv; an unpaired surrogate becomes U+FFFD.
• No other option parsing, globbing or environment expansion happens in the runtime.

Runtime options

The runtime reads its options from the CLAUSE_FLAGS environment variable (words split on spaces and tabs, no quoting) and then from the leading command-line arguments, so the command line wins. Both are parsed the same way; a value goes in the next argument or after =.

On the command line, parsing stops at the first argument that is not a runtime option, so prog data --max-atoms 9 passes all three arguments to the program. In CLAUSE_FLAGS every word must be a runtime option. An invalid value, a word that is not an option in the variable, or --args-file stops the program before any module is registered: clau: runtime failure: <reason>, exit 70. Process counts are not limited and memory is uncapped by default. Byte values are decimal without suffixes and round down to whole words; a program reaching a cap fails with resource_limit, exit 70 (runtime memory limit).

Exit status

Invalid halt/1 arguments raise badarg in the caller. When the entry finishes, the program exits: other processes are stopped without running further, as with OTP's halt/1 after escript returns. A halt in any process ends the program with its status, and a runtime failure in any process ends it with 70; an exception in a spawned process ends only that process (processes).

halt/0,1, error/1,2,3, exit/1 and throw/1 are callable with or without the erlang: prefix; a local definition or -compile({no_auto_import, ...}) keeps the unqualified name local, as in OTP. halt/2 is not available. halt(N) keeps the low 31 bits of any non-negative integer, as OTP does. A slogan is a proper list of at most 1,023 Unicode code points. A halt unwinds the entry through the checked error channel like an error, so it stops the program only after generated cleanup.

Output streams

• stdout: standard_io output (io:format/1,2, io:put_chars/1, erlang:display/1). Buffered; flushed on every exit path except abort.
• stderr: the uncaught-exception report, standard_error output, runtime failures and the error reports of other processes that crash (processes).
• The report is one line uncaught exception <class>: <reason in ~w form>, later followed by stack frames (step 15). Its exact text is not a stable interface; tests match it by pattern.

Startup object

Compiling with an explicit entry (--entry or manifest entry) adds a startup module after the batch's modules. With --emit it is published as clausev1_start.{obj,o,ll,bc} next to the module artifacts (the name cannot collide with a module artifact). It contains a constant abi::v1::StartupDescriptor (startup.hpp): ABI revision, term width, every module descriptor in source order, the entry module/function spellings and an escript flag. Its int main(int, char **) calls the runtime's CLAUSE_main_v1, which:

1. Checks the startup and every module descriptor for ABI revision and width before anything is registered; a mismatch exits 70.
2. Starts the runtime and registers all modules; any failure stops before the entry and discards the runtime (exit 70), so no Erlang code runs against a partial batch.
3. Creates the entry process, builds argv and queues the call of M:F/1 as the main process, then runs it and every process it spawns on the cooperative executor (processes) until it ends.
4. Maps the outcome to the exit status above, printing reports after flushing stdout, then releases every process and shuts the runtime down on every path (except halt(abort)).

clau -o links these objects itself (linking). Manual linking (the native harness recipe without a harness source):

& $tool --emit obj --entry app --artifact-dir build/app app.erl helper.erl
clang-cl /MT build/app/*.obj build/debug/lib/clause_runtime.lib /Fe:app.exe

Any Clang-compatible link of the objects with Clause::generated_program works the same way (see tests/compiler/linking/startup.cmake).

Linking

clau [-O0|-O2|-Os] -o PATH a.erl b.erl ... (or --project FILE [--target T] -o PATH for one selected target) compiles the batch in memory, adds the startup object for the entry and links an executable:

clau -O2 -o build/demo examples/compile/answer.erl examples/compile/client.erl
./build/demo          # build/demo.exe on Windows

-Os additionally places every generated and runtime function and data object in its own section and links with --gc-sections (ELF), -dead_strip (Mach-O) or /OPT:REF /OPT:ICF (MSVC), so code no entry path reaches is removed.

• PATH is invocation-relative. For Windows targets, .exe is appended when the file name has no extension. Its directory must exist.
• Linker: --linker PATH (a path or program name), else clang++ or clang from PATH, then (Windows) %ProgramFiles%/LLVM/bin. It runs as <clang> --driver-mode=g++ --target=<triple> -o <staged> <objects> <runtime>, so Clang chooses the platform linker and C/C++ runtime libraries (on Windows it locates MSVC and the SDK itself; no developer shell is needed).
• Runtime: --runtime-library PATH, else the clause_runtime archive of the build that produced clau (path recorded relative to the executable, e.g. bin/../lib/clause_runtime.lib). Every native object in the archive must match the target's architecture and object format; --target-triple for another target therefore needs a runtime built for it.
• Objects and the executable are staged in a private .clause-link-* directory beside the output, which is removed afterwards. The output is replaced only after a successful link, so every failure keeps an existing file unchanged. The output must not be a directory or alias an input.
• Linker warnings are forwarded to stderr; --linker and --runtime-library require --output or a linking project build.
• Project builds without -o link every selected target that has output or entry to its manifest output, creating missing directories, and replace the outputs only after all selected targets linked (projects).

Escripts

A source file whose first line starts with #! is compiled as an escript, in any mode and with any file name (positional inputs or project .erl files). Rules follow OTP 29 escript for source scripts:

• The #! line is ignored. An optional comment on line 2 and a %%! emulator line (line 2, or line 3 after the comment) are comments; %%! arguments cannot apply to compiled code and produce a warning.
• If the first form is not -module(...), the module is <file name with '.' replaced by '_'>__escript (?MODULE included). OTP adds a timestamp/unique suffix; Clause keeps the name deterministic. The synthesized declaration occupies line 1, so later line numbers are unchanged.
• main/1 is required (escript does not define main/1) and implicitly exported; other functions follow normal export rules.
• -mode(compile | interpret | debug | native) is accepted and ignored; other values are errors. Outside escripts -mode stays unsupported.
• Entry: without --entry, the only escript in the batch is the entry (it wins over modules exporting main/1); several escripts are ambiguous.
• Exit status as OTP escript: an exception escaping the escript entry exits 127 with escript: exception <class>: <reason> on stderr; other rows of the exit-status table apply unchanged.
• Files without #! are ordinary modules. (OTP escript file.erl would skip their first line; Clause does not.) Precompiled beam and archive escripts are not supported.

OTP comparison

Goldens for program fixtures run the entry under OTP with the same rules (oracle); the same oracle generates the executable golden cases that the end-to-end runner links and runs under every policy. Differences from escript for ordinary modules: uncaught exceptions exit 1 instead of 127, and main/1 must be exported. Escript sources keep OTP's rules (see above).