Documentation

Notes on building software with Fil-C through Nix: how to use the results, how the toolchain is maintained, what individual ports needed, and how the port campaigns run. The repository's README gives the overview. These pages are also published at https://mbrock.github.io/filnix/docs/.

Using filnix

/opt/fil without Nix: a tarball of the Fil-C toolchain and memory-safe programs in upstream's /opt/fil layout.
A relocatable Fil-C root: the same toolchain and programs in a directory that works wherever it is unpacked.
Fil-C NixOS and finix: the module that makes a whole system's pkgs the Fil-C set, the base images, what stays native and what it costs, and how to check what runs Fil-C.
A Fil-C userland for NixOS: the record: what it took, and what is still open.
The public AMI and its AWS account: how releases register the AMI, the account's setup, and https://filc.less.rest.
A Fil-C userland for finix: build a whole finix userland with Fil-C.
PHP on Fil-C: PHP 8.5, practical server performance, distributions and the experimental LLVM JIT.
PHP port notes: implementation details, historical benchmarks and version-specific tests, including the early C-emitting JIT.
PHP extensions on Fil-C: PECL and bundled extensions beyond Nixpkgs' default set.
Determinate Nix under Fil-C: Determinate Systems' Nix fork, with its test suites.

Compiler and toolchain

Hacking on the Fil-C compiler without Nix rebuilds: the incremental filc-llvm dev shell.
Updating Fil-C sources and ports: the release and staging toolchain pins and how to move them.
Fil-C 0.687 port import: upstream changes, package-local integration fixes, and validation results.
Fil-C behaviour found while porting: compiler and runtime findings to report upstream, each with its filnix workaround.
Sealed closures: a staging-only proof of concept for closures whose callers cannot read or replace their data.
zmark_shared: pointers inside shared mappings: a staging-only rule, opted into with -fzmark-shared, that lets multi-process servers such as PostgreSQL keep pointers in shared memory.
Fil-C symbols and libtool: why libtool's nm probe fails on Fil-C objects.
zstd with SaRCAsm: zstd's BMI2 assembly decoder loops through the SaRCAsm assembler.
Function-order shuffling (funkyenv) meets Fil-C: whether seeded per-deployment section shuffling fits Fil-C, why the upstream overlay silently breaks the Fil-C bintools, and a staged design for a filnix-native version.

Notes on ports

Boehm GC on FUGC: the libgc API implemented on Fil-C's own garbage collector.
jemalloc on Fil-C's allocator: jemalloc's API on the garbage-collected heap.
Guile 3.0 on Fil-C: GNU Guile on the libgc API above.
GTK, GObject introspection and GnuTLS: GTK3, GTK4 and their GNOME and TLS dependencies.
TPM2-TSS on Fil-C: the full upstream test suite.
Trealla with Fil-C: the Trealla Prolog interpreter.
QuickJS in place of Node.js: which packages need Node on the Fil-C host and where QuickJS stands in.
PCRE2's JIT and the Fil-C LLVM JIT: why sljit cannot run, and a prototype that lowers its LIR to LLVM IR for Fil-C's JIT.
Data race in Determinate Nix's parallel evaluation: a failed thunk's shared exception mutated across threads.
Gem porting workflow and Ruby porting patterns (plain text): Ruby and its native gems.

Thread cancellation

Thread cancellation: what Fil-C needs to get right: the explanation; start here.
Proposed cancellation semantics for Fil-C glibc
Fil-C cancellation implementation checkpoint
Thread cancellation: research notes: the source audit and experiment record.
Raw results: glibc comparison and implementation (plain text).

Port campaigns

What campaigns mean: a frozen, bounded observation of named roots at one revision, with its expected compatibility baseline.
The campaign service: queued campaigns of survey-style builds (port campaigns, the nanofil survey, benchmarks), campaignctl, and the campaign list at https://nix.swa.sh/.
Native Fil-C port campaigns: operating port campaigns and the cache publishers.
Publishing campaign builds: the two public binary caches.
Selecting packages to try with Fil-C
Fil-C port version audit
Shared-library campaign repairs
Focused repairs after the shared-cancellation campaign
Campaign failure review, October 6, 2026