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 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
26By default the timestamp is the current time.  This must be overridden
27using the `KBUILD_BUILD_TIMESTAMP`_ variable.  If you are building
28from a git commit, you could use its commit date.
29
30The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
31and enables warnings if they are used.  If you incorporate external
32code that does use these, you must override the timestamp they
33correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
34variable.
35
36User, host
37----------
38
39The 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
42building from a git commit, you could use its committer address.
43
44Absolute filenames
45------------------
46
47When the kernel is built out-of-tree, debug information may include
48absolute filenames for the source files.  This must be overridden by
49including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
50
51Depending on the compiler used, the ``__FILE__`` macro may also expand
52to an absolute filename in an out-of-tree build.  Kbuild automatically
53uses the ``-fmacro-prefix-map`` option to prevent this, if it is
54supported.
55
56The Reproducible Builds web site has more information about these
57`prefix-map options`_.
58
59Generated files in source packages
60----------------------------------
61
62The build processes for some programs under the ``tools/``
63subdirectory do not completely support out-of-tree builds.  This may
64cause a later source package build using e.g. ``make rpm-pkg`` to
65include generated files.  You should ensure the source tree is
66pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
67building a source package.
68
69Module signing
70--------------
71
72If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
73generate a different temporary key for each build, resulting in the
74modules being unreproducible.  However, including a signing key with
75your source would presumably defeat the purpose of signing modules.
76
77One approach to this is to divide up the build process so that the
78unreproducible parts can be treated as sources:
79
801. Generate a persistent signing key.  Add the certificate for the key
81   to the kernel source.
82
832. 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
883. Create detached signatures for the modules, and publish them as
89   sources.
90
914. Perform a second build that attaches the module signatures.  It
92   can either rebuild the modules or use the output of step 2.
93
94Structure randomisation
95-----------------------
96
97If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
98pre-generate the random seed in
99``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
100is used in rebuilds.
101
102Debug info conflicts
103--------------------
104
105This is not a problem of unreproducibility, but of generated files
106being *too* reproducible.
107
108Once you set all the necessary variables for a reproducible build, a
109vDSO's debug information may be identical even for different kernel
110versions.  This can result in file conflicts between debug information
111packages for the different kernel versions.
112
113To avoid this, you can make the vDSO different for different
114kernel versions by including an arbitrary string of "salt" in it.
115This 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/
123