`bld`

Build system - compile C/native sources from ilusm, with configurable compiler flags, cross-compilation targets, static linking, and a content-addressed build cache.

Load with: use bld

What this module does

bld lets you invoke the system C compiler (or any other compiler) from ilusm code with a structured config object rather than hand-crafting shell strings. You describe the source file, output binary, compiler, flags, and optional cross-compile target, and bld builds the shell command and runs it via os.run.

The cached variant (bldc3) hashes the build config with SHA-256 and stores the compiled output in a cache directory (default .ilusm-cache). On a cache hit it copies the cached binary to the output path instead of recompiling.

Quick example

use bld

# Basic compile
cfg = bldcf("src/main.c", "out/main", [{cc: "gcc", cflags: "-O2 -Wall"}])
bldcc(cfg)

# Static cross-compile for ARM
cfg = bldcf("src/main.c", "out/main-arm", [{
    cc: "arm-linux-gnueabihf-gcc",
    target: "arm-linux-gnueabihf",
    static: tru,
    cflags: "-O2"
}])
bldcc(cfg)

# Cached compile - only recompiles if config changes
bldc3(cfg)

Functions

Shell quoting

bldsq(s)

Wraps a string in double quotes, escaping any embedded double quotes with a backslash. Used internally to safely include file paths in shell commands.

Config

bldcf(src, out, opts)

Creates a build config object. Defaults: cc: "cc", cflags: "-O2", ldflags: "", target: "", static: fls, cache_dir: ".ilusm-cache". Any keys in the first element of opts (an object) override the defaults.

bldky(cfg)

Computes a content-addressed cache key for a config by SHA-256 hashing the JSON-encoded config object. This key uniquely identifies a particular build configuration.

Command generation

bldcm(cfg)

Builds the shell command string for the compile step. Produces: [TARGET="{target}" ]{cc} {cflags}[-static] "{src}" -o "{out}" [{ldflags}]. The TARGET= prefix is only included if target is non-empty. -static is included only if static: tru.

Compiling

bldcc(cfg)

Compiles without caching. Runs the command from bldcm(cfg) via os.run. Returns the output path (cfg.out).

bldc3(cfg)

Compiles with caching. The cache path is {cache_dir}/{out_with_slashes_replaced}_{sha256_key}. If that path exists, copies it to cfg.out instead of recompiling. If not, compiles with bldcc, creates the cache directory, and copies the result into the cache. Returns the output path.

bldcp(cfg)

Returns the cache file path for a given config without compiling.

Notes

All compilation is done by shelling out via os.run - the ilusm process must have access to the compiler in its PATH.
The cache key is based on the entire config object serialised to JSON, then SHA-256 hashed. Changing any config field (even cflags) invalidates the cache entry.
The cache directory is created with mkdir -p on first use - it must be writable.
Requires txt, trl, os, jsn, cry, and fs.