Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.45.0

0.45.0 / src / main.lucb

#==============================================================================================
#
#   main - The luce-base command
#
#   DESCRIPTION:
#       `lex FILE` prints one token per line; `parse FILE` prints the syntax tree; `check
#       FILE` reports the first semantic error or nothing. Each command reads the file into
#       one arena and runs the stages in order.
#
#==============================================================================================

import luce_std.paths
import os
import c
import interop
import back.assemble.assembler
import back.link.archive as archiver
import back.link.linker
import back.backend
import back.ir.digest
import back.reuse
import bind.command as bind_command
import back.target as targets
import platform
import back.c.header
import back.names
import support.native_packages
import support.manifest
import support.modules as module_paths
import luce_std.files
import front.ast
import front.lexer
import front.layout
import front.parser
import front.source
import front.token
import io
import memory
from support.arena import Arena
import luce_std.process
import strings
import sema.check
import sema.standard as standard
import sema.describe
import embed
import back.declarations
import support.buffer
import support.cache as cache
import support.list
import support.literals
import support.runtime
import support.version
import support.host_tools
import support.pieces
import support.macos_platform
import support.in_arena

func usage(out: io.Writer) -> !:
    try out.write("usage: luce-base lex FILE\n       luce-base parse FILE\n       luce-base fmt FILE [--write | --check]\n       luce-base bind HEADER [-I DIR] [-D NAME[=VALUE]] [-o OUT.lucb] [--shims OUT.c] [--recipe FILE] [--preprocess]\n       luce-base check FILE [--package] [--target NAME] [-W]\n       luce-base describe FILE\n       luce-base describe --standard MODULE\n       luce-base interface FILE [-o OUT]\n       luce-base interface --standard MODULE\n       luce-base dependencies FILE [BUILD_ROOT]\n       luce-base describe-closure FILE\n       luce-base describe-closure [--cache-dir DIR] --modules BUILD_ROOT NAME FILE SOURCE_ROOT...\n       luce-base native-inputs FILE...\n       luce-base resolve FILE SOURCE_ROOT MODULE [--base]\n       luce-base resolve-all FILE SOURCE_ROOT MODULE... [-- FILE SOURCE_ROOT MODULE...]...\n       luce-base build FILE [-o OUT] [--release] [--emit=c] [--backend=c] [--native] [--debug] [--emit=asm] [--emit=ir] [--lib] [--freestanding] [--target] [--profile diagnostic] [--cache-dir DIR] [--cache-report] [-W] [-lNAME] [-LDIR] [-framework NAME]\n       luce-base test FILE [--package] [--backend=c] [--native] [--profile diagnostic]\n       luce-base assemble FILE.s -o FILE.o\n       luce-base link FILE.o... -o FILE.exe [-lNAME] [-LDIR] [--system DIR] [--entry NAME]\n       luce-base --version\n")

# mark: Building ===============================================================================

## What a build was asked for.
struct Options:
    var output: str
    var release: bool
    var emit_c: bool
    var run_tests: bool
    var native: bool
    var debug: bool
    var cpu: str
    ## `--lib`: a library and its header rather than a program (§17.6).
    var library: bool
    ## `--freestanding`: no startup shim; the program's own `_start` is the entry (§19.4).
    var freestanding: bool
    ## `--target` with no name: list the targets and the asm architectures the program covers.
    var list_targets: bool
    ## `--target NAME`: the target of the build (§19.5); the host when empty.
    var target: str
    ## `--profile diagnostic`: filled `---` storage and a quarantining allocator (§19.4).
    var diagnostic: bool
    ## `-lNAME` and `-LDIR`: libraries to link and where to find them.
    var libraries: list.List[c.str]
    var library_dirs: list.List[c.str]
    ## `-framework NAME`: an Apple framework to link.
    var frameworks: list.List[c.str]
    ## `--std-dir DIR`: where the standard library's source is (§16.6).
    var std_dir: str
    ## `--cache-dir DIR`: where built objects are kept, `none` for no cache (§19.7).
    var cache_dir: str
    ## `--cache-report`: say whether the object came from the cache.
    var cache_report: bool

## Element `k` of a link-flag list; an empty slot reads as empty text. A `c.str` has no zero
## value (§6.1), so the lists hold `c.str?`.
## The warnings a legal Base program may raise in the C it becomes, which are not about
## the C's types and stay silent: `-Werror` keeps the rest.
let library_c_flags: c.str[6] = ["-std=gnu11", "-Wall", "-Werror", "-fno-strict-aliasing", "-ffp-contract=off", "-O2"]
let generated_c_silences: c.str[5] = ["-Wno-format", "-Wno-self-assign", "-Wno-tautological-compare", "-Wno-parentheses-equality", "-Wno-uninitialized"]

## A command line built piece by piece: `c.str` items in a list, each formatted flag in an
## allocation of its own, so nothing is cut off at a fixed count.
struct Arguments:
    var items: list.List[c.str]

    static func create() -> Arguments!:
        return Arguments(items = try list.List[c.str].create(32))

    func add(item: c.str) -> !:
        try self.items.push(item)

    ## `prefix` followed by `value`, NUL-terminated in the current allocator.
    func flag(prefix: str, value: str) -> !:
        let room = try new u8[prefix.length + value.length + 1] ---
        let text = try strings.format(room, f"{prefix}{value}")
        try self.items.push((c.str)text)

    ## Every whitespace-separated word of `text`, as `pkg-config` prints its flags. The
    ## flags are the C driver's; for a link through `ld` itself, `-Wl,a,b` is the linker's
    ## own words `a b`.
    func words(text: str, for_linker: bool) -> !:
        let b = text.bytes
        var start: usize = 0
        var i: usize = 0
        while i <= b.length:
            if i == b.length or b[i] == ' ' or b[i] == '\n' or b[i] == '\t':
                if i > start:
                    try self.word((str)b[start..<i], for_linker)
                start = i + 1
            i += 1

    func word(text: str, for_linker: bool) -> !:
        let b = text.bytes
        if not for_linker or b.length < 5 or (str)b[..<4] != "-Wl,":
            try self.flag("", text)
            return
        var start: usize = 4
        var i: usize = 4
        while i <= b.length:
            if i == b.length or b[i] == ',':
                if i > start:
                    try self.flag("", (str)b[start..<i])
                start = i + 1
            i += 1

    func span() -> c.str[]:
        return self.items.span()

## The flags `pkg-config` answers for `name` under `what`, `--cflags` or `--libs` (§17.4);
## `for_linker` when they go to `ld` itself rather than the C driver.
func pkg_config_flags(arguments: Arguments*, name: c.str, what: c.str, for_linker: bool) -> !:
    let query: c.str[2] = [what, name]
    let asked = process.run("pkg-config", query) catch failure:
        error(build_failed, "pkg-config is not available, and the manifest names a package through it")
    defer asked.release()
    let answer = asked.value
    if answer.exit_code != 0:
        try io.stderr().write(answer.error_output)
        error(build_failed, "pkg-config does not know a package the manifest names")
    try arguments.words(trim(answer.output), for_linker)

## The `-l`, `-L`, and `-framework` options of the command line, for a C driver link:
## `-L` with a run path, and the frameworks only where the platform has them.
func link_flags(arguments: Arguments*, with_frameworks: bool) -> !:
    for directory in link_directories:
        try arguments.flag("-L", (str)directory)
        try arguments.flag("-Wl,-rpath,", (str)directory)
    for library in link_libraries:
        try arguments.flag("-l", (str)library)
    if with_frameworks:
        for framework in link_frameworks:
            try arguments.add("-framework")
            try arguments.add(framework)

## The manifest's C sources (§17.4), each compiled to an object beside the generated code
## with the flags `pkg-config` gives for the packages it names, and added to the link.
func compile_sources(dir: str, arguments: Arguments*) -> !:
    var s: usize = 0
    while s < package.sources.length:
        let source_text = (str)package.sources[s]
        let compiled_path = try new u8[dir.length + 32] ---
        let compiled = try strings.format(compiled_path, f"{dir}/source{s}.o")
        var source_args = try Arguments.create()
        try source_args.add("-std=gnu11")
        try source_args.add("-c")
        try source_args.add((c.str)source_text)
        try source_args.add("-O0" if debug_backend else "-O2")
        if debug_backend:
            # the DWARF version the native backend writes, so one debug file holds one: a
            # DWARF 5 C unit's string offsets break where GNU ld tail-merges .debug_str
            try source_args.add("-gdwarf-4")
            try source_args.add("-fno-omit-frame-pointer")
        for wanted in package.pkg_config:
            try pkg_config_flags(&source_args, wanted, "--cflags", false)
        try source_args.add("-o")
        try source_args.add((c.str)compiled)
        try run_tool("cc", source_args.span(), "the C compiler rejected a source the manifest names", dir)
        try arguments.add((c.str)compiled)
        s += 1

## Whether `text` begins with `prefix`. The compiler's own sources stay within the seed's
## modules, so this is written here rather than taken from `strings`.
func starts_with(text: str, prefix: str) -> bool:
    if text.length < prefix.length:
        return false
    var i: usize = 0
    while i < prefix.length:
        if text.bytes[i] != prefix.bytes[i]:
            return false
        i += 1
    return true

## Whether `flag` is among the arguments.
func has_argument(arguments: c.str[], flag: str) -> bool:
    for a in arguments:
        if (str)a == flag:
            return true
    return false

## `-W`: the checker's warnings go to standard error (§19.6); without it they are silent.
var show_warnings: bool = false

## A failure's message on standard error, each of its lines prefixed: a check reports
## every failing declaration of a module, one per line, with a note line where it has one.
func report_failure(message: str) -> !:
    var start: usize = 0
    var i: usize = 0
    while i <= message.length:
        if i == message.length or message.bytes[i] == '\n':
            try io.stderr().write(f"luce-base: {(str)message.bytes[start..<i]}\n")
            start = i + 1
        i += 1

func report_warnings(checker: check.Checker*) -> !:
    if not show_warnings:
        return
    var i: usize = 0
    while i < checker.warnings.count:
        try io.stderr().write(f"luce-base: {checker.warnings.get(i)}\n")
        i += 1

## Check FILE and its imports, then generate C for the whole program.
## The mode a program is built in: as asked, unless it is an `answer()` program (§19.4).
func settle_mode(entry: ast.Node*, path: c.str, mode: u32) -> u32!:
    # the message outlives the command's arena with the failure, so its room is the heap's
    if mode == 4 and check.find_decl(entry, "_start") == none:
        let file = (str)path
        let room = try new u8[file.length + 128] --- in memory.heap
        error(build_failed, try strings.format(room, f"{file}: a freestanding program supplies `export naked func _start` (§19.4)"))
    if mode == 0 and check.find_decl(entry, "main") == none:
        if check.find_decl(entry, "answer") == none:
            let file = (str)path
            let room = try new u8[file.length + 128] --- in memory.heap
            error(build_failed, try strings.format(room, f"{file}: this module has no `main` to build a program from; `check` it, or `test` it"))
        return 2
    return mode

## The key of this build (§19.7): the sources the checker read, the target and its level,
## the backend, the flags, the package, and the compiler itself.
func build_key(mode: u32, release: bool) -> str!:
    let settings = try build_settings(mode, release)
    # a debug or symbol build records the project root, and a C object is built by path:
    # those keep the root in their key; a plain native object names sources relative to it
    return try cache.key(settings, debug_backend or symbols_backend or not native_backend)

## The settings of this build as text: everything but the sources that decides its object.
func build_settings(mode: u32, release: bool) -> str!:
    let t = build_target()
    var settings = try buffer.Buffer.create(256)
    try settings.put(t.name)
    try settings.put_u64((u64)t.level)
    try settings.put(" native " if native_backend else " c ")
    try settings.put_u64((u64)mode)
    try settings.put(" r" if release else " -")
    try settings.put("d" if debug_backend else "-")
    try settings.put("s" if symbols_backend else "-")
    try settings.put("q" if diagnostic_profile else "-")
    try settings.put("f" if freestanding else "-")
    try settings.put_u64((u64)opt_level)
    try settings.put(" ")
    try settings.put_u64((u64)opt_count)
    try settings.put(" ")
    try settings.put(names.export_prefix)
    try settings.put(" ")
    try settings.put(package.name)
    if not native_backend:
        # a C object is the C compiler's as much as the program's
        try settings.put(" cc=")
        try settings.put((str)host_c_compiler())
        if let extra = os.env("LUCE_CFLAGS"):
            try settings.put(" ")
            try settings.put(extra)
    return settings.view()

## `--lib`: the program as a library with no entry, and the header of its exports (§17.6).
func generate_library(path: c.str) -> (str, str)!:
    var checker = try checked(path)
    let entry = checker.modules.get(checker.modules.count - 1).tree
    used_mode = 3
    let code = try translate(&checker, entry, 3)
    var text = try buffer.Buffer.create(4096)
    try header.write(&checker, &text)
    return (code, try names.keep(&text))

## The project root as the sources are spelled, which positions name a source relative to:
## the manifest's root is found from the canonical path, the sources keep the spelling
## they were given (`/var/...` where the root is `/private/var/...`), so the root is
## spelled as `path` is when `path` ends the same way below it.
var position_root: str = ""

func spelled_root(path: str, canonical: str, root: str) -> str:
    if root.length == 0 or canonical.length < root.length:
        return root
    let below = (str)canonical.bytes[root.length..]
    if path.length >= below.length and (str)path.bytes[path.length - below.length..] == below:
        return (str)path.bytes[..<path.length - below.length]
    return root

## The program at `given`, checked, with its warnings reported.
func checked(given: c.str, test_build: bool = false, whole_package: bool = false) -> check.Checker!:
    cache.begin()
    let path = try module_paths.portable(given)
    let canonical = try module_paths.canonical((str)path)
    let m = try manifest.load(canonical)
    package = m
    cache.default_root = m.root
    position_root = spelled_root((str)path, canonical, m.root)
    names.export_prefix = m.symbol_prefix
    var checker = try check.Checker.create(scratch_of())
    checker.debug_locals = debug_backend
    checker.package_name = m.name
    checker.build_target = build_target()
    if m.written_name.length > 0:
        checker.program = m.written_name
    checker.program_version = m.version
    checker.test_build = test_build
    checker.whole_package = whole_package
    try checker.add_prelude()
    # the modules the last build of this entry loaded, parsed ahead in parallel
    # (`check.prefetch`), and the list kept again for the next
    let listing = try cache.record_key(try strings.format(try new u8[((str)path).length + 16] ---, f"modules {(str)path}"))
    if let listed = try cache.read(listing, "-m", true):
        try checker.prefetch((str)listed)
    try checker.load(path)
    cache.keep_bytes_as(listing, "-m", (try checker.loaded_list()).bytes)
    try checker.check_program()
    let inputs = try native_inputs(&checker)
    try inputs.apply(&package)
    try report_warnings(&checker)
    return checker

## The checked program through the backend the command chose. With `split` the native
## assembly is cut into pieces (`support.pieces`); with `stable` its labels are named by what
## they label, as a split one's are, in one file. Either takes again the texts of the last
## build's functions that stand as they did (`back.reuse`), unless not `reusing`.
func translate(checker: check.Checker*, entry: ast.Node*, mode: u32, split: bool = false, stable: bool = false, reusing: bool = true) -> str!:
    if native_backend:
        # positions name a source relative to the project root, as the cache key does,
        # except in a debug or symbol build, which names (and keys) sources as they were read
        let root = "" if debug_backend or symbols_backend else position_root
        var native = try backend.NativeBackend.over(checker, entry, debug_backend and not symbols_backend, diagnostic_profile, symbols_backend, root)
        native.dump_ir = dump_ir
        native.opt_level = opt_level
        native.opt_count = opt_count
        native.report = opt_report
        native.split = split
        native.stable = stable
        # mode 3 is a library's code (`generate_library`)
        native.program = mode != 3
        if (split or stable) and reusing and try cache.on():
            # the texts are kept under the program's name and the build's settings
            var settings = digest.Digest.start(0x73657474696e6773)
            settings.text(try build_settings(mode, release_build))
            settings.word(try cache.compiler_digest())
            native.reuse_settings = settings
            native.reuse_name = try reuse.pack_name(settings, package.name, entry_spelling)
        let target: backend.Backend = &native
        var stale = false
        let text = target.compile(mode) catch failure:
            if failure.code != backend.stale:
                error(failure.code, failure.message)
            stale = true
            recover ""
        if stale:
            # a label's tag changed under a reused text (`NativeBackend.keep_texts`)
            return try translate(checker, entry, mode, split, stable, false)
        if cache.report and native.reuse_settings != none:
            try io.stderr().write(f"luce-base: {native.reused_count} functions from the last build\n")
        split_starts = native.starts
        split_ending = native.ending
        split_tags = native.tags
        split_whole = native.module_asm
        return text
    var host_c = try backend.CBackend.over(checker, entry, diagnostic_profile, position_root)
    let target: backend.Backend = &host_c
    return try target.compile(mode)

## Whether the build is `--release`, and its entry as the command spelled it: the settings
## and the name a program's function texts are kept under (`back.reuse`).
var release_build: bool = false
var entry_spelling: str = ""

## After a native translation: where each function's text began, then the rest, and where
## the closing directives began (`support.pieces`).
var split_starts: usize[]
var split_ending: usize = 0
var split_tags: u64[]
## Whether that text is assembled whole, one piece: it has module-level assembly.
var split_whole: bool = false

## Native assembly by default; generated C only when explicitly requested.
var native_backend: bool
## The target of the build, by name: empty, which is the host, unless `--target` named
## another (§19.5).
var build_target_name: str = ""
## The instruction-set level of the build, by `--cpu` name; empty for the automatic choice
## (§19.5): the processor's own level for a build of the host, the baseline for another target.
var cpu_level_name: str = ""

func build_target() -> targets.Target:
    var chosen = targets.Target.named(build_target_name) else return with_level(targets.Target.host())
    return with_level(chosen)

func with_level(t: targets.Target) -> targets.Target:
    var out = t
    if cpu_level_name.length > 0:
        if let level = t.level_named(cpu_level_name):
            out.level = level
    elif t.is_host():
        # a build for this machine uses what this machine has; `--cpu v1` asks for less
        out.level = running_level()
    return out

## The instruction-set level of the processor this compiler runs on (§19.5), what
## `os.cpu_level_running()` answers a program; asked here again because the compiler's own
## sources stay within the seed, which has no `os` module. x86-64: SSE4.2 and POPCNT make
## v2; AVX2, FMA, and BMI2 make v3; AVX-512F makes v4. arm64: NEON, the baseline.
func running_level() -> u32:
    if not platform.x86_64:
        return 1
    var leaf1: u32 = 1
    var c1: u32 = 0
    var b1: u32 = 0
    var d1: u32 = 0
    asm x86_64 (inout("eax") leaf1, inout("ecx") c1, out("ebx") b1, out("edx") d1, options(nostack)):
        cpuid
    var leaf7: u32 = 7
    var c7: u32 = 0
    var b7: u32 = 0
    var d7: u32 = 0
    asm x86_64 (inout("eax") leaf7, inout("ecx") c7, out("ebx") b7, out("edx") d7, options(nostack)):
        cpuid
    _ = b1
    _ = d1
    _ = d7
    let sse42 = (c1 & (1 << 20)) != 0
    let popcnt = (c1 & (1 << 23)) != 0
    let fma = (c1 & (1 << 12)) != 0
    let avx2 = (b7 & (1 << 5)) != 0
    let bmi2 = (b7 & (1 << 8)) != 0
    let avx512f = (b7 & (1 << 16)) != 0
    if not (sse42 and popcnt):
        return 1
    if not (avx2 and fma and bmi2):
        return 2
    return 4 if avx512f else 3

func unknown_level(t: targets.Target) -> !:
    if t.arch == targets.Arch.x86_64:
        error(build_failed, "unknown `--cpu` level; x86-64 has `v1`, `v2`, `v3`, and `v4`")
    error(build_failed, "unknown `--cpu` level; arm64 has `neon` and `sve`")

func unknown_target() -> !:
    error(build_failed, "unknown target; `--target` with no name lists them")

## `--emit=ir`: the native pipeline stops after its passes and writes the IR as text.
var dump_ir: bool
## `--opt N`: how far the IR optimiser goes (0 none, 1 single-assignment form, 2 value
## numbering, 3 load elimination, the default); `--opt-count K`: on the first K functions
## only. Both are for finding an optimiser's fault by bisection.
var opt_level: u32 = 3
var opt_count: u32 = 0xFFFFFFFF
var opt_report: bool = false
## `--debug`: the native backend describes every frame and calls the `debug` module.
var debug_backend: bool
## `--release --debug`: DWARF over the optimised code, without the in-program debugger.
var symbols_backend: bool
## `--freestanding`: the program's own `_start` is the entry, and no shim is linked (§19.4).
var freestanding: bool
## `--profile diagnostic`: filled `---` storage and a quarantining allocator (§19.4).
var diagnostic_profile: bool
## The manifest of the package being built (§16.4): its native inputs reach the build.
var package: manifest.Manifest
## `-lNAME`, `-LDIR`, and `-framework NAME` of the current build, for the link step.
## The libraries, directories, and frameworks the command line asked to link.
var link_libraries: c.str[]
var link_directories: c.str[]
var link_frameworks: c.str[]
var scratch_bytes: u8[65536]
## The mode the last `generate` settled on: 2 means an `answer()` program that links `start.c`.
var used_mode: u32

func scratch_of() -> u8[]:
    return scratch_bytes

## Turn the generated text into `exe` in a scratch directory: assembly through the
## host assembler and linker, C through the host C compiler.
func scratch_directory() -> str!:
    return try in_arena.temporary_directory(".")

func host_c_compiler() -> c.str:
    if let selected = os.env("CC"):
        return (c.str)selected
    return "gcc" if platform.windows else "cc"

## The host C compiler on `arguments`. Windows has none of its own and native builds there
## use none: only the C backend needs one, and a failure to start it says so.
func run_cc(arguments: c.str[], directory: str) -> interop.Owned[process.Completed]!:
    let compiler = host_c_compiler()
    let ran = host_tools.run_compiler(compiler, arguments, directory) catch failure:
        if not platform.windows:
            error(failure.code, failure.message)
        let room = try new u8[failure.message.length + 256] --- in memory.heap
        error(build_failed, try strings.format(room, f"the C backend needs a C compiler, and `{(str)compiler}` could not be run ({failure.message}); name one with CC, or build natively, which needs none"))
    return ran

## The program's object, from the cache or by translating and assembling (§19.7), then the
## link into `requested_exe`.
func compile(checker: check.Checker*, entry: ast.Node*, mode: u32, requested_exe: str, release: bool, with_start: bool) -> !:
    let output_buffer = try new u8[requested_exe.length + 5] ---
    defer free(output_buffer)
    let exe = try strings.format(output_buffer, f"{requested_exe}.exe") if platform.windows and paths.extension(requested_exe).length == 0 else requested_exe
    let workspace = try host_tools.Workspace(exe)
    defer workspace.destroy()
    let dir = workspace.path()
    var name_bytes: u8[4096]
    let linked_exe = try in_arena.join(dir, "program.exe")
    let key = try build_key(mode, release)
    if native_backend:
        try assemble_and_link(dir, name_bytes[..<3072], checker, entry, mode, key, linked_exe)
        try host_tools.publish(linked_exe, exe)
        if debug_backend:
            try finish_debug(exe)
        try workspace.close()
        return
    let gen_path = try strings.format(name_bytes[..<512], f"{dir}/gen.s" if native_backend else f"{dir}/gen.c")
    let header_path = try strings.format(name_bytes[512..<1024], f"{dir}/lucb_rt.h")
    let runtime_path = try strings.format(name_bytes[1024..<1536], f"{dir}/lucb_rt.c")
    let start_path = try strings.format(name_bytes[1536..<2048], f"{dir}/start.c")
    var object_path = try strings.format(name_bytes[2048..<2560], f"{dir}/gen.o")
    try files.write((c.str)header_path, runtime.header.bytes)
    try files.write((c.str)runtime_path, runtime.source.bytes)
    if with_start:
        try files.write((c.str)start_path, runtime.start.bytes)
    let include = try strings.format(name_bytes[2560..<3072], f"-I{dir}")
    if let cached = try cache.take(key, "-c.o", dir):
        object_path = cached
    else:
        let text = try translate(checker, entry, mode)
        try files.write((c.str)gen_path, text.bytes)
        var object_args = try c_arguments(release)
        try object_args.add((c.str)include)
        try object_args.add("-c")
        try object_args.add((c.str)gen_path)
        try object_args.add("-o")
        try object_args.add((c.str)object_path)
        try run_tool("cc", object_args.span(), "the C compiler rejected the generated code", dir)
        cache.keep(key, "-c.o", object_path)
    var cc_args = try c_arguments(release)
    try cc_args.add((c.str)include)
    try cc_args.add((c.str)object_path)
    try cc_args.add((c.str)runtime_path)
    if with_start:
        try cc_args.add((c.str)start_path)
    if platform.macos:
        try cc_args.add("-Wl,-dead_strip_dylibs")
    elif platform.linux:
        try cc_args.add("-Wl,--as-needed")
        try cc_args.add("-rdynamic")
    try cc_args.add("-o")
    try cc_args.add((c.str)linked_exe)
    # the manifest's C sources, under the package root (§17.4), and what it links
    for file in package.sources:
        try cc_args.add(file)
    for library in package.libraries:
        try cc_args.flag("-l", (str)library)
    for search in package.link_search:
        try cc_args.flag("-L", (str)search)
    # Frameworks are an Apple linker concept. A portable package can keep its
    # macOS adapter and framework requirements in one manifest; dead platform
    # branches and their link inputs must disappear together on other hosts.
    if build_target().os == targets.Os.macos:
        for framework in package.frameworks:
            try cc_args.add("-framework")
            try cc_args.add(framework)
    for name in package.pkg_config:
        try pkg_config_flags(&cc_args, name, "--cflags", false)
        try pkg_config_flags(&cc_args, name, "--libs", false)
    try link_flags(&cc_args, platform.macos)
    # the system libraries after every object and source that may use them: under
    # --as-needed a library named before its users is dropped (a package's C source calling
    # pow, when nothing before it did)
    try cc_args.add("-lm")
    try cc_args.add("-pthread")
    if platform.windows:
        # the runtime's waits and its random bytes (os.random_bytes)
        try cc_args.add("-lsynchronization")
        try cc_args.add("-lbcrypt")
    let result = try run_cc(cc_args.span(), dir)
    defer result.release()
    if result.value.exit_code != 0:
        let out = io.stderr()
        try out.write(result.value.error_output)
        error(build_failed, "the C compiler rejected the generated code")
    try host_tools.publish(linked_exe, exe)
    try workspace.close()

## Shared diagnostics and ABI flags for generated C and its runtime.
func c_arguments(release: bool) -> Arguments!:
    var arguments = try Arguments.create()
    try arguments.add("-std=gnu11")
    try arguments.add("-Wall")
    try arguments.add("-fno-strict-aliasing")
    # IEEE 754 with no contraction (§7.2): `a * b + c` rounds twice, as the native backend does
    try arguments.add("-ffp-contract=off")
    try arguments.add("-Werror")
    try arguments.add("-O2" if release else "-O0")
    if platform.windows:
        try arguments.add("-ffunction-sections")
        try arguments.add("-fdata-sections")
        try arguments.add("-Wl,--gc-sections")
    for flag in generated_c_silences:
        try arguments.add(flag)
    # `LUCE_CFLAGS`: flags for every C compile and link of the program, `-fsanitize=address`
    # say; the standard library's archive is built as it was
    if let extra = os.env("LUCE_CFLAGS"):
        try arguments.words(extra, false)
    return arguments

## Finish debug artifacts before the scratch objects disappear. ELF keeps a linked
## sidecar; Mach-O's debug map is resolved into a dSYM while its inputs still exist.
func finish_debug(exe: str) -> !:
    if build_target().os == targets.Os.windows:
        # PE keeps source-level DWARF in the executable; SEH remains available
        # independently of debug mode. No external debug-link path is required.
        return
    if build_target().os == targets.Os.macos:
        var arguments: c.str[1] = [(c.str)exe]
        try run_tool("dsymutil", arguments, "could not produce the dSYM")
        return
    let room = try new u8[exe.length + 32] ---
    let sidecar = try strings.format(room, f"{exe}.debug")
    var keep: c.str[3] = ["--only-keep-debug", (c.str)exe, (c.str)sidecar]
    try run_tool("objcopy", keep, "could not produce the ELF debug file")
    let link_room = try new u8[sidecar.length + 32] ---
    let link = try strings.format(link_room, f"--add-gnu-debuglink={sidecar}")
    var attach: c.str[3] = ["--strip-debug", (c.str)link, (c.str)exe]
    try run_tool("objcopy", attach, "could not attach the ELF debug file")

## The objects that make the program, from the cache or by translating and assembling:
## a split assembly's pieces (`support.pieces`), in order, or one object.
func program_objects(dir: str, name_bytes: u8[], checker: check.Checker*, entry: ast.Node*, mode: u32, key: str) -> str[]!:
    if splittable():
        if let listed = try pieces.cached(key, dir):
            return listed
        let text = try translate(checker, entry, mode, true)
        let t = build_target()
        return try pieces.assemble(dir, text, split_starts, split_tags, split_ending, key, t.os == targets.Os.macos, t.arch_name(), split_whole,
                                   in_process())
    let asm_path = try strings.format(name_bytes[..<512], f"{dir}/gen.s")
    var object_path = try strings.format(name_bytes[512..<1024], f"{dir}/gen.o")
    if let cached = try cache.take(key, "-n.o", dir):
        object_path = cached
    else:
        # labels named by what they label, so the next build may reuse functions (`back.reuse`)
        let text = try translate(checker, entry, mode, false, not debug_backend and not symbols_backend)
        if in_process():
            try assemble_in_process(text, object_path)
        else:
            try files.write((c.str)asm_path, text.bytes)
            try assemble_one(dir)
        cache.keep(key, "-n.o", object_path)
    let one = try new str[1] ---
    one[0] = object_path
    return one

## Whether this build's assembly is split into pieces: native code without debug
## information, whose DWARF lines run through the whole text.
func splittable() -> bool:
    return native_backend and not debug_backend and not symbols_backend

## Whether the target's native objects are the compiler's own to assemble and link
## (`Linker.pe`, x86_64-windows), in this process, with no host tool.
func in_process() -> bool:
    return build_target().linker == targets.Linker.pe

## Assembly `text` as the COFF object at `object_path`, by the compiler's own assembler.
func assemble_in_process(text: str, object_path: str) -> !:
    var object = try buffer.Buffer.create(text.length // 4)
    defer object.destroy()
    try assembler.assemble(text.bytes, "gen.s", &object)
    try files.write((c.str)object_path, object.bytes())

## Assemble the one file at `asm_path` into `object_path`.
func assemble_one(dir: str) -> !:
    # named relative to the workspace, which the assembler runs in: an ELF object records
    # the name of the file it was assembled from, and the workspace's changes every build
    var as_args: c.str[3] = ["-o", "gen.o", "gen.s"]
    let assembled = try host_tools.run("as", as_args, dir)
    defer assembled.release()
    if assembled.value.exit_code != 0:
        try io.stderr().write(assembled.value.error_output)
        error(build_failed, "the assembler rejected the generated code")

## The program's objects (`program_objects`), then the target's linker (§19.5): Apple's
## `ld` against the system library found through `xcrun`, the C driver, which knows
## where the C library, its start files, and the dynamic loader are, or the compiler's own.
func assemble_and_link(dir: str, name_bytes: u8[], checker: check.Checker*, entry: ast.Node*, mode: u32, key: str, exe: str) -> !:
    let objects = try program_objects(dir, name_bytes, checker, entry, mode, key)
    let t = build_target()
    if t.linker == targets.Linker.pe:
        try link_in_process(objects, exe, t)
        return
    if t.linker == targets.Linker.c_driver:
        try link_with_driver(dir, objects, exe, t)
        return
    let sdk_args: c.str[1] = ["--show-sdk-path"]
    let found = try process.run("xcrun", sdk_args)
    defer found.release()
    if found.value.exit_code != 0:
        error(build_failed, "xcrun could not find the SDK")
    let sdk = try strings.format(name_bytes[1024..<2048], f"{trim(found.value.output)}")
    var ld_args = try Arguments.create()
    try ld_args.add("-arch")
    try ld_args.add((c.str)t.arch_name())
    try ld_args.add("-syslibroot")
    try ld_args.add((c.str)sdk)
    try ld_args.add("-o")
    try ld_args.add((c.str)exe)
    # the SDK in the program's build version: AppKit treats a program that names none as
    # older than Mojave (no dark appearance); the minimum stays the assembler's
    if let minimum = try macos_platform.minimum(objects[0]):
        if let sdk_version = try macos_platform.sdk_version(sdk):
            try ld_args.add("-platform_version")
            try ld_args.add("macos")
            try ld_args.add((c.str)minimum)
            try ld_args.add((c.str)sdk_version)
    # a package's declared frameworks and libraries cost nothing where the program
    # names none of their symbols
    try ld_args.add("-dead_strip_dylibs")
    for object in objects:
        try ld_args.add((c.str)object)
    for library in t.system_libraries:
        try ld_args.add((c.str)library)
    if freestanding:
        # the exported `_start` is the entry; its assembler label carries the C underscore
        try ld_args.add("-e")
        try ld_args.add("__start")
    # the manifest's C sources (§17.4), each compiled to an object beside the assembly
    try compile_sources(dir, &ld_args)
    for library in package.libraries:
        try ld_args.flag("-l", (str)library)
    for search in package.link_search:
        try ld_args.add("-L")
        try ld_args.add(search)
    for framework in package.frameworks:
        try ld_args.add("-framework")
        try ld_args.add(framework)
    for name in package.pkg_config:
        try pkg_config_flags(&ld_args, name, "--libs", true)
    for directory in link_directories:
        try ld_args.add("-L")
        try ld_args.add(directory)
        try ld_args.add("-rpath")
        try ld_args.add(directory)
    for library in link_libraries:
        try ld_args.flag("-l", (str)library)
    for framework in link_frameworks:
        try ld_args.add("-framework")
        try ld_args.add(framework)
    let linked = try host_tools.run("ld", ld_args.span(), dir)
    defer linked.release()
    if linked.value.exit_code != 0:
        try io.stderr().write(linked.value.error_output)
        error(build_failed, "the linker rejected the generated code")

## The link through the C driver (Linux): the object, the manifest's sources compiled beside
## it, the libraries of the build, and the target's system libraries. A freestanding program
## links no start files and enters at its own `_start`, the C library still beside it as
## on macOS; `-framework` names nothing here.
func link_with_driver(dir: str, objects: const str[], exe: str, t: targets.Target) -> !:
    var cc_args = try Arguments.create()
    try cc_args.add("-o")
    try cc_args.add((c.str)exe)
    for object in objects:
        try cc_args.add((c.str)object)
    if freestanding:
        try cc_args.add("-nostartfiles")
    # the libraries after it are kept only where the program uses them
    try cc_args.add("-Wl,--as-needed")
    # the program's functions in the dynamic symbol table, so a crash report (dladdr) names
    # them
    try cc_args.add("-rdynamic")
    # the manifest's C sources (§17.4), each compiled to an object beside the assembly
    try compile_sources(dir, &cc_args)
    for search in package.link_search:
        try cc_args.flag("-L", (str)search)
    for library in package.libraries:
        try cc_args.flag("-l", (str)library)
    for name in package.pkg_config:
        try pkg_config_flags(&cc_args, name, "--libs", false)
    try link_flags(&cc_args, false)
    for library in t.system_libraries:
        try cc_args.add((c.str)library)
    try run_tool("cc", cc_args.span(), "the linker rejected the generated code", dir)

## The link by the compiler's own linker (`back.link`): the objects, the libraries the
## package, the command line and the target name as DLLs, found where the package and the
## command line say and in Windows' own directory. The manifest's C sources would need a C
## compiler, which a Windows build is without.
func link_in_process(objects: const str[], exe: str, t: targets.Target) -> !:
    if package.sources.length > 0:
        # the message outlives the command's arena with the failure, so its room is the heap's
        let room = try new u8[((str)package.sources[0]).length + 160] --- in memory.heap
        error(build_failed, try strings.format(room, f"{(str)package.sources[0]}: C sources need a C compiler, which Windows builds do not use; list them under the package's macOS and Linux `def native` blocks"))
    var libraries = try list.List[str].create(16)
    for library in package.libraries:
        try libraries.push((str)library)
    for library in link_libraries:
        try libraries.push((str)library)
    for library in t.system_libraries:
        if starts_with(library, "-l"):
            try libraries.push((str)library.bytes[2..])
    var directories = try list.List[str].create(8)
    for search in package.link_search:
        try directories.push((str)search)
    for directory in link_directories:
        try directories.push((str)directory)
    let options = linker.Options(objects = objects, libraries = libraries.span(), directories = directories.span(), system = try system_directory(),
                                 entry = "_start" if freestanding else "mainCRTStartup", output = exe)
    try linker.link(&options)

## Windows' own DLLs' directory, System32 under `SystemRoot`; empty on a host without one.
func system_directory() -> str!:
    let root = os.env("SystemRoot") else return ""
    return try in_arena.join(root, "System32")

## `build FILE`: check, generate, compile.
func build_file(path: c.str, options: Options) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        if options.debug and not options.native:
            error(build_failed, "--debug requires the native backend")
        native_backend = options.native
        debug_backend = options.debug and options.native
        # `--release --debug`: the optimised program with DWARF, no debugger hooks
        symbols_backend = options.debug and options.native and options.release
        link_libraries = options.libraries.span()
        link_directories = options.library_dirs.span()
        link_frameworks = options.frameworks.span()
        standard.override = options.std_dir
        cache.override = options.cache_dir
        cache.report = options.cache_report
        cpu_level_name = options.cpu
        if options.target.length > 0:
            let chosen = targets.Target.named(options.target) else return try unknown_target()
            build_target_name = chosen.name
            manifest.set_target(chosen.name)
            if not chosen.is_host() and not options.emit_c:
                error(build_failed, "a program for another target is written as C with --emit=c and compiled there")
        if options.cpu.length > 0 and build_target().level_named(options.cpu) == none:
            return try unknown_level(build_target())
        if options.list_targets:
            try list_targets(path)
            return
        if options.library:
            let (code, header_text) = try generate_library(path)
            if options.emit_c:
                # `--emit=c` or `--emit=asm`: the library's code as text, for any target
                if options.output.length > 0:
                    try files.write((c.str)options.output, code.bytes)
                else:
                    try io.stdout().write(code)
                return
            try build_library(code, header_text, options.output if options.output.length > 0 else "library")
            return
        if options.freestanding and not options.native:
            error(build_failed, "a freestanding program is built natively: add `--native`")
        freestanding = options.freestanding
        diagnostic_profile = options.diagnostic
        release_build = options.release
        entry_spelling = (str)path
        var checker = try checked(path)
        let entry = checker.modules.get(checker.modules.count - 1).tree
        used_mode = try settle_mode(entry, path, 4 if options.freestanding else (1 if options.run_tests else 0))
        if options.emit_c:
            let text = try translate(&checker, entry, used_mode)
            if options.output.length > 0:
                try files.write((c.str)options.output, text.bytes)
            else:
                try io.stdout().write(text)
            return
        var exe = options.output
        if exe.length == 0:
            exe = "a.out"
        try compile(&checker, entry, used_mode, exe, options.release, used_mode == 2 and not native_backend)

## `--target` with no name (§19.6): the targets of §19.5, then the asm architectures the
## program's own modules carry blocks for; the one this compiler builds is marked.
func list_targets(path: c.str) -> !:
    var checker = try checked(path)
    let out = io.stdout()
    try out.write("targets:")
    for name in targets.names:
        try out.write(f" {name}")
        if name == targets.Target.host().name:
            try out.write(" (built here)")
    try out.write("\n")
    # every architecture an `asm` block names, at module level or inside a function, once
    var covers_arm64 = false
    var covers_x86_64 = false
    var i: usize = 0
    while i < checker.modules.count:
        let m = checker.modules.get(i)
        if not m.is_prelude:
            var cursor = m.tree.body
            while let d = cursor:
                if d.kind == ast.Kind.asm_:
                    note_architecture(d.text, &covers_arm64, &covers_x86_64)
                elif d.kind == ast.Kind.func_:
                    if let body = d.body:
                        var s = body.body
                        while let statement = s:
                            if statement.kind == ast.Kind.asm_:
                                note_architecture(statement.text, &covers_arm64, &covers_x86_64)
                            s = statement.next
                cursor = d.next
        i += 1
    if covers_arm64 or covers_x86_64:
        try out.write("asm architectures covered:")
        if covers_arm64:
            try out.write(" arm64")
        if covers_x86_64:
            try out.write(" x86_64")
        try out.write("\n")
    else:
        try out.write("asm architectures covered: none\n")

func note_architecture(arch: str, arm64: bool*, x86_64: bool*):
    if arch == "arm64":
        *arm64 = true
    elif arch == "x86_64":
        *x86_64 = true

## `--lib`: `NAME.a` from the generated code (and the C runtime when the code is C), and
## `NAME.h` with the exported surface (§17.6).
func build_library(code: str, header_text: str, name: str) -> !:
    let workspace = try host_tools.Workspace(name)
    defer workspace.destroy()
    let dir = workspace.path()
    var names_bytes: u8[4096]
    let destination = try strings.format(names_bytes[2048..<2560], f"{name}.a")
    let archive = try in_arena.join(dir, "library.a")
    let header_path = try strings.format(names_bytes[2560..<3072], f"{name}.h")
    let object_path = try strings.format(names_bytes[..<512], f"{dir}/gen.o")
    if native_backend:
        if in_process():
            try assemble_in_process(code, object_path)
        else:
            let asm_path = try strings.format(names_bytes[512..<1024], f"{dir}/gen.s")
            try files.write((c.str)asm_path, code.bytes)
            var as_args: c.str[3] = ["-o", (c.str)object_path, (c.str)asm_path]
            try run_tool("as", as_args, "the assembler rejected the generated code", dir)
        if in_process():
            var one: str[1] = [object_path]
            try archiver.archive_files(one, archive)
        else:
            var ar_args = try Arguments.create()
            try ar_args.add("rcs")
            try ar_args.add((c.str)archive)
            try ar_args.add((c.str)object_path)
            try run_tool("ar", ar_args.span(), "the archiver failed", dir)
    else:
        let gen_path = try strings.format(names_bytes[512..<1024], f"{dir}/gen.c")
        let rt_header = try strings.format(names_bytes[1024..<1536], f"{dir}/lucb_rt.h")
        let rt_source = try strings.format(names_bytes[1536..<2048], f"{dir}/lucb_rt.c")
        try files.write((c.str)gen_path, code.bytes)
        try files.write((c.str)rt_header, runtime.header.bytes)
        try files.write((c.str)rt_source, runtime.source.bytes)
        var include_bytes: u8[600]
        let include = try strings.format(include_bytes, f"-I{dir}")
        var rt_object_bytes: u8[600]
        let rt_object = try strings.format(rt_object_bytes, f"{dir}/rt.o")
        var gen_args = try Arguments.create()
        for flag in library_c_flags:
            try gen_args.add(flag)
        for flag in generated_c_silences:
            try gen_args.add(flag)
        try gen_args.add((c.str)include)
        try gen_args.add("-c")
        try gen_args.add((c.str)gen_path)
        try gen_args.add("-o")
        try gen_args.add((c.str)object_path)
        try run_tool("cc", gen_args.span(), "the C compiler rejected the generated code", dir)
        var rt_args: c.str[11] = ["-std=gnu11", "-Wall", "-Werror", "-fno-strict-aliasing", "-ffp-contract=off", "-O2", (c.str)include, "-c", (c.str)rt_source, "-o", (c.str)rt_object]
        try run_tool("cc", rt_args, "the C compiler rejected the runtime", dir)
        var ar_args = try Arguments.create()
        try ar_args.add("rcs")
        try ar_args.add((c.str)archive)
        try ar_args.add((c.str)object_path)
        try ar_args.add((c.str)rt_object)
        try run_tool("ar", ar_args.span(), "the archiver failed", dir)
    try host_tools.publish(archive, destination)
    try files.write((c.str)header_path, header_text.bytes)
    try workspace.close()

## `assemble FILE -o OBJECT`: x86-64 assembly for Windows as a COFF object, through the
## compiler's own assembler (`back.assemble`).
func assemble_file(path: c.str, output: c.str) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        let text = try in_arena.read(path)
        var object = try buffer.Buffer.create(text.length // 4)
        try assembler.assemble(text, (str)path, &object)
        try files.write(output, object.bytes())

## `link FILE.o... -o FILE.exe`: objects for x86_64-windows linked into an executable by
## the compiler's own linker (`back.link`), with `-lNAME`'s DLLs from `-LDIR`, `--system
## DIR` (Windows' own directory by default, so another host can link with a copy of it),
## and `--entry NAME` for an entry other than the start library's.
func link_file(arguments: const c.str[]) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var objects = try list.List[str].create(16)
        var libraries = try list.List[str].create(8)
        var directories = try list.List[str].create(8)
        var options = linker.Options(objects = objects.span(), libraries = libraries.span(), directories = directories.span(), system = try system_directory(),
                                     entry = "mainCRTStartup", output = "")
        var i: usize = 0
        while i < arguments.length:
            let a = (str)arguments[i]
            let value = (str)arguments[i + 1] if i + 1 < arguments.length else ""
            if a == "-o" or a == "--system" or a == "--entry":
                if value.length == 0:
                    let room = try new u8[64] --- in memory.heap
                    error(build_failed, try strings.format(room, f"{a} takes a value"))
                if a == "-o":
                    options.output = value
                elif a == "--system":
                    options.system = value
                else:
                    options.entry = value
                i += 1
            elif starts_with(a, "-l") and a.length > 2:
                try libraries.push((str)a.bytes[2..])
            elif starts_with(a, "-L") and a.length > 2:
                try directories.push((str)a.bytes[2..])
            else:
                try objects.push(a)
            i += 1
        if options.output.length == 0:
            error(build_failed, "link needs -o FILE.exe")
        options.objects = objects.span()
        options.libraries = libraries.span()
        options.directories = directories.span()
        try linker.link(&options)

## Run a build tool; its standard error is shown when it fails.
func run_tool(program: c.str, arguments: c.str[], what: str, directory: str = "") -> !:
    let ran = try run_cc(arguments, directory) if (str)program == "cc" else try host_tools.run(program, arguments, directory)
    defer ran.release()
    if ran.value.exit_code != 0:
        try io.stderr().write(ran.value.error_output)
        error(build_failed, what)

## `test FILE`: build the test runner into a scratch file and run it; `whole_package`
## (`--package`) tests every module of the file's package, imported or not (§16.5).
func test_file(path: c.str, native: bool, whole_package: bool) -> i32!:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        native_backend = native
        var checker = try checked(path, true, whole_package)
        let entry = checker.modules.get(checker.entry_index).tree
        used_mode = try settle_mode(entry, path, 1)
        # a function no test reaches is not compiled, so one naming another platform's
        # symbol builds here as it does in a program that imports the module
        try check.test_as_library(checker.modules.get(checker.entry_index).name)
        # LUCE_TEST_BINARY keeps the compiled test kept at a path so a memory checker can
        # run it (tools/valgrind_std.sh); otherwise it builds into a scratch dir and removes it.
        if let requested = os.env("LUCE_TEST_BINARY"):
            let kept = try strings.copy(requested)
            try compile(&checker, entry, 1, kept, false, false)
            var kept_args: c.str[1] = ---
            kept_args[0] = (c.str)kept
            return try process.call((c.str)kept, kept_args)
        let directory = try scratch_directory()
        defer remove_tree((c.str)directory)
        let exe_name = try new u8[directory.length + 16] ---
        let exe = try strings.format(exe_name, f"{directory}/test.exe" if platform.windows else f"{directory}/test")
        try compile(&checker, entry, 1, exe, false, false)
        var run_args: c.str[1] = ---
        run_args[0] = (c.str)exe
        # the runner writes to our streams as it goes: a report and a trap stay in order
        return try process.call((c.str)exe, run_args)

## `test`'s file and options, in any order: the backend, `--native` (the default) or
## `--backend=c`, the profile, `--profile diagnostic` or `--profile default` (§19.4), and
## `--package`, the whole package (§16.5); none, after the usage, for anything else or for
## other than one file.
func test_options(arguments: const c.str[]) -> TestOptions?!:
    var options = TestOptions()
    var count: usize = 0
    var i: usize = 0
    while i < arguments.length:
        let a = (str)arguments[i]
        let profile = (str)arguments[i + 1] if a == "--profile" and i + 1 < arguments.length else ""
        if a == "--backend=c":
            options.native = false
        elif a == "--package":
            options.whole_package = true
        elif profile == "diagnostic" or profile == "default":
            options.diagnostic = profile == "diagnostic"
            i += 1
        elif a.length > 0 and not starts_with(a, "-"):
            options.file = arguments[i]
            count += 1
        elif a != "--native" and a != "-W":
            count = 0
            break
        i += 1
    if count != 1:
        try usage(io.stderr())
        return none
    return options

## What `luce-base test` was asked: the file and how to build its tests.
struct TestOptions:
    var file: c.str = ""
    var native: bool = true
    var diagnostic: bool = false
    var whole_package: bool = false

func remove_tree(path: c.str):
    files.remove_tree(path) catch failure:
        _ = failure

## The program could not be built.
pub let build_failed: ErrorCode = ErrorCode.package(13)

## Text without its trailing newline.
func trim(text: str) -> str:
    var end = text.length
    let b = text.bytes
    while end > 0 and (b[end - 1] == '\n' or b[end - 1] == ' '):
        end -= 1
    return (str)b[..<end]

## A checker for the build's target with the prelude loaded: the start of every command
## that checks without settings of its own.
func new_checker() -> check.Checker!:
    var checker = try check.Checker.create(scratch_of())
    checker.build_target = build_target()
    try checker.add_prelude()
    return checker

## The program whose entry is `path`, loaded and checked by a `new_checker`.
func checked_entry(path: c.str) -> check.Checker!:
    var checker = try new_checker()
    try checker.load(path)
    try checker.check_program()
    return checker

## Check FILE and the modules it imports, and with `whole_package` every other module of its
## package (`--package`, what `luc check` asks for); silence means success. The command's
## status: 1 when the check failed, or when it printed warnings and `-W` makes them a failure.
func check_file(path: c.str, whole_package: bool) -> i32!:
    var result = try embed.check_file(path, build_target(), whole_package)
    defer result.close()
    if not result.ok():
        try report_failure(result.failure)
        return 1
    try report_warnings(&result.checker)
    return 1 if show_warnings and result.checker.warnings.count > 0 else 0

## `check FILE --target NAME`: the checker sees NAME's platform constants, so the warnings
## that depend on them (a branch no target of the name reaches) are the target's (§19.5).
## Whether the arguments name a target.
func check_target(arguments: c.str[]) -> bool!:
    var i: usize = 3
    while i + 1 < arguments.length:
        if (str)arguments[i] == "--target":
            let chosen = targets.Target.named((str)arguments[i + 1]) else error(build_failed, "unknown target; `--target` with no name lists them")
            build_target_name = chosen.name
            manifest.set_target(chosen.name)
            return true
        i += 1
    return false

## Check the module and print its public declarations (§17.7).
func describe_file(path: c.str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try checked_entry(path)
        let entry = checker.modules.get(checker.modules.count - 1)
        try describe.write(out, &checker, entry.tree, entry.name)

## The interface of the module at `path` (§9.8): its declarations with `linked` for what
## a library built from it defines, written to `output`, or to `out` when there is none.
func interface_file(path: c.str, output: str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try checked_entry(path)
        var text = try buffer.Buffer.create(65536)
        try declarations.write(&text, checker.modules.get(checker.modules.count - 1), &checker.table)
        if output.length > 0:
            try files.write((c.str)output, text.bytes())
        else:
            try out.write(text.view())

## The interface of a standard module, from the source the compiler carries.
func interface_standard(name: str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try new_checker()
        let index = checker.find_module(name) else error(build_failed, "unknown standard module")
        try checker.check_program()
        var text = try buffer.Buffer.create(65536)
        try declarations.write(&text, checker.modules.get(index), &checker.table)
        try out.write(text.view())

## Describe the compiler's canonical embedded module, without copying it into a
## temporary user module or changing the standard declarations' type identities.
func describe_standard(name: str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try new_checker()
        let index = checker.find_module(name) else error(build_failed, "unknown standard module")
        try checker.check_program()
        try describe.write(out, &checker, checker.modules.get(index).tree, name)

## Resolve through the same package exports as a Base build. The names/paths use
## NUL delimiters so directory names containing whitespace remain lossless.
func resolve_module(importer: str, root: str, name: str, base_only: bool, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        let (kind, resolved) = try classified(importer, root, name, base_only)
        try out.write(f"luce-base-module-v1\0{kind}\0{resolved.name}\0{resolved.path}\0{resolved.root}\0")

## What import `name` of `importer` is, for the resolve commands: its kind, `standard`,
## `package` (a `from` import whose names are modules, §16.3), `base` or `luce`, and where it
## leads. A Base module is a `.lucb` file or a directory whose `ORDER` lists its fragments.
func classified(importer: str, root: str, name: str, base_only: bool) -> (str, module_paths.Resolution)!:
    if check.is_standard_module(name):
        return ("standard", module_paths.Resolution(name, "", ""))
    if try module_paths.names_modules(importer, name):
        return ("package", module_paths.Resolution(name, root, root))
    let resolved = try module_paths.resolve(importer, root, name, base_only)
    let order = try new u8[resolved.path.length + 8] ---
    let base = strings.ends_with(resolved.path, ".lucb") or files.exists((c.str)try strings.format(order, f"{resolved.path}/ORDER"))
    return ("base" if base else "luce", resolved)

## `resolve-all IMPORTER ROOT NAME... [-- IMPORTER ROOT NAME...]...`: the imports of one
## module or more, each resolved as `resolve` does, in one run. For each module, `importer`
## and its path; then a record for each name, `module`, the name, kind, canonical name,
## path and root, or `error`, the name and the message; each field ended by NUL. A
## consumer resolving imports a process at a time paid a process for each (luced-3d: 382);
## one module at a time, a process for each module.
func resolve_modules(groups: c.str[], out: io.Writer) -> !:
    try out.write("luce-base-modules-v2\0")
    var at: usize = 0
    while at < groups.length:
        var end = at
        while end < groups.length and (str)groups[end] != "--":
            end += 1
        if end - at < 2:
            error(build_failed, "resolve-all: each module is its path and its source root, then its imports")
        let importer = (str)groups[at]
        let root = (str)groups[at + 1]
        try out.write(f"importer\0{importer}\0")
        for named in groups[at + 2..<end]:
            let name = (str)named
            var arena = Arena(memory.heap)
            defer arena.destroy()
            with arena:
                let (kind, resolved) = classified(importer, root, name, false) catch failure:
                    try out.write(f"error\0{name}\0{failure.message}\0")
                    continue
                try out.write(f"module\0{name}\0{kind}\0{resolved.name}\0{resolved.path}\0{resolved.root}\0")
        at = end + 1

## Report the resolved nonstandard import closure for source packaging. The entry
## itself is excluded: the caller already knows its source path and import alias.
## Names and paths are NUL-delimited, so whitespace in a parent path is lossless.
## Load through the same resolver as a build; source text is never approximated by
## matching import-looking lines. Validate before writing any protocol bytes.
func dependencies_file(path: c.str, build_root: str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try checked_closure(path, build_root)
        try write_dependencies(&checker, out)

## `path` loaded and checked with everything it imports.
func checked_closure(path: c.str, build_root: str = "") -> check.Checker!:
    var checker = try check.Checker.create(scratch_of())
    checker.build_target = build_target()
    # a consumer building another package names that build's source root, whose package
    # names its modules bare (§16.3); otherwise `load` takes the entry's own package
    if build_root.length > 0:
        let building = try module_paths.building_package(build_root)
        if building.length > 0:
            checker.package_name = building
    try checker.add_prelude()
    try checker.load(path)
    try checker.check_program()
    return checker

## The dependency report of a checked closure: native inputs, then each module but the
## entry with its source, then every module's package.
## `entry_last`: the last module is the entry, which the caller names itself and the report
## leaves out; with several modules loaded by their canonical names, none is left out.
func write_dependencies(checker: check.Checker*, out: io.Writer, entry_last: bool = true) -> !:
    let inputs = try native_inputs(checker)
    try out.write("luce-base-dependencies-v4\0")
    try inputs.write(out)
    let reported = checker.modules.count - 1 if entry_last and checker.modules.count > 0 else checker.modules.count
    var index: usize = 0
    while index < reported:
        let item = checker.modules.get(index)
        if not item.is_prelude:
            try out.write("source\0")
            try out.write(item.name)
            try out.write("\0")
            try out.write(item.canonical)
            try out.write("\0")
        index += 1
    for module in checker.modules.span():
        if not module.is_prelude:
            try out.write(f"package\0{module.name}\0{module.package_name}\0")

## `describe-closure FILE`: the module at `path` checked once, then every module of its
## closure described (`module`, its source path, the description, each ended by NUL, the
## list ended by an empty record), then the closure's dependency report. A consumer that
## would describe each module and ask each for its dependencies checks the closure once.
func describe_closure(path: c.str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var checker = try checked_closure(path)
        try write_closure(&checker, out, true)

## A checked closure as `describe-closure` reports it: each module but the prelude with its
## description, then the dependency report, whose entry `entry_last` leaves out.
func write_closure(checker: check.Checker*, out: io.Writer, entry_last: bool) -> !:
    try out.write("luce-base-closure-v1\0")
    for module in checker.modules.span():
        if module.is_prelude:
            continue
        try out.write(f"module\0{module.canonical}\0")
        try describe.write(out, checker, module.tree, module.name)
        try out.write("\0")
    try out.write("\0")
    try write_dependencies(checker, out, entry_last)

## `describe-closure [--cache-dir DIR] --modules BUILD_ROOT NAME PATH ROOT...`: several modules, each loaded under its
## canonical name from its package's source root, checked together once, then described as
## `describe-closure` describes one closure; the dependency report names every module of
## the union, these among them. A consumer that imports many modules with closures in
## common (every one of luced-3d's holds luce-prism) checks the shared part once.
##
## With a cache named, the answer is kept as a record (`support.cache`) under the question
## and answered from it while nothing it read has changed: a Luce build asks this of the
## same unchanged libraries every time.
func describe_closures(build_root: str, triples: c.str[], out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var record = ""
        if cache.named():
            var question = try buffer.Buffer.create(1024)
            try question.put("describe-closure\0")
            try question.put(build_root)
            for argument in triples:
                try question.put("\0")
                try question.put((str)argument)
            record = try cache.record_key(question.view())
            if let answer = try cache.recall(record):
                _ = try out.write(answer)
                return
        var answer = try buffer.Buffer.create(65536)
        try closure_of(build_root, triples, &answer)
        if record.length > 0:
            cache.remember(record, answer.bytes())
        _ = try out.write(answer.bytes())

## The closures `describe_closures` describes, checked and written to `out`.
func closure_of(build_root: str, triples: c.str[], out: io.Writer) -> !:
    var checker = try check.Checker.create(scratch_of())
    checker.build_target = build_target()
    # the build's package names its modules bare, every other package's behind its
    # identifier (§16.3), as each module's own description names them
    let building = try module_paths.building_package(build_root)
    if building.length > 0:
        checker.package_name = building
    try checker.add_prelude()
    var at: usize = 0
    while at + 2 < triples.length:
        let root = (str)triples[at + 2]
        let room = try new u8[root.length + 2] ---
        # a root is a directory the module paths below it are joined to
        checker.root = try strings.format(room, f"{root}/") if root.length > 0 and root.bytes[root.length - 1] != '/' else root
        if checker.find_module((str)triples[at]) == none:
            try checker.load_as(triples[at + 1], (str)triples[at])
        at += 3
    try checker.check_program()
    try write_closure(&checker, out, false)

## Collect the packages actually loaded, including the entry and private imports.
func native_inputs(checker: check.Checker*) -> native_packages.Inputs!:
    var inputs = try native_packages.Inputs.create()
    for module in checker.modules.span():
        if not module.is_prelude:
            try inputs.collect(module.canonical)
    return inputs

## Luce also has native inputs on its own source packages. Share Base's manifest
## interpretation without requiring a Luce source file to parse as Base.
## `native-inputs FILE...`: the native records of each file's manifest, gathered in order,
## each once; a consumer with many modules asks once.
func native_inputs_files(sources: c.str[], out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        var inputs = try native_packages.Inputs.create()
        for path in sources:
            try inputs.collect((str)path)
        try out.write("luce-base-dependencies-v4\0")
        try inputs.write(out)

func parse_file(path: c.str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        let src = try source.Source.load(path)
        var p = try parser.Parser.over(src, scratch_of())
        let module = try p.parse_module()
        try ast.dump(out, module, 0)

## `fmt FILE`: the module in the canonical layout (§19.6), printed; `--write` puts it back
## in the file, `--check` prints nothing and answers 1 when the file is not in that layout.
## The layout is proved before it is shown: the parser reads it back into the same tree.
func fmt_file(path: c.str, mode: str, out: io.Writer) -> i32!:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        let src = try source.Source.load(path)
        var p = try parser.Parser.over(src, scratch_of())
        p.allow_core_names = true  # a standard module formats like any other
        let module = try p.parse_module()
        var f = try layout.Formatter.over(src, p.token_span())
        try f.module(module)
        let text = f.text()
        let again = try source.Source.over((str)path, text.bytes)
        var p2 = try parser.Parser.over(again, scratch_of())
        p2.allow_core_names = true
        let reread = p2.parse_module() catch failure:
            error(failure.code, try strings.format(scratch_bytes[..<2048], f"the layout does not parse: {failure.message}"))
        if not same_tree(module, reread):
            error(build_failed, "the layout reads back as a different tree; the formatter is wrong for this file")
        if mode == "--check":
            return 0 if text == (str)src.bytes else 1
        if mode == "--write":
            if text != (str)src.bytes:
                try files.write(path, text.bytes)
            return 0
        try out.write(text)
        return 0

## Whether two trees have the same structure: at every node, sibling for sibling, the
## kind, flags, text and children match. The condition echo the parser keeps on an
## `assert` call (§11.6) is a whitespace-sensitive copy of the source that the formatter
## may reflow, and the argument subtree already fixes the meaning, so it is not compared
## on a call node.
func same_tree(a: ast.Node*?, b: ast.Node*?) -> bool:
    var x = a
    var y = b
    while true:
        let na = x else return y == none
        let nb = y else return false
        if na.kind != nb.kind or na.flags != nb.flags:
            return false
        if na.kind != ast.Kind.call and na.text != nb.text:
            return false
        if not same_tree(na.ty, nb.ty) or not same_tree(na.left, nb.left):
            return false
        if not same_tree(na.right, nb.right) or not same_tree(na.body, nb.body):
            return false
        x = na.next
        y = nb.next

func lex_file(path: c.str, out: io.Writer) -> !:
    var arena = Arena(memory.heap)
    defer arena.destroy()
    with arena:
        let src = try source.Source.load(path)
        var lx = lexer.Lexer.over(src)
        while true:
            let t = try lx.next()
            if t.kind == token.Kind.eof:
                break
            if t.kind == token.Kind.newline or t.kind == token.Kind.indent or t.kind == token.Kind.dedent:
                try out.write(f"{t.line}:{t.column} {t.label()}\n")
            else:
                try out.write(f"{t.line}:{t.column} {t.label()} {lx.text(t)}\n")

## `build`'s options from its arguments after the file, or none when one is malformed: the
## message is already written.
func build_options(arguments: c.str[]) -> Options?!:
    var options = try default_options()
    # An emission format selects its backend independently of flag order.
    var emission_backend: u32 = 0
    var i: usize = 3
    while i < arguments.length:
        let last = try build_option(&options, arguments, i, &emission_backend) else return none
        i = last + 1
    if emission_backend != 0:
        options.native = emission_backend == 2
    return options

## `build`'s options before any argument: the native backend, no output named, nothing
## linked.
func default_options() -> Options!:
    var options: Options = ---
    options.libraries = try list.List[c.str].create(4)
    options.library_dirs = try list.List[c.str].create(4)
    options.frameworks = try list.List[c.str].create(4)
    options.output = ""
    options.std_dir = ""
    options.cache_dir = ""
    options.cache_report = false
    options.release = false
    options.emit_c = false
    options.run_tests = false
    options.native = true
    options.debug = false
    options.library = false
    options.freestanding = false
    options.list_targets = false
    options.target = ""
    options.cpu = ""
    options.diagnostic = false
    return options

## The `build` argument at `i` into `options` (an emission format's backend into
## `emission_backend`): the index of the last argument it took, the one after it when it
## takes a value, or none when it is malformed, its message written.
func build_option(options: Options*, arguments: c.str[], i: usize, emission_backend: u32*) -> usize?!:
    let a = (str)arguments[i]
    let has_value = i + 1 < arguments.length
    let value = (str)arguments[i + 1] if has_value else ""
    if a == "-o" and has_value:
        options.output = value
        return i + 1
    elif a == "--release":
        options.release = true
    elif a == "--emit=c" or a == "--emit=asm":
        options.emit_c = true
        dump_ir = false
        *emission_backend = 1 if a == "--emit=c" else 2
    elif a == "--emit=ir":
        options.emit_c = true
        options.native = true
        dump_ir = true
        *emission_backend = 2
    elif a == "--opt" and has_value:
        let wanted_level = literals.decode_integer(value) catch failure:
            try io.stderr().write("luce-base: --opt takes a level 0, 1, 2, or 3\n")
            return none
        if wanted_level > 3:
            try io.stderr().write("luce-base: --opt takes a level 0, 1, 2, or 3\n")
            return none
        opt_level = u32(wanted_level)
        return i + 1
    elif a == "--opt-report":
        opt_report = true
    elif a == "--opt-count" and has_value:
        let wanted_count = literals.decode_integer(value) catch failure:
            try io.stderr().write("luce-base: --opt-count takes a number of rewrites\n")
            return none
        opt_count = u32(wanted_count)
        return i + 1
    elif a == "--native":
        options.native = true
    elif a == "--backend=c":
        options.native = false
    elif a == "--lib":
        options.library = true
    elif a == "--freestanding":
        options.freestanding = true
    elif a == "--target" and has_value and not starts_with(value, "-"):
        options.target = value
        return i + 1
    elif a == "--target":
        options.list_targets = true
    elif a == "--cpu" and has_value:
        options.cpu = value
        return i + 1
    elif a == "--profile" and has_value:
        if value == "diagnostic":
            options.diagnostic = true
        elif value != "default":
            try io.stderr().write(f"luce-base: unknown profile `{value}`; the profiles are `default` and `diagnostic`\n")
            return none
        return i + 1
    elif a == "--debug":
        options.debug = true
    elif a == "-W":
        show_warnings = true
    elif starts_with(a, "-l") and a.length > 2:
        try options.libraries.push((c.str)(str)a.bytes[2..])
    elif starts_with(a, "-L") and a.length > 2:
        try options.library_dirs.push((c.str)(str)a.bytes[2..])
    elif a == "-framework" and has_value:
        try options.frameworks.push(arguments[i + 1])
        return i + 1
    elif a == "--cache-dir" and has_value:
        options.cache_dir = value
        return i + 1
    elif a == "--cache-report":
        options.cache_report = true
    elif a == "--std-dir" and has_value:
        options.std_dir = value
        return i + 1
    else:
        try io.stderr().write(f"luce-base: unexpected argument `{a}`\n")
        return none
    return i

## The questions Luce asks of Base modules (resolve, describe-closure, native-inputs,
## dependencies, and their batched forms): the command's exit status, or none when
## `command` is not one of them or its arguments are not that command's.
func module_question(command: str, positional: usize, arguments: c.str[], out: io.Writer) -> i32?!:
    if command == "resolve" and (positional == 5 or (positional == 6 and (str)arguments[5] == "--base")):
        resolve_module((str)arguments[2], (str)arguments[3], (str)arguments[4], positional == 6, out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "native-inputs" and positional >= 3:
        native_inputs_files(arguments[2..], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "describe-closure" and positional == 3:
        describe_closure(arguments[2], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "describe-closure" and positional >= 7 and (str)arguments[2] == "--modules" and (positional - 4) % 3 == 0:
        describe_closures((str)arguments[3], arguments[4..], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "resolve-all" and positional >= 4:
        resolve_modules(arguments[2..], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "dependencies" and (positional == 3 or positional == 4):
        dependencies_file(arguments[2], (str)arguments[3] if positional == 4 else "", out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    return none

## The `luce-base` command: it dispatches on the first argument (§19.6).
## `given` with each `@file` replaced by the file's lines, one argument a line, as C
## compilers read them: how a caller passes more than a command line holds. Windows takes
## 32 767 characters, and luce's batched questions (`resolve-all`, `describe-closure
## --modules`) name every module of a program by its absolute path. An `@` that names no
## readable file stays the argument it is.
func response_files(given: c.str[]) -> c.str[]!:
    var any = false
    for a in given:
        let text = (str)a
        if text.length > 1 and text.bytes[0] == '@':
            any = true
    if not any:
        return given
    var expanded = try list.List[c.str].create(given.length + 64)
    for a in given:
        let text = (str)a
        if text.length < 2 or text.bytes[0] != '@':
            try expanded.push(a)
            continue
        let read = files.read((c.str)try strings.copy((str)text.bytes[1..])) catch:
            try expanded.push(a)
            continue
        let contents = (str)read.value
        var start: usize = 0
        while start < contents.length:
            var end = start
            while end < contents.length and contents.bytes[end] != '\n':
                end += 1
            var stop = end
            if stop > start and contents.bytes[stop - 1] == '\r':
                stop -= 1
            try expanded.push((c.str)try strings.copy((str)contents.bytes[start..<stop]))
            start = end + 1
    return expanded.span()

## The command line, its `@file` arguments read (`response_files`): the command's status.
pub func main(given: c.str[]) -> i32!:
    let arguments = try response_files(given)
    let out = io.stdout()
    if arguments.length < 2:
        try usage(io.stderr())
        return 2
    let command = (str)arguments[1]
    # a command takes the files as it first finds them (`cache.remembering`): a lookup is
    # tens of microseconds on Windows, and luced-3d's build looked at its dependencies'
    # directories 90 000 times, for most of four seconds there
    cache.remembering = true
    # `-W` may appear on any command and is not one of its arguments
    var positional = arguments.length
    for a in arguments:
        if (str)a == "-W":
            show_warnings = true
            positional -= 1
    if command == "--version":
        try out.write(f"luce-base {version.text}\n")
        return 0
    if command == "fmt" and (positional == 3 or (positional == 4 and ((str)arguments[3] == "--write" or (str)arguments[3] == "--check"))):
        let mode = (str)arguments[3] if positional == 4 else ""
        let code = fmt_file(arguments[2], mode, out) catch failure:
            try io.stderr().write(f"luce-base: {failure.message}\n")
            recover 1
        return code
    if command == "bind":
        let code = bind_command.run(arguments, out) catch failure:
            try io.stderr().write(f"luce-base: {failure.message}\n")
            recover 1
        return code
    if command == "parse" and positional == 3:
        parse_file(arguments[2], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "build" and positional >= 3:
        let options = try build_options(arguments) else return 2
        build_file(arguments[2], options) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "test" and positional >= 3:
        let options = try test_options(arguments[2..]) else return 2
        diagnostic_profile = options.diagnostic
        let code = test_file(options.file, options.native, options.whole_package) catch failure:
            try report_failure(failure.message)
            recover 1
        return code
    if command == "check" and positional >= 3:
        var whole_package = false
        for a in arguments[3..]:
            if (str)a == "--package": whole_package = true
        let words = positional - (1 if whole_package else 0)
        let targeted = check_target(arguments) catch failure:
            try report_failure(failure.message)
            return 1
        if (words != 3 and words != 5) or targeted != (words == 5):
            try usage(io.stderr())
            return 2
        let code = check_file(arguments[2], whole_package) catch failure:
            try report_failure(failure.message)
            recover 1
        return code
    if command == "describe-closure" and positional >= 5 and (str)arguments[2] == "--cache-dir":
        # the cache Luce keeps, where the closure's answer is recorded (`describe_closures`)
        cache.override = (str)arguments[3]
        var rest = try new c.str[positional - 2] ---
        rest[0] = arguments[0]
        rest[1] = arguments[1]
        for k in 4..<positional:
            rest[k - 2] = arguments[k]
        if let code = try module_question(command, positional - 2, rest, out):
            return code
    if let code = try module_question(command, positional, arguments, out):
        return code
    if command == "describe" and positional == 4 and (str)arguments[2] == "--standard":
        describe_standard((str)arguments[3], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "describe" and positional == 3:
        describe_file(arguments[2], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "interface" and positional == 4 and (str)arguments[2] == "--standard":
        interface_standard((str)arguments[3], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "interface" and (positional == 3 or (positional == 5 and (str)arguments[3] == "-o")):
        interface_file(arguments[2], (str)arguments[4] if positional == 5 else "", out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if let code = try file_tool(command, positional, arguments, out):
        return code
    try usage(io.stderr())
    return 2

## The commands that turn one file into another form, `lex` and `assemble`: the exit status,
## or none when `command` is not one of them with its arguments.
func file_tool(command: str, positional: usize, arguments: c.str[], out: io.Writer) -> i32?!:
    if command == "assemble" and positional == 5 and (str)arguments[3] == "-o":
        assemble_file(arguments[2], arguments[4]) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "link" and positional >= 5:
        link_file(arguments[2..]) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    if command == "lex" and positional == 3:
        lex_file(arguments[2], out) catch failure:
            try report_failure(failure.message)
            return 1
        return 0
    return none

test "an @file argument stands for the file's lines, one argument a line":
    let folder = try in_arena.temporary_directory(".")
    defer files.remove_tree((c.str)folder) catch ignored:
        _ = ignored
    let listing = try in_arena.join(folder, "arguments")
    try files.write((c.str)listing, "C:/a b/one.luc\r\nroot\n--\nlast")
    let reference = try strings.join(["@", listing], "")
    var given: c.str[4] = ["luce-base", "resolve-all", (c.str)try strings.copy(reference), "@missing-file"]
    let expanded = try response_files(given)
    assert(expanded.length == 7)
    assert((str)expanded[2] == "C:/a b/one.luc" and (str)expanded[3] == "root" and (str)expanded[4] == "--" and (str)expanded[5] == "last")
    assert((str)expanded[6] == "@missing-file")