简体中文

Assembly syntax for instructions. A real compile-time language for everything around them.

XIRASM is built for assembly programmers who want direct control without being trapped in an old directive dialect or fragile text-macro tricks.

Write instructions normally. When the source needs calculation, generation, reuse, or transformation, use typed values, functions, control flow, collections, modules, file data, and token matching.

The result is one assembler language for handwritten instructions, generated code, binary layouts, and native output formats across x86 and RISC-V.

• Normal ISA text stays normal. Write labels and processor instructions directly; no function-call wrapper is required around assembly.
• Compile-time programming replaces text-macro puzzles. Typed values, functions, lexical scope, if/else if, while, for, break, and continue express generation logic directly.
• Data and formats use the same language. Structs, unions, float and integer emission, reserve operations, modules, files, JSON, TOML, lists, maps, and token matching compose without a second directive dialect.
• The frontend owns assembly semantics. Source spans, symbols, fragments, fixups, layout, relaxation, diagnostics, and output remain explicit; ISA encoders are narrow leaf backends.
• One project model covers x86 and RISC-V. The same compile-time language drives x86, x86-64, RV32, and RV64 sources.

Instructions remain assembly. Repetitive work becomes normal compile-time code:

x86.use64();

fn emit_square_table(count: u8) {
    for value in range(0, count) {
        dd(value * value);
    }
}

const answer: u32 = 40 + 2;

entry:
    mov eax, answer
    ret

table:
emit_square_table(4);

The function and loop execute only while assembling. The output contains the machine code and generated table, not a runtime interpreter.

The language also provides:

• typed constants and variables;
• reusable functions and lexical scope;
• lists, maps, strings, and byte sequences;
• structs, unions, packing, alignment, and reserved data;
• modules and imports;
• JSON, TOML, and file-driven generation;
• token matching for compact source DSLs;
• assertions with source-positioned diagnostics.

Build with Zig 0.17:

zig build -Doptimize=ReleaseSafe

Create hello.asm:

x86.use64();

entry:
    mov eax, 42
    ret

Assemble a flat binary from the repository build:

./zig-out/bin/xirasm hello.asm --target x86-64 -o hello.bin

On Windows, run zig-out\bin\xirasm.exe. An installed xirasm can be used directly from PATH.

Create a ready-to-build native project:

xirasm init hello-win --isa x86-64 --os windows --abi msvc
xirasm init hello-linux --isa x86-64 --os linux --abi sysv

Each generated project contains xirasm.toml; run xirasm build inside that project to assemble its configured source and output.

The compile-time language and project structure stay consistent across targets.

XIRASM can directly produce:

• flat and application-specific binaries;
• PE32 and PE64 Windows executables and DLLs;
• COFF32 and COFF64 object files;
• ELF32 and ELF64 executables;
• ELF64 position-independent executables;
• ELF32 and ELF64 object files;
• ELF64 shared libraries.

Executable-format projects use the ordinary format library:

import("format/format.inc");

The CLI can also create ready-to-build Windows and Linux starter projects. Detailed PE, COFF, and ELF examples belong in the Executable Formats Guide.

The standalone XIRASM VS Code extension provides highlighting, completion, navigation, and compiler-backed diagnostics.

• Language Guide - learn the compile-time language and assembler model.
• Executable Formats Guide - build PE, COFF, and ELF programs with the ordinary format API.
• Advanced Format Construction Guide - use direct format helpers when manual control is required.
• Language API Reference - look up syntax and built-in APIs.

Current version: 0.2.7

XIRASM is pre-1.0 software: the assembler, language API, format library, CLI, and editor integration are usable now, while public contracts may still be refined before 1.0. Repository gates exercise the documented API surface, positive and negative source fixtures, allocation-failure paths, release-safe builds, and the clean public-package boundary.

Apache-2.0.