Documentation/kbuild/reproducible-builds.rst

   1 ===================
   2 Reproducible builds
   3 ===================
   4
   5 It is generally desirable that building the same source code with
   6 the same set of tools is reproducible, i.e. the output is always
   7 exactly the same.  This makes it possible to verify that the build
   8 infrastructure for a binary distribution or embedded system has not
   9 been subverted.  This can also make it easier to verify that a source
  10 or tool change does not make any difference to the resulting binaries.
  11
  12 The `Reproducible Builds project`_ has more information about this
  13 general topic.  This document covers the various reasons why building
  14 the kernel may be unreproducible, and how to avoid them.
  15
  16 Timestamps
  17 ----------
  18
  19 The kernel embeds a timestamp in two 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 By default the timestamp is the current time.  This must be overridden
  27 using the `KBUILD_BUILD_TIMESTAMP`_ variable.  If you are building
  28 from a git commit, you could use its commit date.
  29
  30 The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
  31 and enables warnings if they are used.  If you incorporate external
  32 code that does use these, you must override the timestamp they
  33 correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
  34 variable.
  35
  36 User, host
  37 ----------
  38
  39 The kernel embeds the building user and host names in
  40 ``/proc/version``.  These must be overridden using the
  41 `KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables.  If you are
  42 building from a git commit, you could use its committer address.
  43
  44 Absolute filenames
  45 ------------------
  46
  47 When the kernel is built out-of-tree, debug information may include
  48 absolute filenames for the source files.  This must be overridden by
  49 including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
  50
  51 Depending on the compiler used, the ``__FILE__`` macro may also expand
  52 to an absolute filename in an out-of-tree build.  Kbuild automatically
  53 uses the ``-fmacro-prefix-map`` option to prevent this, if it is
  54 supported.
  55
  56 The Reproducible Builds web site has more information about these
  57 `prefix-map options`_.
  58
  59 Generated files in source packages
  60 ----------------------------------
  61
  62 The build processes for some programs under the ``tools/``
  63 subdirectory do not completely support out-of-tree builds.  This may
  64 cause a later source package build using e.g. ``make rpm-pkg`` to
  65 include generated files.  You should ensure the source tree is
  66 pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
  67 building a source package.
  68
  69 Module signing
  70 --------------
  71
  72 If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
  73 generate a different temporary key for each build, resulting in the
  74 modules being unreproducible.  However, including a signing key with
  75 your source would presumably defeat the purpose of signing modules.
  76
  77 One approach to this is to divide up the build process so that the
  78 unreproducible parts can be treated as sources:
  79
  80 1. Generate a persistent signing key.  Add the certificate for the key
  81    to the kernel source.
  82
  83 2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
  84    signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
  85    empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
  86    Build the kernel and modules.
  87
  88 3. Create detached signatures for the modules, and publish them as
  89    sources.
  90
  91 4. Perform a second build that attaches the module signatures.  It
  92    can either rebuild the modules or use the output of step 2.
  93
  94 Structure randomisation
  95 -----------------------
  96
  97 If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
  98 pre-generate the random seed in
  99 ``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
 100 is used in rebuilds.
 101
 102 Debug info conflicts
 103 --------------------
 104
 105 This is not a problem of unreproducibility, but of generated files
 106 being *too* reproducible.
 107
 108 Once you set all the necessary variables for a reproducible build, a
 109 vDSO's debug information may be identical even for different kernel
 110 versions.  This can result in file conflicts between debug information
 111 packages for the different kernel versions.
 112
 113 To avoid this, you can make the vDSO different for different
 114 kernel versions by including an arbitrary string of "salt" in it.
 115 This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
 116
 117 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
 118 .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
 119 .. _KCFLAGS: kbuild.html#kcflags
 120 .. _prefix-map options: https://reproducible-builds.org/docs/build-path/
 121 .. _Reproducible Builds project: https://reproducible-builds.org/
 122 .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/