build/docs/sccache-dist.rst

   1 .. _sccache_dist:
   2
   3 ==================================
   4 Distributed sccache (sccache-dist)
   5 ==================================
   6
   7 `sccache <https://github.com/mozilla/sccache>`_ is a ccache-like tool written in
   8 Rust by Mozilla.
   9
  10 The steps for setting up your machine as an sccache-dist server are detailed below.
  11
  12 In addition to improved security properties, distributed sccache offers
  13 distribution and caching of rust compilation, so it should be an improvement
  14 above and beyond what we see with icecc. Build servers run on Linux and
  15 distributing builds is currently supported from Linux, macOS, and Windows.
  16
  17
  18 Steps for distributing a build as an sccache-dist client
  19 ========================================================
  20
  21 Start by following the instructions at https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md#configure-a-client
  22 to configure your sccache distributed client.
  23 *NOTE* If you're distributing from Linux a toolchain will be packaged
  24 automatically and provided to the build server. If you're distributing from
  25 Windows or macOS, start by using the cross-toolchains provided by
  26 ``./mach bootstrap`` rather than attempting to use ``icecc-create-env``.
  27 sccache 0.2.12 or above is recommended, and the auth section of your config
  28 must read::
  29
  30     [dist.auth]
  31     type = "mozilla"
  32
  33 * If you're compiling from a macOS client, there are a handful of additional
  34   considerations outlined here:
  35   https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md#considerations-when-distributing-from-macos.
  36
  37   Run ``./mach bootstrap`` to download prebuilt toolchains to
  38   ``~/.mozbuild/clang-dist-toolchain.tar.xz`` and
  39   ``~/.mozbuild/rustc-dist-toolchain.tar.xz``. This is an example of the paths
  40   that should be added to your client config to specify toolchains to build on
  41   macOS, located at ``~/Library/Application Support/Mozilla.sccache/config``::
  42
  43     [[dist.toolchains]]
  44     type = "path_override"
  45     compiler_executable = "/path/to/home/.rustup/toolchains/stable-x86_64-apple-darwin/bin/rustc"
  46     archive = "/path/to/home/.mozbuild/rustc-dist-toolchain.tar.xz"
  47     archive_compiler_executable = "/builds/worker/toolchains/rustc/bin/rustc"
  48
  49     [[dist.toolchains]]
  50     type = "path_override"
  51     compiler_executable = "/path/to/home/.mozbuild/clang/bin/clang"
  52     archive = "/path/to/home/.mozbuild/clang-dist-toolchain.tar.xz"
  53     archive_compiler_executable = "/builds/worker/toolchains/clang/bin/clang"
  54
  55     [[dist.toolchains]]
  56     type = "path_override"
  57     compiler_executable = "/path/to/home/.mozbuild/clang/bin/clang++"
  58     archive = "/path/to/home/.mozbuild/clang-dist-toolchain.tar.xz"
  59     archive_compiler_executable = "/builds/worker/toolchains/clang/bin/clang"
  60
  61   Note that the version of ``rustc`` found in ``rustc-dist-toolchain.tar.xz``
  62   must match the version of ``rustc`` used locally. The distributed archive
  63   will contain the version of ``rustc`` used by automation builds, which may
  64   lag behind stable for a few days after Rust releases, which is specified by
  65   the task definition in
  66   `this file <https://hg.mozilla.org/mozilla-central/file/tip/taskcluster/ci/toolchain/dist-toolchains.yml>`_.
  67   For instance, to specify 1.37.0 rather than the current stable, run
  68   ``rustup toolchain add 1.37.0`` and point to
  69   ``/path/to/home/.rustup/toolchains/1.37.0-x86_64-apple-darwin/bin/rustc`` in your
  70   client config.
  71
  72   The build system currently requires an explicit target to be passed with
  73   ``HOST_CFLAGS`` and ``HOST_CXXFLAGS`` e.g.::
  74
  75     export HOST_CFLAGS="--target=x86_64-apple-darwin16.0.0"
  76     export HOST_CXXFLAGS="--target=x86_64-apple-darwin16.0.0"
  77
  78 * Compiling from a Windows client is supported but hasn't seen as much testing
  79   as other platforms. The following example mozconfig can be used as a guide::
  80
  81     ac_add_options CCACHE="C:/Users/<USER>/.mozbuild/sccache/sccache.exe"
  82
  83     export CC="C:/Users/<USER>/.mozbuild/clang/bin/clang-cl.exe --driver-mode=cl"
  84     export CXX="C:/Users/<USER>/.mozbuild/clang/bin/clang-cl.exe --driver-mode=cl"
  85     export HOST_CC="C:/Users/<USER>/.mozbuild/clang/bin/clang-cl.exe --driver-mode=cl"
  86     export HOST_CXX="C:/Users/<USER>/.mozbuild/clang/bin/clang-cl.exe --driver-mode=cl"
  87
  88   The client config should be located at
  89   ``~/AppData/Roaming/Mozilla/sccache/config/config``, and as on macOS custom
  90   toolchains should be obtained with ``./mach bootstrap`` and specified in the
  91   client config, for example::
  92
  93     [[dist.toolchains]]
  94     type = "path_override"
  95     compiler_executable = "C:/Users/<USER>/.mozbuild/clang/bin/clang-cl.exe"
  96     archive = "C:/Users/<USER>/.mozbuild/clang-dist-toolchain.tar.xz"
  97     archive_compiler_executable = "/builds/worker/toolchains/clang/bin/clang"
  98
  99     [[dist.toolchains]]
 100     type = "path_override"
 101     compiler_executable = "C:/Users/<USER>/.rustup/toolchains/stable-x86_64-pc-windows-msvc/bin/rustc.exe"
 102     archive = "C:/Users/<USER>/.mozbuild/rustc-dist-toolchain.tar.xz"
 103     archive_compiler_executable = "/builds/worker/toolchains/rustc/bin/rustc"
 104
 105 * Add the following to your mozconfig::
 106
 107     ac_add_options CCACHE=/path/to/home/.mozbuild/sccache/sccache
 108
 109   If you're compiling from a macOS client, you might need some additional configuration::
 110
 111     # Set the target flag to Darwin
 112     export CFLAGS="--target=x86_64-apple-darwin16.0.0"
 113     export CXXFLAGS="--target=x86_64-apple-darwin16.0.0"
 114     export HOST_CFLAGS="--target=x86_64-apple-darwin16.0.0"
 115     export HOST_CXXFLAGS="--target=x86_64-apple-darwin16.0.0"
 116
 117     # Specify the macOS SDK to use
 118     ac_add_options --with-macos-sdk=/path/to/MacOSX-SDKs/MacOSX13.3.sdk
 119
 120   You can get the right macOS SDK by downloading an old version of XCode from
 121   `developer.apple.com <https://developer.apple.com>`_ and unpacking the SDK
 122   from it.
 123
 124 * When attempting to get your client running, the output of ``sccache -s`` should
 125   be consulted to confirm compilations are being distributed. To receive helpful
 126   logging from the local daemon in case they aren't, run
 127   ``SCCACHE_NO_DAEMON=1 SCCACHE_START_SERVER=1 SCCACHE_LOG=sccache=trace path/to/sccache``
 128   in a terminal window separate from your build prior to building. *NOTE* use
 129   ``RUST_LOG`` instead of ``SCCACHE_LOG`` if your build of ``sccache`` does not
 130   include `pull request 822
 131   <https://github.com/mozilla/sccache/pull/822>`_. (``sccache`` binaries from
 132   ``mach bootstrap`` do include this PR.)
 133
 134 * Run ``./mach build -j<value>`` with an appropriately large ``<value>``.
 135   ``sccache --dist-status`` should provide the number of cores available to you
 136   (or a message if you're not connected). In the future this will be integrated
 137   with the build system to automatically select an appropriate value.
 138
 139 This should be enough to distribute your build and replace your use of icecc.
 140 Bear in mind there may be a few speedbumps, and please ensure your version of
 141 sccache is current before investigating further. Please see the common questions
 142 section below and ask for help if anything is preventing you from using it over
 143 email (dev-builds), on slack in #sccache, or in #build on irc.
 144
 145 Steps for setting up a server
 146 =============================
 147
 148 Build servers must run linux and use bubblewrap 0.3.0+ for sandboxing of compile
 149 processes. This requires a kernel 4.6 or greater, so Ubuntu 18+, RHEL 8, or
 150 similar.
 151
 152 * Run ``./mach bootstrap`` or
 153   ``./mach artifact toolchain --from-build linux64-sccache`` to acquire a recent
 154   version of ``sccache-dist``. Please use a ``sccache-dist`` binary acquired in
 155   this fashion to ensure compatibility with statically linked dependencies.
 156
 157 * The instructions at https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md#configure-a-build-server
 158   should contain everything else required to configure and run the server.
 159
 160   *NOTE* Port 10500 will be used by convention for builders.
 161   Please use port 10500 in the ``public_addr`` section of your builder config.
 162
 163   Extra logging may be helpful when setting up a server. To enable logging,
 164   run your server with
 165   ``sudo env SCCACHE_LOG=sccache=trace ~/.mozbuild/sccache/sccache-dist server --config ~/.config/sccache/server.conf``
 166   (or similar). *NOTE* ``sudo`` *must* come before setting environment variables
 167   for this to work. *NOTE* use ``RUST_LOG`` instead of ``SCCACHE_LOG`` if your
 168   build of ``sccache`` does not include `pull request 822
 169   <https://github.com/mozilla/sccache/pull/822>`_. (``sccache`` binaries from
 170   ``mach bootstrap`` do include this PR.)
 171
 172
 173 Common questions/considerations
 174 ===============================
 175
 176 * My build is still slow: scache-dist can only do so much with parts of the
 177   build that aren't able to be parallelized. To start debugging a slow build,
 178   ensure the "Successful distributed compilations" line in the output of
 179   ``sccache -s`` dominates other counts. For a full build, at least a 2-3x
 180   improvement should be observed.
 181
 182 * My build output is incomprehensible due to a flood of warnings: clang will
 183   treat some warnings differently when it's fed preprocessed code in a separate
 184   invocation (preprocessing occurs locally with sccache-dist). Adding
 185   ``rewrite_includes_only = true`` to the ``dist`` section of your client config
 186   will improve this; however, setting this will cause build failures with a
 187   commonly deployed version of ``glibc``. This option will default to ``true``
 188   once the fix is more widely available. Details of this fix can be found in
 189   `this patch <https://sourceware.org/ml/libc-alpha/2019-11/msg00431.html>`_.
 190
 191 * My build fails with a message about incompatible versions of rustc between
 192   dependent crates: if you're using a custom toolchain check that the version
 193   of rustc in your ``rustc-dist-toolchain.tar.xz`` is the same as the version
 194   you're running locally.