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
64Generated files in source packages
65----------------------------------
66
67The build processes for some programs under the ``tools/``
68subdirectory do not completely support out-of-tree builds.  This may
69cause a later source package build using e.g. ``make rpm-pkg`` to
70include generated files.  You should ensure the source tree is
71pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
72building a source package.
73
74Module signing
75--------------
76
77If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
78generate a different temporary key for each build, resulting in the
79modules being unreproducible.  However, including a signing key with
80your source would presumably defeat the purpose of signing modules.
81
82One approach to this is to divide up the build process so that the
83unreproducible parts can be treated as sources:
84
851. Generate a persistent signing key.  Add the certificate for the key
86   to the kernel source.
87
882. 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
933. Create detached signatures for the modules, and publish them as
94   sources.
95
964. Perform a second build that attaches the module signatures.  It
97   can either rebuild the modules or use the output of step 2.
98
99Structure randomisation
100-----------------------
101
102If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
103pre-generate the random seed in
104``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
105is used in rebuilds.
106
107Debug info conflicts
108--------------------
109
110This is not a problem of unreproducibility, but of generated files
111being *too* reproducible.
112
113Once you set all the necessary variables for a reproducible build, a
114vDSO's debug information may be identical even for different kernel
115versions.  This can result in file conflicts between debug information
116packages for the different kernel versions.
117
118To avoid this, you can make the vDSO different for different
119kernel versions by including an arbitrary string of "salt" in it.
120This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
121
122.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
123.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
124.. _KCFLAGS: kbuild.html#kcflags
125.. _prefix-map options: https://reproducible-builds.org/docs/build-path/
126.. _Reproducible Builds project: https://reproducible-builds.org/
127.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
128