Object Format Guide

The production object path starts in compiler/main.0x0 with a direct ELF64

relocatable writer. The first supported production slice emits a deterministic

ET_REL object for an integer-returning main without routing through GAS.

The compatibility object path in compiler/compat-main.0x0 still emits GAS

x86-64 assembly and lets the generated native compiler assemble or link it with

the host toolchain. That path remains comparison coverage while the direct

writer grows.

Milestone 4 is complete only when compiler/main.0x0 emits the full ELF64

relocatable object slice described below. The current direct writer is real but

limited: it proves the repository owns ELF object headers, section headers,

symbol tables, string tables, ABI notes, deterministic layout, and linkable

machine code for the first integer main slice.

tools/zero-object-info.py is the repository-owned object metadata reader. It

prints deterministic ELF header, section index, section, ABI note, relocation,

and symbol metadata for tests and diagnostics.

Its malformed-object diagnostics are stable enough for tests:

object not found: <path>
unsupported object: missing ELF magic
malformed object: ELF header out of range
unsupported object: expected ELF64 little-endian
unsupported object: expected System V ELF ABI
unsupported object: expected clear ELF ident padding
unsupported object: expected ELF version 1
unsupported object: expected 64-byte ELF header
unsupported object: expected ET_REL
unsupported object: expected x86-64
unsupported object: expected clear ELF flags
unsupported object: expected no entry point
unsupported object: expected no program headers
unsupported object: expected 64-byte section headers
unsupported object: expected STRTAB section names
unsupported object: expected SYMTAB .symtab
unsupported object: expected STRTAB symbol strings
unsupported object: expected 24-byte symbols
unsupported object: expected RELA relocation section
unsupported relocation: <kind>
unsupported object: expected PROGBITS note section
unsupported object: expected PROGBITS .text
unsupported object: expected PROGBITS .rodata
unsupported object: expected PROGBITS .data
unsupported object: expected NOBITS .bss
unsupported object: expected AX .text
unsupported object: expected A .rodata
unsupported object: expected WA .data
unsupported object: expected WA .bss
unsupported object: expected metadata flags clear <section>
malformed object: section header table out of range
malformed object: invalid shstrndx
malformed object: section payload out of range
malformed object: section payloads overlap
malformed object: section name offset out of range
malformed object: duplicate section: <name>
malformed object: section alignment missing
malformed object: section alignment not power of two
malformed object: section alignment mismatch
malformed object: ABI marker missing NUL
malformed object: ABI marker is not UTF-8
malformed object: source marker missing NUL
malformed object: source marker is not UTF-8
malformed object: symtab string link out of range
malformed object: symbol name offset out of range
malformed object: unnamed defined symbol
malformed object: unnamed undefined symbol
malformed object: duplicate defined symbol: <name>
malformed object: symbol section index out of range
unsupported object: expected symbol in loadable section
malformed object: undefined symbol payload nonzero
malformed object: symbol range out of section
malformed object: string table missing initial NUL
malformed object: string table entry missing NUL
malformed object: string table entry is not UTF-8
malformed object: symbol table size not aligned
malformed object: symtab local info out of range
malformed object: missing null symbol
malformed object: invalid null symbol
malformed object: invalid null section
unsupported object: expected default symbol visibility
unsupported object: expected local/global symbol binding
malformed object: symbol binding order mismatch
unsupported object: expected function/object symbol type
unsupported relocation type: <number>
malformed object: relocation symbol link out of range
malformed object: relocation target section out of range
malformed object: relocation section target mismatch
malformed object: relocation symbol index out of range
malformed object: relocation symbol is null
unsupported relocation target section: <section>
malformed object: relocation offset out of range
malformed object: RELA section size not aligned

Current Direct Object Slice

compile-object-i64-chunks-file is the production entry for this slice. It

returns deterministic ELF hex chunks so callers can stream or join them without

requiring the object writer itself to retain one whole output string. It emits

ordinary library objects without requiring a main symbol.

compile-object-i64-file remains a compatibility wrapper that joins those

chunks for smoke tools.

compile-object-main-i64-chunks-file keeps the stricter whole-program

validation and main requirement for single-object compatibility tests.

The chunked writer emits:

• ELF64 ET_REL header;
• .text;
• empty .rodata, .data, and .bss sections in the current integer/call

slice so section indices and linker layout are deterministic before data

payload emission lands;

• .note.0x0.abi;
• .note.0x0.source;
• .symtab;
• .strtab;
• .rela.text when a supported direct call needs relocation;
• .shstrtab;
• one global function symbol for every top-level integer-returning function;
• one local .text.local object symbol covering the generated .text bytes;
• one undefined global function symbol for every supported external direct-call

target;

• deterministic source-path metadata for file-based object emission;
• deterministic section offsets and table ordering;
• section payload offsets aligned to their declared sh_addralign, including

.rela.text and .symtab 8-byte alignment.

The generated .text contains one return stub per supported function. Integer

literal returns use a sign-extending signed 32-bit immediate stub for the

current ABI I64 slice; literals outside that range are rejected instead of

being silently truncated or zero-extended.

For the current call slice, a function body that is a direct call emits a

call rel32 placeholder and an R_X86_64_PLT32 relocation with addend -4

against the callee symbol. The callee may be defined in the same object or left

undefined for zero-link to resolve from another compiler-emitted object.

Local symbols are emitted before globals and are not exported through archive or

linker symbol resolution; they exist so object readers can inspect section-local

metadata without creating cross-object duplicate-symbol failures.

make object-check decodes the emitted hex into an object file, verifies the

ABI marker, links positive and negative integer-return objects with cc, and

checks that the linked processes exit with the expected low-byte statuses.

Legacy Compatibility Object Slice

The compatibility object backend supports the integer/control-flow/function-call

slice through generated GAS assembly:

• integer literals and integer results;
• Unit, true, and false as integer-compatible values;
• integer arithmetic and comparisons;
• if, do, local bindings, function calls, recursion, and up to six

arguments;

• imports loaded through existing (↥ "...") forms.

The generated assembly includes:

.section .note.0x0.abi,"a",@note
  .asciz "0x0 ABI 0.1"

This ABI marker is required now so later compiler-emitted .o files can keep

the same compatibility identity.

Required Full Direct Relocatable Writer

The production object writer must emit ELF64 relocatable objects directly from

0x0 compiler source. It must produce:

• ELF header with ET_REL;
• .text;
• .rodata;
• .data or .bss when required by generated runtime data;
• .symtab;
• .strtab;
• relocation sections for compiler-emitted calls and data references;
• .note.0x0.abi;
• .note.0x0.source source metadata for diagnostics;
• deterministic section and symbol ordering.

Archive Boundary

The current production archive path is tools/zero-ar.py, described in

docs/archive-format.html. It produces deterministic static archives with a

GNU-style symbol index from compiler-emitted objects and streams member payloads

instead of retaining whole archives in memory.

Host ar behavior may be used only as a comparison oracle; it is not part of

the production archive path.

Required Validation

make object-source-check is the lightweight source contract gate. It does not

compile; it verifies that the compiler object writer, zero-object-info,

documentation, and object/linker smoke tests agree on the current ELF64

ET_REL section set, ABI/source notes, global and undefined function symbols,

chunked writer entry points, and R_X86_64_PLT32 relocation contract.

make object-info-check proves repository-owned object inspection for ELF

headers, section metadata, ABI note contents, source metadata, symbols,

relocation byte counts, and relocation target sections.

Relocation rows are printed only after the referenced symbol has passed the

same name, binding, visibility, section, and range checks required for symbol

rows.

make object-info-diagnostics-check verifies stable malformed-object

diagnostics in zero-object-info without invoking the compiler or linker.

make object-chunks-check proves the chunked object entry produces the same

bytes as the compatibility text wrapper and that the decoded object contains the

ABI marker.

make object-symbols-check proves the direct object writer emits multiple

global function symbols and that zero-link still enters main.

make object-relocations-check proves the direct object writer emits

inspectable .rela.text entries for supported calls and that zero-link

applies them for the current same-object call slice.

make linker-multi-object-check proves the direct object writer can emit a

main object with an undefined helper symbol, link it with two other

compiler-emitted objects, apply the cross-object relocation, and reject duplicate

or missing symbols.

make archive-check proves deterministic archive writing, archive symbol

indexes, duplicate archive symbol rejection, and archive linking that extracts

only required members.

make lib0x0-archive-check proves the direct object writer can emit the current

runtime/lib0x0_abi.0x0 runtime object and link a user object against

runtime/lib0x0.a.

make object-check must prove today:

• direct object emission writes and links a real ELF64 relocatable object;
• object assembly includes the ABI marker;
• the current object path links and runs imported integer examples;
• generated direct and compatibility object-path artifacts have stable hashes

for the same source;

• failures for missing symbols, duplicate symbols, and ABI mismatch are added

once direct relocatable objects exist.