Skip to main content

Crate offlineasm_macros

Crate offlineasm_macros 

Source
Expand description

Provides the offlineasm! proc macros.

Both macros accept a file path (as a string literal) or the offlineasm code written inline as ordinary tokens. The inline form takes no string wrapper:

ⓘ
offlineasm!("asm/program.asm");

offlineasm! {
    global _offlineasmTest
    _offlineasmTest:
        move t0, 42
        ret
}

§Choosing a configuration

Offlineasm sources are compiled once per settings configuration (#if style: which backend, whether pointers are 64-bit, …). There are two modes:

  • settings { ... } (recommended). Each entry maps an offlineasm setting to a Rust cfg predicate, which is resolved at compile time:

    ⓘ
    offlineasm! {
        settings {
            X86_64 = target_arch = "x86_64",
            ARM64 = target_arch = "aarch64",
            HAS_AVX = target_feature = "avx",
        }
        global _offlineasmTest
        _offlineasmTest:
            ret
    }

    Exactly one configuration is compiled: the one in which the listed settings hold the values their predicates resolved to, and every other offlineasm setting is false. The emitted items are not gated, so the generated symbols can be used directly.

  • Without a settings block, every valid, non-erroneous, working-backend settings combination is emitted, each guarded by a #[cfg(...)] predicate standing in for the preprocessor #if OFFLINE_ASM_... / #endif test:

    • non-RLoop backends emit #[cfg(predicate)] global_asm!(TEMPLATE, ident = const EXPR, ...).
    • the RLoop (portable interpreter loop) backend emits Rust source lines rather than a global_asm!, so it becomes #[cfg(predicate)] mod <unique> { ...rust lines... }.

offlineasm_include! additionally registers the file’s directory (or, for inline input, the invoking crate’s CARGO_MANIFEST_DIR) as an offlineasm -I include directory.

Compile-time failures (parse errors, lowering errors, a configuration whose generated Rust doesn’t tokenize) become compile_error!(...) in the macro’s expansion rather than a proc-macro panic, so they show up as ordinary, readable build errors / IDE diagnostics.

Macros§

offlineasm
Compiles offlineasm source given as a path or inline tokens.
offlineasm_include
Compiles offlineasm like offlineasm!, with an include directory registered.