DOCSEARCHbyAlgolia
Submit Docs

sccache Documentation

repository·main·Indexed 27 days ago

https://github.com/mozilla/sccache

sccache is a shared compilation cache tool and compiler wrapper designed to speed up build processes by avoiding redundant compilations. It supports multiple languages, including C/C++, Rust, CUDA, and AMD ROCm HIP. The tool offers flexible storage backends ranging from local disks to cloud providers such as S3, Azure, Google Cloud Storage, and Redis, and provides distributed compilation capabilities with enhanced security features.

Tokens
23.6K
Snippets
56
Records
161
Agent score
92%

What's inside sccache

  1. Overview of Distributed sccache architecture

    main

    Distributed sccache consists of three components:

    1. Client: An sccache binary that performs compilations on remote machines.
    2. Scheduler (sccache-dist binary): Decides where compilation jobs should run.
    3. Server (sccache-dist binary): Executes the actual builds.

    Platform Support:

    • Servers: Must be 64-bit Linux or FreeBSD.
    • Clients: Can request compilation from Linux, Windows, or macOS.
      • Linux: Attempts to automatically package the compiler.
      • Windows/macOS: Users must specify a toolchain for cross-compilation in advance.

  2. Overview of sccache

    main

    sccache is a compiler caching tool similar to ccache. It acts as a compiler wrapper to avoid redundant compilation by storing results on local disk or various cloud storage backends.

    Key features include:

    • Supported Languages: Assembler, C/C++, Rust, NVIDIA CUDA (via nvcc or clang), and AMD ROCm HIP.
    • Storage Backends: Supports local disk, S3, R2, Redis, Memcached, Google Cloud Storage, Azure, GitHub Actions, WebDAV, Alibaba OSS, and Tencent Cloud Object Storage.
    • Distributed Compilation: Provides icecream-style distributed compilation with enhanced security features like authentication, transport layer encryption, and sandboxed execution.
    • Hierarchical Caching: Supports multi-level caching with automatic backfill.

  3. Use sccache for Rust builds

    main

    To cache Rust compilations, you can either configure Cargo globally or use an environment variable. Requires Cargo 1.40 or newer.

    Option 1: Cargo Configuration

    Add the following to your $HOME/.cargo/config.toml:

    [build]
rustc-wrapper = "/path/to/sccache"

    Option 2: Environment Variable

    Set RUSTC_WRAPPER before running cargo:

    export RUSTC_WRAPPER=/path/to/sccache
cargo build
    export RUSTC_WRAPPER=/path/to/sccache
cargo build

  4. Install sccache

    main

    You can install sccache via package managers, cargo, or by downloading prebuilt binaries from the GitHub releases page.

    macOS

    Use Homebrew or MacPorts:

    brew install sccache
# or
sudo port install sccache

    Windows

    Use Scoop or Winget:

    scoop install sccache
# or
winget install Mozilla.sccache

    Via cargo

    To install from source (resource-intensive):

    cargo install sccache --locked

    To install a prebuilt binary using cargo-binstall:

    cargo binstall sccache

    With Nix

    Add to buildInputs in nixpkgs:

    buildInputs = [ pkgs.sccache ];

    Or use the provided flake overlay for the latest version, or run directly:

    nix run github:mozilla/sccache -- --help
nix shell github:mozilla/sccache

  5. Use custom toolchains for distributed compilation

    main

    To support cross-compilation (especially from Windows/macOS), you can manually specify toolchain archives in the client configuration using the [[dist.toolchains]] section with type = "path_override".

    Required Fields:

    • compiler_executable: The path on the local machine that sccache matches against to trigger this config.
    • archive: A Gzip-compressed TAR archive containing the toolchain.
    • archive_compiler_executable: The path inside the archive where the compiler resides.
    # Example for Linux/macOS
[[dist.toolchains]]
type = "path_override"
compiler_executable = "/home/me/.mozbuild/clang/bin/clang"
archive = "/home/me/.mozbuild/toolchains/33d92fcd79ffef6e-clang-dist-toolchain.tar.gz"
archive_compiler_executable = "/builds/worker/toolchains/clang/bin/clang"

  6. Enable sccache for Rust compilation via RUSTC_WRAPPER

    main
    To use sccache to cache Rust compilation (specifically rustc invocations produced by cargo), set the RUSTC_WRAPPER environment variable to sccache in your build environment. This instructs cargo to wrap all compilation calls with the sccache binary.

  7. Build distributed server binaries using Docker

    main

    To build a release binary for the distributed server (sccache-dist) with musl support, use the following Docker command. This builds the binary, strips it, and packages it into a tarball.

    docker run -ti --rm -v $PWD:/sccache luser/sccache-musl-build:0.1 /bin/bash -c "cd /sccache; cargo build --release --target x86_64-unknown-linux-musl --features=dist-server && strip target/x86_64-unknown-linux-musl/release/sccache-dist && cd target/x86_64-unknown-linux-musl/release/ && tar czf sccache-dist.tar.gz sccache-dist"

  8. Run a persistent sccache server on Jenkins

    main

    To prevent Jenkins from killing the sccache server process when a job finishes (which can break parallel builds), you can run sccache as a persistent system service outside of Jenkins.

    To ensure the server does not shut down due to inactivity, set the SCCACHE_IDLE_TIMEOUT environment variable to 0. Note that in this configuration, all Jenkins jobs will share the same sccache configuration and statistics.

  9. Produce an sccache release using cargo-release

    main

    Releases for sccache are produced using cargo-release. This tool automates bumping the version number, creating and pushing a new tag, and publishing to crates.io.

    To preview the actions that will be taken without actually performing them, use the --dry-run flag.

  10. Configure Preprocessor cache mode

    main

    Preprocessor cache mode allows sccache to skip preprocessing for C/C++ files, which can significantly speed up compilation. It is enabled by default.

    Enabling/Disabling

    • Configuration option: use_preprocessor_cache_mode (defaults to true).
    • Environment variable: Set SCCACHE_DIRECT to true/on/1 to enable, or false/off/0 to disable.

    Preprocessor Cache Configuration Options

    OptionDefaultDescription
    use_preprocessor_cache_modetrueEnables/disables the mode.
    file_stat_matchesfalseIf true, uses size + ctime + mtime to check for file changes. If false, only hashes contents.
    use_ctime_for_stattrueUses ctime (status change on UNIX, creation time on Windows) to check for changes.
    ignore_time_macrosfalseIf true, ignores __DATE__, __TIME__, and __TIMESTAMP__. Warning: This can produce stale results.
    skip_system_headersfalseIf true, only adds system header paths to the cache key, ignoring their contents.
    hash_working_directorytrueAdds the current working directory to the cache key.

    Limitations and Disabling Conditions

    Preprocessor cache mode is automatically disabled if:

    • You are not compiling C or C++.
    • You are not using GCC or Clang.
    • You are not using local storage.
    • Compiler options -MP, -Xpreprocessor, or -Wp, are present.
    • A header file's modification time is too new (to avoid races).
    • __DATE__, __TIME__, or __TIMESTAMP__ are present in the source (unless ignore_time_macros is true).

  11. Enable GitHub Actions cache for sccache

    main

    To use the GitHub Actions cache backend, set the SCCACHE_GHA_ENABLED environment variable to on.

    To force a purge of all existing caches, change the value of the SCCACHE_GHA_VERSION environment variable.

  12. Use MSVC response files with sccache

    main

    sccache supports MSVC-style response files. When using MSVC, the following rules apply:

    • Contents are inserted in-place in the original command.
    • Options can span multiple lines, but each individual option must begin and end on the same line.
    • Backslashes (\) cannot be used to combine options across multiple lines.
    • Options can be wrapped in double-quotes (") to preserve whitespace.
    • Encoding: sccache supports any text file encoding under the WHATWG encoding standard (including utf-8 and utf-16), which is useful for msbuild generated files.

    Limitations:

    • No Recursion: MSVC response files cannot contain additional @file options.
    • No /link support: sccache does not accept the /link directive, so the special treatment of /link regarding @file boundaries described in MSVC documentation is not implemented.