Pizfix: The Original Fil-C Staging Area

Fil-C is fanatically compatible with C/C++ at the source level, but not compatible at all at the ABI level. This means that:

• Fil-C cannot share headers with your system. You cannot #include anything from /usr/include, for example.

• Fil-C cannot share libraries with your system. You cannot link to anything in /usr/lib, for example.

Fil-C requires its own separate slice of headers, libraries, and executables. This document describes the simplest approach, called the Pizfix, which makes it easy to have a self-contained installation of Fil-C headers and libraries without requiring root privileges.

Two alternatives to the Pizfix are /opt/fil and the Pizlix Linux distribution.

The Pizfix Slice

When you install Fil-C the "pizfix" way, either from source or from binary, you will get relevant libraries, binaries, and headers in two places, assuming you unpacked Fil-C in the fil-c directory:

• fil-c/build/ contains clang and clang's own headers. For example, you can run clang using fil-c/build/bin/clang or fil-c/build/bin/clang++.

• fil-c/pizfix/ contains the Fil-C system headers and libraries. For example:

  • fil-c/pizfix/include/ contains libc headers.

  • fil-c/pizfix/stdfil-include/ contains Fil-C headers like stdfil.h and unwind.h (Fil-C has the functionality of libunwind built in).

  • fil-c/pizfix/os-include/ contains symlinks to kernel headers.

  • fil-c/pizfix/lib/ contains Fil-C libraries, including libc.so and libpizlo.so.

  • fil-c/pizfix/lib_test/ contains a version of libpizlo.so that enables internal assertions. You can set LD_LIBRARY_PATH to point to this directory if you want to run with aggressive internal checking (which can cost a lot of perf).

  • fil-c/pizfix/lib_gcverify/ contains a version of libpizlo.so that has the GC verifier enabled by default. You can set LD_LIBRARY_PATH to point to this directory if you want to run with the verifier. The verifier makes the GC a lot slower. You can also enable the verifier with the FUGC_VERIFY=1, FUGC_MIN_THRESHOLD=0, and FUGC_THRESHOLD_MULTIPLIER=1.01 environment variable settings. Using the library in this directory instead of environment variables is appropriate for those cases where it's easier to interpose a library than to set environment variables.

  • fil-c/pizfix/lib_test_gcverify/ contains a version of libpizlo.so that has internal assertions and the GC verifier enabled by default.

This allows for users to easily set up a Fil-C slice anywhere on their Linux machine, and the Fil-C compiler and loader both search for headers and libraries in the pizfix. The compiler knows to do this by finding the pizfix relative to the location of its own binary. The clang driver is just doing this logic:

1. Observe that the clang binary is at filc/build/bin/clang.

2. Locate clang's own headers in filc/build/bin/../lib/clang/20/include.

3. Locate the pizfix at filc/build/bin/../../pizfix.

4. Locate the headers in filc/build/bin/../../pizfix/include, filc/build/bin/../../pizfix/stdfil-include, and filc/build/bin/../../pizfix/os-include.

5. Locate the libraries in filc/build/bin/../../pizfix/lib.

When installing additional libraries and software, it's easiest to tell the build system that --prefix=fil-c/pizfix - i.e. put all software in the pizfix staging area. Additionally, it's useful to build pkgconf and put it in the pizfix and then run all build systems with PATH=fil-c/pizfix/bin:$PATH so that various packages in the pizfix are able to find one another the "pkg" way.

Currently, the Fil-C clang will only pull this trick if it locates the pizfix. Otherwise, it will look for headers and libraries the normal Linux way (i.e. /usr/include, /lib, and /usr/lib). In other words, Fil-C is already set up to support being used as the primary slice of a Linux distribution with a Fil-C userland.