firebuild.conf

// Default configuration file for Firebuild

version = 1.0;

// enviromnent variables passed to the build command
env_vars = {
  // the following environment variables are passed to the build command unchanged
  // Note that if DYLD_LIBRARY_PATH is not set on MacOS, it is set by firebuild
  // to the path where libfirebuild is installed.
  pass_through = [ "HOME", "PATH", "SHELL", "PWD", "LD_LIBRARY_PATH", "DYLD_LIBRARY_PATH"];

  // These env vars are skipped when computing an intercepted command's fingerprint.
  fingerprint_skip = [ "MAKE_TERMOUT", "MAKE_TERMERR" ];

  // The folloving environment variables are pre-set to the values configured below.
  // Note that FB_SOCKET, FB_READ_ONLY_LOCATIONS, FB_IGNORE_LOCATIONS, FB_JOBSERVER_USERS
  // and LD_PRELOAD (DYLD_INSERT_LIBRARIES and DYLD_FORCE_FLAT_NAMESPACE on OS X)
  // are also set by firebuild internally.
  // The variables should be in "NAME=value" format.
  preset = [
    // Make ccache call the original compiler. This allows firebuild rather than ccache
    // cache the build results. To enable ccache's caching in firebuild-intercepted builds
    // don't set CCACHE_DISABLE=1 and add "ccache" to the processes.dont_shortcut list.
    "CCACHE_DISABLE=1"
  ];
};

processes = {
  // Shortcut only the listed processes (together with their descendants).
  // This can keep the cache size really small and allows limiting shortcutting to
  // the known to be well-behaving processes.
  // Note that the descendants are not shortcut on their own, only if they are listed here, too.
  shortcut_allow_list = [];

  // Processes that should always be executed. This means that their ancestors
  // can't be cached and shortcut either.
  dont_shortcut = [
    // orchestrating tools that compare timestamps
    "make", "ninja",
    // Sleep is used sometimes to provide periodic status of the build, which breaks if sleep is shortcut
    // and finish very fast. By default the sleep command is shortcut. Disable shortcutting if your build
    // system relies on sleep's original behavior.
    // "sleep",
    // Part of the file information returned by stat() e.g. inode number is ignored
    // for shortcutting purposes and is not stored in the cache. As a result the stat command
    // would very often provide invalid output when shortcut thus it is safer to just not shortcut it.
    "stat",
    // The ls command can print inodes and other ignored file information, too.
    "ls"
  ];

  // Processes that should not be intercepted. This means that they and their ancestors
  // and children can't be cached and shortcut either.
  dont_intercept = [
    // starts a daemon and causes deadlock with interception enabled
    "fakeroot",
    // Similar build accelerator which is unlikely to be shortcut efficiently.
    // Interception is enabled because firebuild also sets CCACHE_DISABLE=1 by default thus
    // ccache will just call the original compiler.
    // "ccache",
    // hangs, also has its own caching framework
    "gradle",
    // Go has its own caching framework
    "go"
  ];

  // Processes that we could cache and shortcut, but prefer not to (for example
  // because they are fast enough).
  // This has no effect on potentially caching and shortcutting their ancestors.
  skip_cache = [
    // The default shell. Not caching it may improve performance of builds running a lot of
    // very quick shell scripts.
    // "sh",
    // coreutils
    "arch", "basename", "cat", "chgrp", "chmod", "chown", "cp", "cut",
    "dd", "dir", "dirname", "expr", "head", "install", "link", "ln",
    "mkdir", "mv", "readlink", "realpath", "rm", "rmdir",
    "seq", "tail", "touch", "tr", "unlink",
    // usually shell builtins, but not always
    "[", "echo", "false", "printf", "pwd", "test", "true",
    // other standard utils
    "egrep", "fgrep", "grep", "rgrep", "sed"
  ];

  // Shells to cache instead of child when the shell just executes the child.
  // For example "foo ..." is not cached, when its parent /bin/sh -c "foo ..." can be cached instead.
  shells = [
    "/bin/bash",
    "/bin/dash",
    "/bin/sh",
    "bash",
    "dash",
    "sh"
  ];
  // Programs that use Make's or a similar jobserver.
  // Firebuild ignores the below programs' communication over jobserver fds to allow shortcutting
  // them.
  // Only the file name without the directory name can be listed here,
  // for example list "rustc" instead of "/usr/bin/rustc".
  jobserver_users = [
    "cargo",
    // Make is not shortcut by default, thus its communication over the jobserver fds does not make
    // a difference.
    // "make",
    "rustc"
  ];
};

// Ignore operations affecting these files, directories, or any
// location under these directories.
ignore_locations = [
  "/dev/autofs_nowait",
  "/dev/full",
  "/dev/null",
  "/dev/random",
  "/dev/tty",
  "/dev/urandom",
  "/dev/zero",
  "/proc/cpuinfo",
  "/proc/filesystems",
  "/proc/net",
  "/proc/meminfo",
  "/proc/self",
  "/proc/stat",
  "/sys/devices",
  "/sys/fs/cgroup",
  // sockets connected to on macOS
  "/var/run/syslog",
  "/var/run/usbmuxd"
];

// These files, directores, or any location under these directories assumed to be
// read-only files not changing while firebuild is running. Opening a file with
// those prefixes does not delay program execution while the file hash is saved.
read_only_locations = [
  "/bin", "/etc", "/lib", "/lib32", "/libx32", "/lib64", "/opt", "/proc/sys", "/sbin", "/snap", "/usr"
];

// Only cache results of processes consuming more CPU time (system + user) in seconds than this value.
// The CPU time includes all children's CPU time. If a process cached its ancestors can still be cached
// if their cumulative CPU time exceeds this limit.
min_cpu_time = 0.000;

// Quirks are adjustments of firebuild's behavior typically to allow shortcutting processes
// in cases which are considered to be safe most of the time.
quirks = [
  // Many processes (such as gcc) query the time with clock_gettime() and with similar calls but
  // don't use it in the output (unless the __TIME__ or __DATE__ preprocessor macros are used).
  // This quirk ignores all time queries for all processes.
  "ignore-time-queries",
  // When processes open a directory with opendir() or with a similar call the contents are hashed and
  // the processes are shorcut if the directory contents match the contents stored in the cache entry.
  // /tmp or TMPDIR OTOH is used by many processes outside of the intercepted builds, thus the
  // contents will most likely be different with each run making any process opening the temporary
  // directory not shortcutable almost every time they run.
  // This quirk ignores /tmp's directory listing for shortcutting purposes.
  // (Files used in /tmp are still tracked.)
  "ignore-tmp-listing",
  // lto-wrapper starts make internally which is not shortcutable in general.
  // This quirk allows shortcutting make and touch when it is run by lto-wrapper.
  // Since the internal make is started in /tmp the ignore-tmp-listing quirk needs to
  // be enabled as well to shortcut lto-wrapper.
  "lto-wrapper",
  // dot (via libfontconfig) and other commands call (f)stafs() which don't impact the output.
  // Ignore those calls to allow shortcutting such processes.
  "ignore-statfs",
  // Guess if a command parameter is a file and include the hash of the file in the process fingerprint.
  // This typically speeds up shortcutting, but may prevent shortcutting when the files passed to a command
  // as parameters already exist and their content would not be read by the command.
  "guess-file-params"
];

// The cache can contain multiple candidate entres for shortcutting a command.
// Run the intercepted command after failing to shortcut it using a preset number of candidates.
shortcut_tries = 20;

// Maximum size of the files stored in the cache, in GB.
// This is not a hard limit. When the cache size at the end of a build exceeds this limit
// garbage collection is started to remove the unusable cache entries first, then the last
// recently used ones until the cache size is decreased to at least 20% under the limit.
max_cache_size = 5.0

// Maximum size of one cache entry in MB.
// This includes the size of all outputs to be replayed when using the cache entry for shortcutting
// and the entry's size.
max_entry_size = 250.0