This page is an English fallback. I have not published a Español translation of this generated reference yet.

Compiler CLI#

This page embeds the help text from the compiler used for the guide build. The parser remains the authority when an old document disagrees.

nanoc - Compiler for the nanolang programming language

Usage: ./bin/nanoc [OPTIONS] <input.nano>
       ./bin/nanoc --print-locale [--locale <tag>]

Options:
  -o <file>      Specify output file (default: $TMPDIR/nanoc_a.out)
  --verbose      Show detailed compilation steps and commands
                 (also enabled by NANO_VERBOSE_BUILD=1 env var)
  --keep-c       Keep generated C file (saves to output dir instead of /tmp)
  -fshow-intermediate-code  Print generated C to stdout
  -S             Save generated C to <input>.genC (for inspection)
  --json-errors  Output errors in JSON format for tool integration
  --reflect <path>  Emit module API as JSON (for documentation generation)
  -I <path>      Add include path for C compilation
  -L <path>      Add library path for C linking
  -l <lib>       Link against library (e.g., -lSDL2)
  -pg            Enable gprof profiling (adds -g -fno-omit-frame-pointer)
  --profile      Inject timing hooks; print hotspot report (sorted by total time)
  --trace        Inject generated-C function-call tracing hooks (stderr).
                 Shares one startup hook with --profile; NANO_TRACE=0 disables
                 collection at runtime without recompiling.
  --profile-output <p>  Write structured profiling JSON to file <p> (use with -pg)
  --coverage     Instrument compiled output for gcov/lcov line+branch coverage
                 Run: gcov <source.c>, or use 'make coverage-report' for HTML
  --profile-runtime     Implies --profile; also write flamegraph collapsed-stack
                 .nano.prof (default: <output_binary>.nano.prof). Compatible with
                 flamegraph.pl: flamegraph.pl <bin>.nano.prof > flame.svg
                 Native target only — errors out under --target, which
                 emit artifacts nanoc never runs and so cannot profile.
  --profile-runtime-output <p>  Set explicit path for flamegraph .nano.prof output
  --target <t>   Compile target: native (default), ptx, opencl, c, riscv
                 ptx:    emit NVIDIA PTX assembly for `gpu fn` functions
                 opencl: emit OpenCL C kernel source (.cl) for `gpu fn` functions
                         CPU fallback via POCL when no GPU present
  --tco          Enable tail-call optimization (rewrite tail recursion to loops)
  --debug / -g   Emit debug info where the selected target supports it
  --bench        Run @bench-annotated functions (micro-benchmark mode)
  --bench-n <N>  Fixed iteration count (default: auto-calibrate to ~1s)
  --bench-json <f> Write JSON benchmark results to file
                          clang -O2 prog.ll -o prog
  --pgo <file>   Profile-guided inlining: read .nano.prof from a native
                 --profile-runtime build, identify hot call sites and inline
                 them. Combines with --tco.
                 Example: nanoc --profile-runtime prog.nano -o prog
                          ./prog                    # generates prog.nano.prof
                          nanoc --pgo prog.nano.prof prog.nano -o prog_opt
  install [pkg@range ...]
                 Install nano packages from the registry (nanoc-install.sh)
                 Reads nano.packages.json + writes nano.lock
                 Example: nanoc install gpu-math@^1.0.0 nano-core@latest
  add [pkg@range ...]
                 Add package(s) to nano.packages.json and install them
                 Example: nanoc add gpu-math@^1.0.0
  --version, -v  Show version information
  --help, -h     Show this help message
  --locale <tag> BCP 47 language tag (overrides NANO_LOCALE, LC_ALL, LANG)
  --print-locale Print resolved locale axes and exit (no compile)

Verification Options:
  --trust-report         Show formal verification trust levels for all functions
  --reference-eval       Cross-check verified functions with Coq-extracted interpreter

Safety Options:
  --warn-unsafe-imports  Warn when importing unsafe modules
  --warn-unsafe-calls    Warn when calling functions from unsafe modules
  --warn-ffi             Warn on any FFI (extern function) call
  --forbid-unsafe        Error (not warn) on unsafe module imports

Agent Options:
  --llm-diags-json <p>   Write machine-readable diagnostics JSON (agent-only)
  --llm-diags-toon <p>   Write diagnostics in TOON format (~40% fewer tokens)
  --llm-shadow-json <p>  Write machine-readable shadow failure summary JSON (agent-only)
  --test-imports        I run dependency shadows before root shadows (default)
  --root-shadows-only   I run only root-file shadows

Examples:
  ./bin/nanoc hello.nano -o hello
  ./bin/nanoc program.nano --verbose -S          # Show steps and save C code
  ./bin/nanoc example.nano -o example --verbose
  ./bin/nanoc sdl_app.nano -o app -I/opt/homebrew/include/SDL2 -L/opt/homebrew/lib -lSDL2

Parser Audit#

I found 35 long option spellings in src/main.c.

These parsed spellings are absent from the current --help output:

• --doc-md
• --emit-typed-ast-json
• --save