Compiling and running
How a .nu source file becomes a native binary.
A NURL source file goes through two stages to become a program you can run:
hello.nu → (nurlc) → hello.ll (LLVM IR — a text format, human-readable)
hello.ll → (clang) → hello (native binary for your machine)nurlc (the NURL compiler) never touches your CPU's instruction set
directly. It emits LLVM IR and hands that to
clang, which turns it into a real binary. This is the
same backend Rust and Swift use.
Script compiling
Whether you installed the prebuilt toolchain (nurl) or built from source (./nurl.sh / nurl.bat), the wrapper drives both stages for you:
nurl hello.nu # → ./hello
nurl hello.nu myprogram # → ./myprogram
nurl --run hello.nu # compile and run immediately
./nurl.sh hello.nu # repo-root equivalent in a source checkoutUseful flags (put them before the source file):
| Flag | Effect |
|---|---|
-O0 … -O3 | Optimization level passed to clang (default -O2) |
-g, --debug | Emit DWARF debug info (#line directives mapping back to .nu lines) |
--check | Fast parse, type check, and borrow check without LLVM IR codegen |
--lint | Report unused bindings/functions, shadowed locals, and redundant frees |
--unsafe-report | Audit every unsafe function and raw pointer/FFI operation |
--split | Emit multi-file C shards and compile them across CPU cores in parallel |
--sanitize | Compile and link with AddressSanitizer, UBSan, and LeakSanitizer |
--coverage | Instrument line/branch coverage for nurl-cov |
--static | Produce a statically linked binary |
--target=<triple> | Cross-compile for the given target triple |
--emit-ir | Stop after stage 1 — just produce the .ll file, do not link |
--emit-asm | Emit native assembly (.s), skip linking |
--stdin NAME | Read the source from stdin; diagnostics and the default output name use NAME (no file needs to exist) |
At the default -O2, clang inlines and reorders code aggressively.
A debugger's "break at this source line" becomes unreliable, because
the line may not correspond to a single instruction anymore. -O0 keeps
the generated code close to the source structure, which you want
when you step through a bug, at the cost of a slower binary. Reach for
-O2/-O3 again after debugging.
Manual compiling
./build/nurlc hello.nu > hello.ll
clang hello.ll stdlib/runtime.native.o -lm -lpthread -o hello
./helloLink against stdlib/runtime.native.o, not stdlib/runtime.o — after a
normal build the latter is LLVM bitcode (for link-time optimization), and a
plain clang link rejects it with "file format not recognized".
nurlc emits only the functions your main can actually reach. An
import brings in a whole module — importing stdlib/ext/json.nu for
json_parse also brings the pretty-printer, the comparison helpers
and the float formatter — and handing all of that to clang means
paying for optimizing code the linker then throws away. Dropping it
at the source of the IR instead is worth 30–40% of the clang step
on a stdlib-heavy program.
The binary is unchanged: link-time optimization was already removing
the same code, just later. Reachability is computed over the finished
IR, so closures, generic instantiations, destructors and dynamic
trait vtables are all handled without special cases, and a file with
no main — a module you intend to link into something else — is
left whole. nurlc --no-dce emits everything, which is what you want
when diffing IR against an older compiler.
If you installed the prebuilt toolchain
The prebuilt installer (curl | sh or install.ps1) places nurl, nurlc, nurlpkg, nurlfmt, stdlib/, and lib/runtime.native.o in $NURL_HOME (~/.nurl), so you can compile and run .nu files directly with nurl hello.nu or nurl --run hello.nu without building from source.
Compiling to WebAssembly
See the online playground
to try NURL in the browser without an install, and
docs/PLATFORMS.md
for the full target list when you are ready to cross-compile.
Last updated on