Rux Compiled Unit

A Rux Compiled Unit (RCU, .rcu) is the object format of the Rux compiler. Each back end — x86-64 and AArch64 — encodes its instructions itself and stores them, with symbols and relocations, in one RCU per compiled source file. The Rux linker reads the units of a build and writes the target's container: a PE image on Windows, ELF on Linux and FreeBSD, Mach-O on macOS, or a relocatable object or static archive in the target's own format. No external assembler, compiler or linker takes part.

A normal build keeps its units in memory. rux build --emit rcu also writes them out, as Temp/Obj/<file>.rcu, with a readable dump of each in Temp/Rcu/<file>.rcu.txt (see rux build).

flowchart LR
    src["`Src/*.rux`"] --> fe["front end<br/>HIR, LIR"]
    fe --> x64["x86-64 back end"]
    fe --> a64["AArch64 back end"]
    x64 --> rcu["RCU units"]
    a64 --> rcu
    rcu --> link["Rux linker"]
    link --> out["PE, ELF or Mach-O"]

File layout

All multi-byte integers are little-endian, and every field sits at the exact offset listed — there is no implicit padding. The regions follow one another in this order:

┌──────────────────────────────────────────┐ offset 0
│ File header                    32 bytes  │
├──────────────────────────────────────────┤ offset 32
│ Section table       section_count × 40   │
├──────────────────────────────────────────┤ 32 + section_count × 40
│ Symbol table         symbol_count × 20   │
├──────────────────────────────────────────┤
│ For each section, in table order:        │
│   raw data        (aligned to section)   │
│   relocations     (aligned to 4)         │
├──────────────────────────────────────────┤
│ String table      string_table_size      │
├──────────────────────────────────────────┤
│ Rux metadata  64 bytes (aligned to 8)    │ when present
└──────────────────────────────────────────┘

Every gap introduced by alignment is filled with 0x00. A reader needs only the header to find everything else.

File header

The architecture byte names the processor only. Operating system and calling convention are not recorded: the instruction bytes were generated for one target, and the linker is told which one it is linking for. A unit is only meaningful to a link for the same architecture, and the linker rejects any other.

A reader must reject a file whose magic differs, and should reject one whose major version is newer than it understands.

Section table

section_count entries of 40 bytes, starting at offset 32.

An empty section still has a raw_offset — the aligned position its bytes would start at.

Both back ends emit the same three sections, always in this order:

Symbol table

symbol_count entries of 20 bytes, starting right after the section table.

An external symbol has section_idx = 0xFFFF and value = 0; it is a reference to a definition in another unit of the link or, for an extern declaration, to a shared library.

The linker binds each reference to exactly one definition and reports a duplicate or a missing one. An executable's root is Main; a library's roots are its exported definitions.

Relocations

Each section's relocations are an array of 16-byte entries at reloc_offset.

In the formulas, S is the symbol's address, A the addend and P the address of the patched field. Types below 16 patch a whole little-endian field and are architecture-neutral; types from 16 patch bit fields of one AArch64 instruction word and keep the names of their ELF counterparts.

A displacement that does not fit its field, or a misaligned load/store target, is a link error that names the symbol.

String table

A flat block of NUL-terminated UTF-8 strings. Offset 0 is always the empty string, so a 0 offset anywhere means "no name". Each distinct string is stored once. The writer interns, in this order: the source path, the package name, each symbol's name and type spelling, and the section names. Symbol and section names are printable ASCII; the source path may be any UTF-8.

Metadata

When F_HAS_METADATA is set, a 64-byte block sits at metadata_offset, aligned to 8. The compiler writes it into every unit.

Checksum

checksum is a CRC-32C — the Castagnoli polynomial, reflected form 0x82F63B78, initial value and final XOR 0xFFFFFFFF — over every byte of the file, with the checksum field itself counted as four zero bytes. It is computed last, after every other field is written. It is deliberately not the IEEE CRC-32 of ZIP, so the two are not interchangeable.

Example

Src/Main.rux of a package called Math:

func Add(a: int32, b: int32) -> int32 {
    return a + b;
}

func Main() -> int {
    return Add(3, 4) as int;
}

rux build --emit rcu --target linux-x86_64 writes Temp/Obj/Main.rcu, whose dump begins:

; RCU  Rux Compiled Unit  v1.0
; Architecture: x86-64
; Package:       Math
; Rux version:   0.4.0

Sections: 3
  [ 0]  .text       flags:AER    align:16    data:239B  relocs:1
  [ 1]  .rodata     flags:AR     align:8     data:0B  relocs:0
  [ 2]  .data       flags:ARW    align:8     data:0B  relocs:0

Symbols: 2
  [  0]  Add     .text+0x0000  size=150     FUNC      LOCAL   "int32"
  [  1]  Main    .text+0x0096  size=89      FUNC      LOCAL   "int"

Relocations (.text):
  [  0]  off=0x00CE  sym[0]=Add  REL_32  addend=0

The one relocation is the call Add inside Main: four placeholder bytes at .text + 0xCE that the linker replaces with Add − (P + 4). Built for linux-aarch64 instead, the same call is a bl patched by an AARCH64_CALL26 relocation.

With a source path of 120 bytes, the file is laid out as follows:

and its header reads:

52 43 55 00   magic              "RCU\0"
00 01         version            0x0100
01            arch               x86-64
01            flags              F_HAS_METADATA
03 00         section_count      3
00 00         _reserved
02 00 00 00   symbol_count       2
C0 01 00 00   string_table_off   0x1C0
A6 00 00 00   string_table_size  166
68 02 00 00   metadata_offset    0x268
xx xx xx xx   checksum           CRC-32C, computed last

See also

• Assembly — asm func bodies, whose symbols become relocations
• rux build — --emit rcu and the other inspection outputs
• Linking — external symbols bound to shared libraries