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 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 30 By default the timestamp is the current time and in the case of 31 ``kheaders`` the various files' modification times. This must 32 be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable. 33 If you are building from a git commit, you could use its commit date. 34 35 The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, 36 and enables warnings if they are used. If you incorporate external 37 code that does use these, you must override the timestamp they 38 correspond to by setting the `SOURCE_DATE_EPOCH`_ environment 39 variable. 40 41 User, host 42 ---------- 43 44 The 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 47 building from a git commit, you could use its committer address. 48 49 Absolute filenames 50 ------------------ 51 52 When the kernel is built out-of-tree, debug information may include 53 absolute filenames for the source files. This must be overridden by 54 including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. 55 56 Depending on the compiler used, the ``__FILE__`` macro may also expand 57 to an absolute filename in an out-of-tree build. Kbuild automatically 58 uses the ``-fmacro-prefix-map`` option to prevent this, if it is 59 supported. 60 61 The Reproducible Builds web site has more information about these 62 `prefix-map options`_. 63 64 Generated files in source packages 65 ---------------------------------- 66 67 The build processes for some programs under the ``tools/`` 68 subdirectory do not completely support out-of-tree builds. This may 69 cause a later source package build using e.g. ``make rpm-pkg`` to 70 include generated files. You should ensure the source tree is 71 pristine by running ``make mrproper`` or ``git clean -d -f -x`` before 72 building a source package. 73 74 Module signing 75 -------------- 76 77 If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to 78 generate a different temporary key for each build, resulting in the 79 modules being unreproducible. However, including a signing key with 80 your source would presumably defeat the purpose of signing modules. 81 82 One approach to this is to divide up the build process so that the 83 unreproducible parts can be treated as sources: 84 85 1. Generate a persistent signing key. Add the certificate for the key 86 to the kernel source. 87 88 2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the 89 signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an 90 empty string, and disable ``CONFIG_MODULE_SIG_ALL``. 91 Build the kernel and modules. 92 93 3. Create detached signatures for the modules, and publish them as 94 sources. 95 96 4. Perform a second build that attaches the module signatures. It 97 can either rebuild the modules or use the output of step 2. 98 99 Structure randomisation 100 ----------------------- 101 102 If you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate 103 the random seed in ``scripts/basic/randstruct.seed`` so the same 104 value is used by each build. See ``scripts/gen-randstruct-seed.sh`` 105 for details. 106 107 Debug info conflicts 108 -------------------- 109 110 This is not a problem of unreproducibility, but of generated files 111 being *too* reproducible. 112 113 Once you set all the necessary variables for a reproducible build, a 114 vDSO's debug information may be identical even for different kernel 115 versions. This can result in file conflicts between debug information 116 packages for the different kernel versions. 117 118 To avoid this, you can make the vDSO different for different 119 kernel versions by including an arbitrary string of "salt" in it. 120 This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. 121 122 Git 123 --- 124 125 Uncommitted changes or different commit ids in git can also lead 126 to different compilation results. For example, after executing 127 ``git reset HEAD^``, even if the code is the same, the 128 ``include/config/kernel.release`` generated during compilation 129 will be different, which will eventually lead to binary differences. 130 See ``scripts/setlocalversion`` for details. 131 132 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp 133 .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host 134 .. _KCFLAGS: kbuild.html#kcflags 135 .. _prefix-map options: https://reproducible-builds.org/docs/build-path/ 136 .. _Reproducible Builds project: https://reproducible-builds.org/ 137 .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.