code-native

Write a native .so module for the Code programming language in Rust — link "x.so" as m

emit particle to m from .code source, with the handler behind m implemented here instead of C.

This is the Rust-specific path into code's native-module ABI (src/code_abi.h in the main repo). C — and anything else that can produce a C-ABI shared library — still uses that header and src/runtime.c directly; there's no package registry to publish a C-language bundle to, so that story is unchanged. This crate exists so a Rust module doesn't need a checkout of the code repo at all: cargo add code-native pulls in everything required, including a real runtime.c compiled and linked in by this crate's build.rs — not a Rust reimplementation of it, so there's no risk of the refcounting subtly drifting from what the host trusts.

Quick start

# Cargo.toml
[lib]
crate-type = ["cdylib"]

[dependencies]
code-native = "0.1"

// src/lib.rs
use code_native::*;

#[no_mangle]
pub extern "C" fn code_module_abi_version() -> u32 {
    CODE_ABI_VERSION
}

#[no_mangle]
pub unsafe extern "C" fn code_module_dispatch(out: *mut CodeValue, particle: *const CodeValue) {
    let particle = &*particle;
    match read_field_str(particle, "_class") {
        Some("Double") => {
            let value = read_field_number(particle, "value").unwrap_or(0.0);
            make_result(&mut *out, c"DoubleResult", |slot| number(slot, value * 2.0));
        }
        other => runtime_error(&format!("unknown handler: {other:?}")),
    }
}

cargo build --release
# target/release/libmymodule.so

-- my_script.code
link "libmymodule.so" as m
emit Double { "_class": "Double", "value": 21 } to m get result
assert result.value = 42

Run it with code run my_script.code, or code build my_script.code to compile a native binary that dlopen's the module at startup — both output modes accept a .so the same way.

Why only two required exports

code_module_abi_version and code_module_dispatch are it. There's no code_module! macro generating boilerplate here (unlike the old language's own code-native, which generated a whole descriptor table of handlers/vars/types/emissions): the new ABI dropped that design for one function a module dispatches through itself — see docs/todo/native-module-linking.md in the main repo for why. code_release needs no code from you at all — it comes from the runtime.c this crate links in automatically.

Exported variables

Optional third export, code_module_vars, is what makes m.someConst work alongside emit ... to m:

use code_native::*;
use std::sync::OnceLock;

static VARS: OnceLock<CodeVarList> = OnceLock::new();

#[no_mangle]
pub extern "C" fn code_module_vars() -> *const CodeVarList {
    VARS.get_or_init(|| {
        let mut buf = SlotBuffer::new(1);
        number(buf.slot_mut(0), 3.14159);
        let values = buf.slot_mut(0) as *mut CodeValue;
        // Both leaked deliberately: the ABI requires this data to stay
        // valid for the module's whole lifetime, the same requirement a C
        // module meets with `static` storage.
        std::mem::forget(buf);
        let names: &'static [*const std::ffi::c_char] = Box::leak(Box::new([c"pi".as_ptr()]));
        CodeVarList { count: 1, names: names.as_ptr(), values }
    })
}

See code_abi.h's own doc comment (vendored into this crate at vendor/code_abi.h) for the full CodeVarList contract — this crate mirrors it field-for-field rather than hiding it, since building the 'static-lifetime buffer correctly is easier to get right by following the same shape a C module uses than behind a leaky abstraction.

`.a` static modules

Only .so is covered above (it's code_abi.h's "primary format" — the one artifact both code run and code build accept). A .a static module uses a different, simpler contract — no deep-copy boundary, no per-module code_release, but with its own symbol-prefixing requirement since every .a linked into one program shares a flat symbol table. This crate doesn't cover that path yet; see code_abi.h's ".a static modules" section and tests/native_modules/test_math_static.c in the main repo.

Safety

Most of this crate's surface is safe Rust, but code_module_dispatch itself is necessarily unsafe extern "C" fn — it's called across an FFI boundary with a raw pointer the host guarantees is valid, which Rust has no way to express short of unsafe. Everything you do inside the handler (read_field_str, number, make_result, …) is safe.

code-native on crates.io already has 0.2.0 published under this same repo + account, from the old language — a completely different API (the macro/descriptor-table design this README's "Why only two required exports" section explains is gone) and a different license (that one's MIT; this one is GPL-3.0, since it links runtime.c from the main repo directly rather than reimplementing it). That's why this package starts at 1.0.0 rather than continuing the 0.2.x line: a real break — API and license both — deserves a major version, not one a ^0.2 pin would silently accept. (Same call crates/code-wasm made for its own npm package, for the same reason.)

Releasing (maintainers)

Published via crates.io Trusted Publishing (OIDC) from GitHub Actions (.github/workflows/publish-crates-native.yml) — no CARGO_REGISTRY_TOKEN stored anywhere, mirroring crates/code-wasm's npm Trusted Publishing setup.

One-time setup (crates.io account configuration, can't be done from CI) — normally the very first publish has to be manual, since crates.io has no equivalent to npm's Staged Packages for configuring a trusted publisher before a crate exists at all. Not needed here: the crate already exists (see above), owned by the same account doing this setup, so go straight to its Settings → Trusted Publishing page and add:

Repository owner: codelovesme
Repository name: code
Workflow filename: publish-crates-native.yml
Environment: leave blank

Every release after that is just:

git tag code-native-v1.0.0   # whatever the new version is — no `v` prefix elsewhere
git push origin code-native-v1.0.0

The workflow sets Cargo.toml's version from the tag itself, verifies the package builds standalone (cargo publish --dry-run), and publishes. workflow_dispatch (the "Run workflow" button in the Actions tab) does everything except the actual publish — a real dry run against the exact package that would ship.

License

GPL-3.0 — see LICENSE. This crate links runtime.c from the main code repo directly (vendored, not reimplemented), so it carries the same license.

code-native 1.0.0