Nelua

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.

necc source on GitHub

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.nelua uses the full Nelua frontend and TinyCC as its C backend.
  • necc --native program.nelua sends 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.nelua selects 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
./hello

The 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.

Static x86-64 Linux · 21 November 2026
Workloadnecc before (ms)Updated necc (ms)Fastest external (ms)necc text (B)
Compile tiny C input2.5512.6071.837 · TinyCC16
Compile 128 functions5.3685.0322.271 · TinyCC6422
Compile arithmetic kernel2.5402.5331.808 · lacc -O2154
Compile Lua character table3.8604.0212.450 · TinyCC0
Compile Lua opcode table4.8784.7442.813 · TinyCC0
Compile bootstrap compiler6.3626.5032.851 · TinyCC7833
Run six million iterations9.3181.6262.979 · Zig cc -O2154
Regenerate bootstrap C4.3524.4634.211 · GCC -O27833

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
Median milliseconds by workload
CompilerTiny C128 functionsArithmeticLua charactersLua opcodesBootstrap CRun arithmeticRun bootstrap
Clang 14 -O020.02733.00920.14920.64621.65827.99011.1944.385
Clang 14 -O220.97692.24726.19521.01221.93387.9594.3534.255
GCC -O010.88544.21311.2358.6329.28129.0399.2534.249
GCC -O211.768141.61113.7698.7459.08590.5626.8254.211
PCC4.1868.5954.2635.3285.5249.17510.0564.399
PCC -O4.1757.5874.1925.3205.59410.3319.2744.330
TinyCC1.8372.2711.8222.4502.8132.8519.7384.336
Zig cc -O024.35339.63924.53425.75126.22434.69110.9134.309
Zig cc -O226.68196.05230.32125.17426.28790.1622.9794.375
chibicc3.78611.3983.8237.7399.77711.95117.4524.569
cproc/QBE8.25812.7328.2139.2269.94313.0709.4524.282
lacc1.8622.5111.8252.8293.0983.00817.0464.273
lacc -O21.8702.6691.8082.8163.1173.08816.9394.350
necc before2.5515.3682.5403.8604.8786.3629.3184.352
necc updated code generator2.6075.0322.5334.0214.7446.5031.6264.463

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.

Workload2ebbb9d (ms)e1eab18 (ms)TinyCC (ms)
Run one million Lua calls605.81498.10168.98
Emit C for Nelua matrix multiplication1077.34984.03746.34
Compile the Lua VM to an object160.26138.4323.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.

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.

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.

Median milliseconds for each SDK · 21 November 2026
PhaseTiny C, beforeTiny C, updated128 functions, before128 functions, updated
TinyCC preprocessing1.6461.7555.5861.999
necc frontend (--cc1)1.5041.4122.8412.774
necc -S on preprocessed C1.4831.4742.8882.894
TinyCC assembly1.6121.6112.6352.684
Complete necc compile2.5342.5158.9535.425
Complete TinyCC compile1.7791.8292.3132.437

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.

WorkloadPrevious necc (ms)GCC-built necc (ms)Fastest external (ms)
Compile 128 functions16.0388.7271.506 · TinyCC
Run six million arithmetic iterations20.2779.3712.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.

Build the distro

nebuild runs the build graph that uses necc to compile Nebox and package the Theseus boot image.