reproducible-builds.rst

  1===================
  2Reproducible builds
  3===================
  4
  5It is generally desirable that building the same source code with
  6the same set of tools is reproducible, i.e. the output is always
  7exactly the same.  This makes it possible to verify that the build
  8infrastructure for a binary distribution or embedded system has not
  9been subverted.  This can also make it easier to verify that a source
 10or tool change does not make any difference to the resulting binaries.
 11
 12The `Reproducible Builds project`_ has more information about this
 13general topic.  This document covers the various reasons why building
 14the kernel may be unreproducible, and how to avoid them.
 15
 16Timestamps
 17----------
 18
 19The kernel embeds timestamps in three places:
 20
 21* The version string exposed by ``uname()`` and included in
 22  ``/proc/version``
 23
 24* File timestamps in the embedded initramfs
 25
 26* If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel
 27  headers embedded in the kernel or respective module,
 28  exposed via ``/sys/kernel/kheaders.tar.xz``
 29
 30By default the timestamp is the current time and in the case of
 31``kheaders`` the various files' modification times. This must
 32be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable.
 33If you are building from a git commit, you could use its commit date.
 34
 35The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
 36and enables warnings if they are used.  If you incorporate external
 37code that does use these, you must override the timestamp they
 38correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
 39variable.
 40
 41User, host
 42----------
 43
 44The kernel embeds the building user and host names in
 45``/proc/version``.  These must be overridden using the
 46`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables.  If you are
 47building from a git commit, you could use its committer address.
 48
 49Absolute filenames
 50------------------
 51
 52When the kernel is built out-of-tree, debug information may include
 53absolute filenames for the source files.  This must be overridden by
 54including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
 55
 56Depending on the compiler used, the ``__FILE__`` macro may also expand
 57to an absolute filename in an out-of-tree build.  Kbuild automatically
 58uses the ``-fmacro-prefix-map`` option to prevent this, if it is
 59supported.
 60
 61The Reproducible Builds web site has more information about these
 62`prefix-map options`_.
 63
 64Some CONFIG options such as `CONFIG_DEBUG_EFI` embed absolute paths in
 65object files. Such options should be disabled.
 66
 67Generated files in source packages
 68----------------------------------
 69
 70The build processes for some programs under the ``tools/``
 71subdirectory do not completely support out-of-tree builds.  This may
 72cause a later source package build using e.g. ``make rpm-pkg`` to
 73include generated files.  You should ensure the source tree is
 74pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
 75building a source package.
 76
 77Module signing
 78--------------
 79
 80If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
 81generate a different temporary key for each build, resulting in the
 82modules being unreproducible.  However, including a signing key with
 83your source would presumably defeat the purpose of signing modules.
 84
 85One approach to this is to divide up the build process so that the
 86unreproducible parts can be treated as sources:
 87
 881. Generate a persistent signing key.  Add the certificate for the key
 89   to the kernel source.
 90
 912. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
 92   signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
 93   empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
 94   Build the kernel and modules.
 95
 963. Create detached signatures for the modules, and publish them as
 97   sources.
 98
 994. Perform a second build that attaches the module signatures.  It
100   can either rebuild the modules or use the output of step 2.
101
102Structure randomisation
103-----------------------
104
105If you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate
106the random seed in ``scripts/basic/randstruct.seed`` so the same
107value is used by each build. See ``scripts/gen-randstruct-seed.sh``
108for details.
109
110Debug info conflicts
111--------------------
112
113This is not a problem of unreproducibility, but of generated files
114being *too* reproducible.
115
116Once you set all the necessary variables for a reproducible build, a
117vDSO's debug information may be identical even for different kernel
118versions.  This can result in file conflicts between debug information
119packages for the different kernel versions.
120
121To avoid this, you can make the vDSO different for different
122kernel versions by including an arbitrary string of "salt" in it.
123This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
124
125Git
126---
127
128Uncommitted changes or different commit ids in git can also lead
129to different compilation results. For example, after executing
130``git reset HEAD^``, even if the code is the same, the
131``include/config/kernel.release`` generated during compilation
132will be different, which will eventually lead to binary differences.
133See ``scripts/setlocalversion`` for details.
134
135.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
136.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
137.. _KCFLAGS: kbuild.html#kcflags
138.. _prefix-map options: https://reproducible-builds.org/docs/build-path/
139.. _Reproducible Builds project: https://reproducible-builds.org/
140.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/