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 services on NixOS: swap chosen NixOS services for their Fil-C builds and leave the rest of the system alone.
A Fil-C userland for finix: build a whole finix userland with Fil-C.
PHP on Fil-C: PHP 7.4, 8.4 and 8.5, distribution tarballs, the Docker image, and the experimental opcache JIT compiled through C.
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 behaviour found while porting: compiler and runtime findings to report upstream, each with its filnix workaround.
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.

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.
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

Native Fil-C port campaigns: the runner and the dashboard at https://nix.swa.sh/.
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