Rux Compiled Unit

Binary specification for the .rcu object files emitted by the Rux compiler. The same format is used on every supported operating system — FreeBSD, Linux, macOS, and Windows.

Overview

A Rux Compiled Unit (RCU) (.rcu) is the binary object file emitted by the Rux compiler for each compiled .rux source file. The Rux linker collects one or more RCU files and links them into a native executable for the target operating system — a PE (.exe) on Windows, an ELF binary on Linux and BSD, or a Mach-O binary on macOS.

RCU is the object format for the x86-64 backend only. The AArch64 backend takes a separate route (C generated and compiled through a native Clang toolchain) and does not emit RCU.

Design Goals

Comparison with Common Formats

File Layout

An RCU file consists of six consecutive regions. All multi-byte integer fields are stored in little-endian byte order. Fields are placed at the exact offsets listed — there is no implicit struct padding.

┌──────────────────────────────────────────────┐  Offset 0
│                 File Header                  │  32 bytes (fixed)
├──────────────────────────────────────────────┤  Offset 32
│               Section Table                  │  section_count × 40 bytes
├──────────────────────────────────────────────┤  Offset 32 + section_count × 40
│               Symbol Table                   │  symbol_count × 20 bytes
├──────────────────────────────────────────────┤
│     Section Raw Data + Relocation Arrays     │  one block per section:
│       ┌──────────────────────────┐           │    raw data (aligned)
│       │  section[0] raw data     │           │    followed by relocation
│       │  section[0] relocations  │           │    entries (4-byte aligned)
│       │  section[1] raw data     │           │
│       │  section[1] relocations  │           │
│       │  ...                     │           │
│       └──────────────────────────┘           │
├──────────────────────────────────────────────┤
│               String Table                   │  string_table_size bytes
├──────────────────────────────────────────────┤
│          Rux Metadata  (optional)            │  64 bytes when present
└──────────────────────────────────────────────┘

Reading tip — a reader needs only the 32-byte File Header to locate every other structure. Parse the header first, then use the stored offsets and counts to seek directly to any region.

File Header

The File Header is always 32 bytes and begins at file offset 0.

Architecture

The arch field encodes only the processor architecture, not the operating system or ABI. A single RCU file can therefore be linked on any supported OS; the linker chooses the executable format (PE, ELF, or Mach-O) and the calling convention (Win64 or System V AMD64) for the target. Additional architectures may be assigned in future minor versions.

File Flags

Bits 1–7 are reserved and must be 0.

Version Compatibility

A reader must reject a file whose magic bytes do not match "RCU\0". A reader should reject a file whose version major byte is greater than the highest major version it supports. Minor version differences within the same major version are backward-compatible.

Section Table

The Section Table begins immediately at file offset 32 and contains section_count entries of 40 bytes each.

Section Types

Section Flags

Standard Sections

The Rux compiler always emits exactly three sections in fixed order. User code never names sections explicitly; the compiler assigns data to the appropriate section automatically.

Sections with no generated content are written with raw_size = 0; their virtual_size is 1.

Symbol Table

The Symbol Table begins immediately after the last Section Table entry.

File offset = 32 + section_count × 40

Each entry is 20 bytes.

Symbol Kinds

External symbols (SYM_EXTERN_FUNC, SYM_EXTERN_DATA) always have section_idx = 0xFFFF and value = 0.

Symbol Visibility

Relocation Table

Each section with fix-ups has its own relocation array. A section's array starts at section.reloc_offset and contains section.reloc_count entries of 16 bytes each.

Relocation Types

Variables used in the formulas:

• sym — virtual address assigned to the target symbol by the linker.
• patch_va — virtual address of the first byte of the placeholder field (section_virtual_address + section_offset).
• addend — the signed value stored in the relocation entry.

REL_REL32 — PC-Relative 32-bit Fix-up

REL_REL32 is the most common relocation type for x86-64 code. The assembler emits four zero bytes as a placeholder. The linker replaces them with a signed 32-bit integer according to:

patch = (i32)(sym + addend − (patch_va + 4))

The + 4 in the denominator accounts for the processor advancing RIP past the 4-byte placeholder before adding the displacement.

With addend = 0 (the default emitted by the Rux compiler) the formula covers all standard x86-64 position-relative encodings:

String Table

The String Table is a flat array of null-terminated UTF-8 strings packed consecutively. Byte offset 0 is always \0 — the empty string sentinel. All string-offset fields in other structures are byte offsets into this array.

Offset   Content
 0       \0                          ← always: empty sentinel
 1       "add\0"
 5       "main\0"
10       "fn(i32, i32) -> i32\0"
30       "-> i32\0"
37       "math.rux\0"
46       ...

Strings are encoded in UTF-8. The Rux compiler guarantees that symbol names and section names contain only printable ASCII characters. Source file paths and Rux type strings may contain arbitrary UTF-8.

Rux Metadata

When header.flags & F_HAS_METADATA is set, a 64-byte Rux Metadata block is present at header.metadata_offset. This block is specific to Rux and carries information used by the build system for incremental compilation and by tooling for diagnostics and introspection.

The current Rux compiler emits this block on every unit and always sets F_HAS_METADATA. The block remains optional in the format, so readers must still honour the flag rather than assuming its presence.

Current implementation — the compiler fills in source_path_off, package_name_off, build_timestamp, and rux_version, but does not yet populate source_hash (written as 32 zero bytes) or compiler_flags (written as 0). Both fields are reserved for the incremental-compilation and tooling features below, and the block is emitted now so they can be enabled without a format change.

Compiler Flags

Bits 3–31 are reserved and must be 0.

Alignment and Padding Rules

1. Section Table — begins at file offset 32 with no preceding padding.
2. Symbol Table — begins immediately after the last Section Table entry with no padding (32 + section_count × 40).
3. Section raw data — must begin at a file offset that satisfies offset mod alignment == 0 where alignment is the section's declared alignment. Insert zero-fill padding between consecutive sections as necessary.
4. Relocation arrays — must begin at a 4-byte-aligned file offset. Insert zero-fill padding after section raw data if needed before the relocation array.
5. String Table — byte-aligned; no special alignment required.
6. Rux Metadata block — must begin at an 8-byte-aligned file offset. Insert zero-fill padding after the String Table if needed.

Unused bytes in any padding region must be set to 0x00.

Example: Two-Function Unit

This section shows a complete RCU for the following source file.

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

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

Machine Code — .text (31 bytes)

Calling convention — this listing uses the System V AMD64 ABI (Linux, BSD, macOS), where the first two integer arguments arrive in edi/esi. On Windows (Win64) they would arrive in ecx/edx with 32 bytes of shadow space, so the exact instruction bytes differ per target — the RCU structures around the code do not.

; Add — section offset 0, size 10 bytes
Offset  Bytes             Disassembly
  0     55                push  rbp
  1     48 89 E5          mov   rbp, rsp
  4     01 F7             add   edi, esi        ; b into a (i32)
  6     89 F8             mov   eax, edi        ; return value
  8     5D                pop   rbp
  9     C3                ret

; Main — section offset 10, size 21 bytes
Offset  Bytes             Disassembly
 10     55                push  rbp
 11     48 89 E5          mov   rbp, rsp
 14     BF 03 00 00 00    mov   edi, 3          ; first argument
 19     BE 04 00 00 00    mov   esi, 4          ; second argument
 24     E8 00 00 00 00    call  Add             ; ← REL_REL32 relocation at offset 25
 29     5D                pop   rbp
 30     C3                ret

The four zero bytes at offsets 25–28 are the REL_REL32 placeholder for the call Add instruction.

Symbol Table (2 entries)

Relocation Table for .text (1 entry)

Linker verification — assuming .text is placed at virtual address 0x1000:

• Add_va = 0x1000 + 0 = 0x1000
• patch_va = 0x1000 + 25 = 0x1019
• patch = (i32)(0x1000 + 0 − (0x1019 + 4)) = (i32)(0x1000 − 0x101D) = −29 = 0xFFFFFFE3
• CPU executes E8 E3 FF FF FF → jumps to 0x101D + (−29) = 0x1000 ✓

String Table (37 bytes)

Off   Hex                                           ASCII
 0    00                                            \0 (sentinel)
 1    41 64 64 00                                   "Add\0"
 5    4D 61 69 6E 00                                "Main\0"
10    66 6E 28 69 33 32 2C 20 69 33 32 29 20        "fn(i32, i32) -> i32\0"
      2D 3E 20 69 33 32 00
30    2D 3E 20 69 33 32 00                          "-> i32\0"

File Layout Summary

The compiler always emits three sections. .rodata and .data are empty here (no string literals or global variables), so their raw_size = 0 and virtual_size = 1.

File offset   Region                       Size
  0x0000      File Header                  32 bytes
  0x0020      Section Table  (3 entries)   120 bytes
  0x0098      Symbol Table   (2 entries)   40 bytes
  0x00C0      .text raw data               31 bytes  (alignment 16 → offset 0xC0 = 192, 192 % 16 = 0 ✓)
              [1 byte zero padding]
  0x00E0      .text relocations (1 entry)  16 bytes  (alignment 4  → offset 0xE0 = 224, 224 % 4  = 0 ✓)
  0x00F0      .rodata raw data              0 bytes  (alignment 8  → offset 0xF0 = 240, 240 % 8  = 0 ✓)
  0x00F0      .data raw data                0 bytes  (alignment 8  → offset 0xF0 = 240, no padding)
  0x00F0      String Table                 37 bytes
              [3 bytes zero padding for 8-byte alignment]
  0x0118      Rux Metadata                 64 bytes  (alignment 8  → offset 0x118 = 280, 280 % 8  = 0 ✓)
  0x0158      End of file

File Header Bytes

Offset  Bytes                           Field
  0     52 43 55 00                     magic         "RCU\0"
  4     01 00                           version       0x0100 → v1.0
  6     01                              arch          0x01 → x86-64
  7     01                              flags         F_HAS_METADATA
  8     03 00                           section_count 3
 10     00 00                           _reserved
 12     02 00 00 00                     symbol_count  2
 16     F0 00 00 00                     string_table_off  0x00F0
 20     25 00 00 00                     string_table_size 37
 24     18 01 00 00                     metadata_offset   0x0118
 28     xx xx xx xx                     checksum      (CRC-32C computed last)

Incremental Compilation

The Rux Metadata block is designed to let the build system avoid recompiling unchanged source files:

1. Source hash check — compute the SHA-256 of the .rux file and compare it to source_hash in the metadata. If they match, the source has not changed since the last compilation.
2. Compiler version check — if the installed compiler's rux_version differs from the value stored in the metadata, the file must be recompiled regardless of the hash, because language semantics or code-generation may have changed.

If both checks pass the existing .rcu is used directly; the source file is not read again.

Status — this describes the intended design. The current compiler writes an all-zero source_hash, so the hash-based skip is not yet active. The metadata block is already emitted on every unit, so the mechanism can be turned on later without changing the file format.

Checksum — CRC-32C

The checksum field holds a CRC-32C (Castagnoli polynomial 0x1EDC6F41) computed over the entire file content with the four bytes at offset 28 treated as 0x00000000.

Writers must compute and store the checksum after writing all other fields. Readers may skip validation by checking for checksum == 0; a stored checksum of 0 disables checking.

Implementation Notes

Reading an RCU File

1. Read 32 bytes from offset 0 → File Header.
2. Verify magic == 0x52, 0x43, 0x55, 0x00.
3. Verify version major byte <= supported major version.
4. Read section_count × 40 bytes at offset 32 → Section Table.
5. Read symbol_count × 20 bytes at offset (32 + section_count × 40) → Symbol Table.
6. Read string_table_size bytes at string_table_off → String Table.
7. For each section entry: a. If raw_size > 0, read raw_size bytes at raw_offset → section data. b. If reloc_count > 0, read reloc_count × 16 bytes at reloc_offset → relocations.
8. If flags & F_HAS_METADATA, read 64 bytes at metadata_offset → Rux Metadata. Verify metadata magic == 0x4D, 0x45, 0x54, 0x41.
9. If header.checksum != 0, validate CRC-32C.

Writing an RCU File

1. Assemble sections, symbols, relocations, and strings from the code-generation stage.
2. Intern all strings (names, type strings, paths) into the String Table.
3. Compute section_count, symbol_count, and all file offsets (write 0 into header.checksum as a placeholder).
4. Write regions in order: File Header → Section Table → Symbol Table → for each section: raw data (aligned) + relocation array (4-byte aligned) → String Table (no alignment) → Rux Metadata (8-byte aligned, optional).
5. Compute CRC-32C over the complete file content (treating offset 28 as zero).
6. Seek to offset 28 and write the 4-byte checksum.

Linker Responsibilities

The Rux linker processes a set of RCU files to produce a native executable for the target operating system:

1. Collect and merge all same-named sections (.text, .rodata, .data, .bss).
2. Resolve all symbols: pair each SYM_EXTERN_* reference with its VIS_GLOBAL or VIS_WEAK definition; report an error for any unresolved symbol.
3. Assign virtual addresses to all merged sections.
4. Apply all relocations using the formulas in Relocation Types.
5. Emit an executable in the target's native format — PE/COFF on Windows, ELF on Linux and BSD, or Mach-O on macOS — with the appropriate headers, an import table for external symbols (for example a PE .idata section for Windows API calls, or dynamic-linking entries on ELF and Mach-O), and the merged section data.