Core · the compiler driver
necc
Build C and Nelua programs for x86-64 Linux against standalone Nelibc, run Lua, or compile an object for UEFI firmware.
Compile a program
These commands assume the staged SDK is installed at the distro default or selected with NECC_SYSROOT.
export NECC_SYSROOT=/path/to/sdk
printf '%s\n' 'int main(void) { return 0; }' > hello.c
necc hello.c -o hello
./hello
printf '%s\n' "print 'hello from Nelua'" > hello.nelua
necc hello.nelua -o hello-nelua
./hello-nelua
necc --lua -e 'print(_VERSION)'For a multi-file link, pass source files, object files and static archives together. Put archives after the objects that use them. Use -c to keep the object file from a single input.
Choose a Nelua compilation path
necc program.neluauses the full Nelua frontend and TinyCC as its C backend.necc --native program.neluasends the full frontend’s generated C through necc’s native C frontend. This path requires the program’s generated C to fit the supported subset.necc --direct program.neluaselects the self-hosted Nelua subset frontend and the native C backend.
The C frontend is written in Nelua. Its native backend uses the x86-64 System V calling convention by default.
Call x86-64 UEFI firmware
When the Nelua frontend emits C for an EFI entry point or protocol function pointer, necc honors its ms_abi attribute. Firmware can call the entry point, and the application can call firmware through a pointer stored in a protocol table.
The neboot verification exercises both directions. The compiler emits an ELF object for nelinker’s EFI output mode.
Link with nelinker
The 19 November 2026 toolchain build accepts an absolute linker path in NECC_NELINKER. With both tools on your PATH and the same SDK selected, rebuild the C example above using nelinker for its final static link.
export NECC_NELINKER="$(command -v nelinker)"
necc hello.c -o hello
./helloThe SDK’s TinyCC still handles C preprocessing and assembly. When NECC_NELINKER is unset, TinyCC also handles the final link. To see which archive member supplies a symbol, try the direct archive example.
Compiler timings
Generated arithmetic
On 21 November 2026 the six-million-iteration kernel took 1.626 ms with necc, 9.318 ms with the previous necc and 2.979 ms with Zig cc -O2. The two reference executables are byte-for-byte identical to those in the earlier comparison.
When a register-only integer loop has a unit-stride counter and a state update that is linear in the state and counter, necc can combine 16 iterations. It uses the scalar loop for the remainder. The compiler derives the coefficients and any low-bit mask from the program. Calls, volatile accesses and other observable effects keep the original loop. The generated kernel grew from 69 to 154 bytes.
Each time below is a median in milliseconds over 23 warm, interleaved rounds on one Intel Core i7-11700F core. The external field contains 13 compiler configurations. Text size is the number of bytes of machine code in necc’s object. The two Lua tables contain data.
| Workload | necc before (ms) | Updated necc (ms) | Fastest external (ms) | necc text (B) |
|---|---|---|---|---|
| Compile tiny C input | 2.551 | 2.607 | 1.837 · TinyCC | 16 |
| Compile 128 functions | 5.368 | 5.032 | 2.271 · TinyCC | 6422 |
| Compile arithmetic kernel | 2.540 | 2.533 | 1.808 · lacc -O2 | 154 |
| Compile Lua character table | 3.860 | 4.021 | 2.450 · TinyCC | 0 |
| Compile Lua opcode table | 4.878 | 4.744 | 2.813 · TinyCC | 0 |
| Compile bootstrap compiler | 6.362 | 6.503 | 2.851 · TinyCC | 7833 |
| Run six million iterations | 9.318 | 1.626 | 2.979 · Zig cc -O2 | 154 |
| Regenerate bootstrap C | 4.352 | 4.463 | 4.211 · GCC -O2 | 7833 |
The optimized executable finished ahead of Zig in all 42 rounds of an independent repeat. Across 57 loop shapes, both necc versions matched the reference on 26,299 inputs. Lua’s string-hash routine kept identical machine code and passed 263,688 output checks.
Compare every compiler configuration
| Compiler | Tiny C | 128 functions | Arithmetic | Lua characters | Lua opcodes | Bootstrap C | Run arithmetic | Run bootstrap |
|---|---|---|---|---|---|---|---|---|
| Clang 14 -O0 | 20.027 | 33.009 | 20.149 | 20.646 | 21.658 | 27.990 | 11.194 | 4.385 |
| Clang 14 -O2 | 20.976 | 92.247 | 26.195 | 21.012 | 21.933 | 87.959 | 4.353 | 4.255 |
| GCC -O0 | 10.885 | 44.213 | 11.235 | 8.632 | 9.281 | 29.039 | 9.253 | 4.249 |
| GCC -O2 | 11.768 | 141.611 | 13.769 | 8.745 | 9.085 | 90.562 | 6.825 | 4.211 |
| PCC | 4.186 | 8.595 | 4.263 | 5.328 | 5.524 | 9.175 | 10.056 | 4.399 |
| PCC -O | 4.175 | 7.587 | 4.192 | 5.320 | 5.594 | 10.331 | 9.274 | 4.330 |
| TinyCC | 1.837 | 2.271 | 1.822 | 2.450 | 2.813 | 2.851 | 9.738 | 4.336 |
| Zig cc -O0 | 24.353 | 39.639 | 24.534 | 25.751 | 26.224 | 34.691 | 10.913 | 4.309 |
| Zig cc -O2 | 26.681 | 96.052 | 30.321 | 25.174 | 26.287 | 90.162 | 2.979 | 4.375 |
| chibicc | 3.786 | 11.398 | 3.823 | 7.739 | 9.777 | 11.951 | 17.452 | 4.569 |
| cproc/QBE | 8.258 | 12.732 | 8.213 | 9.226 | 9.943 | 13.070 | 9.452 | 4.282 |
| lacc | 1.862 | 2.511 | 1.825 | 2.829 | 3.098 | 3.008 | 17.046 | 4.273 |
| lacc -O2 | 1.870 | 2.669 | 1.808 | 2.816 | 3.117 | 3.088 | 16.939 | 4.350 |
| necc before | 2.551 | 5.368 | 2.540 | 3.860 | 4.878 | 6.362 | 9.318 | 4.352 |
| necc updated code generator | 2.607 | 5.032 | 2.533 | 4.021 | 4.744 | 6.503 | 1.626 | 4.463 |
Timings, quartiles and object sizes (CSV)All 2,760 samples (CSV)Three-way arithmetic repeat (CSV)Method and checksReplay the runtime comparisonIndependent loop and Lua checks
Dense switch dispatch
On 21 November 2026 necc e1eab18 emitted relative jump tables for dense integer switches. Both runtime workloads used the same interpreter objects except for Lua’s VM. The third row times a separate compiler invocation.
| Workload | 2ebbb9d (ms) | e1eab18 (ms) | TinyCC (ms) |
|---|---|---|---|
| Run one million Lua calls | 605.81 | 498.10 | 168.98 |
| Emit C for Nelua matrix multiplication | 1077.34 | 984.03 | 746.34 |
| Compile the Lua VM to an object | 160.26 | 138.43 | 23.77 |
Each Lua workload returned the expected result. All three frontend runs emitted byte-identical C at the same output path. The small arithmetic control produced identical necc objects before and after.
Lua runtime samplesFrontend runtime samplesC compilation and arithmetic samplesQuartiles and observed rangesReplay scriptsVersions and reproduction
Earlier SDK comparison
Earlier on 21 November, changing the SDK preprocessor cut the 128-function compile from 9.370 to 5.425 ms. Both SDKs used the same necc executable and emitted byte-identical objects. The old arithmetic executable took 9.729 ms against Zig’s 3.071 ms. Zig combined four recurrence steps per group, while that necc build executed one step at a time.
SDK comparison (CSV)Individual SDK timings (CSV)Zig loop-unrolling control (CSV)SDK comparison method
Compiler phase timings
Preprocessing the 128-function input fell from 5.586 to 1.999 ms in a separate 25-round comparison. The updated necc frontend took 2.774 ms on that preprocessed C, and the SDK assembler took 2.684 ms on its output. TinyCC compiled the original C directly in 2.437 ms. Each figure includes a separate process launch.
| Phase | Tiny C, before | Tiny C, updated | 128 functions, before | 128 functions, updated |
|---|---|---|---|---|
| TinyCC preprocessing | 1.646 | 1.755 | 5.586 | 1.999 |
| necc frontend (--cc1) | 1.504 | 1.412 | 2.841 | 2.774 |
| necc -S on preprocessed C | 1.483 | 1.474 | 2.888 | 2.894 |
| TinyCC assembly | 1.612 | 1.611 | 2.635 | 2.684 |
| Complete necc compile | 2.534 | 2.515 | 8.953 | 5.425 |
| Complete TinyCC compile | 1.779 | 1.829 | 2.313 | 2.437 |
Phase medians and quartiles (CSV)All 600 phase samples (CSV)Verified output hashes (CSV)
19 November 2026 toolchain comparison
In the static x86-64 Linux shootout, necc improved on its previous release. Other compilers led all six compile-time cases and both generated-program runtime cases. The table shows median milliseconds over 23 warm, interleaved rounds. Each tool had to produce the expected result.
| Workload | Previous necc (ms) | GCC-built necc (ms) | Fastest external (ms) |
|---|---|---|---|
| Compile 128 functions | 16.038 | 8.727 | 1.506 · TinyCC |
| Run six million arithmetic iterations | 20.277 | 9.371 | 2.099 · Zig cc -O2 |
A separate 25-round measurement of the 128-function input put standalone preprocessing at 4.892 ms. TinyCC finished the entire compile in 1.526 ms in that run. For a larger correctness check, necc compiled all 42 C translation units of the Lua runtime and extensions. The resulting interpreter passed the portable Lua 5.4.6 test suite.
Compiler and object results (CSV)Compiler phase timings (CSV)
Build the distro
nebuild runs the build graph that uses necc to compile Nebox and package the Theseus boot image.