Compiler Configuration, Build Modes and Cross-Compilation

38.1 Build Modes

(default) debug All checks, stack traces, no optimization Optimizations (-O3), keeps runtime checks (bounds, overflow...)

Optimizations + all checks off (maximum speed, unsafe) --opt:speed / size / none C compiler optimization goal

-d:lto / --passC:-flto --passL:-flto Defects abort immediately (smaller, faster code) Debug info for gdb/lldb with Nim names --stackTrace:off --lineTrace:off Disable trace bookkeeping

--checks:off, --boundChecks:off, --overflowChecks:off, --nilChecks --mm:orc / arc / refc Thread support (on by default in Nim 2) --app:console / gui / lib / staticlib

--cc:gcc / clang / vcc / tcc / zig / icl -d:strip / --passL:-s

--hints:off, --warnings:off, --warningAsError:X Enforce consistent identifier style

38.2 Configuration Files (Precedence: Low → High)

$nim/config/nim.cfg (global) ~/.config/nim/nim.cfg / config.nims (user)

Parent directory nim.cfg / config.nims Project nim.cfg, config.nims, <project>.nim.cfg, <project>.nims

# config.nims
switch("mm", "orc")
--define:release
when defined(windows):
  switch("cc", "vcc")

38.3 Cross-Compilation

Static linking with musl (--passL:-static) for fully portable Linux binaries.

--genScript / --compileOnly generate C sources and a build script for compiling elsewhere.

nim c --os:windows --cpu:amd64 -d:mingw app.nim                 # Linux → Windows (MinGW)
nim c --os:linux --cpu:arm64 --gcc.exe:aarch64-linux-gnu-gcc --gcc.linkerexe:aarch64-linux-gnu-gcc app.nim
nim c --cc:clang --clang.exe:"zigcc" --clang.linkerexe:"zigcc" --passC:"-target x86_64-linux-musl" app.nim   # Zig as a cross C compiler
nim c --os:android --cpu:arm64 ...                               # Android NDK
nim c --os:ios --cpu:arm64 ...