Documentation/kbuild/reproducible-builds.rst

Source file repositories/reference/linux-study-clean/Documentation/kbuild/reproducible-builds.rst

File Facts

System
Linux kernel
Corpus path
Documentation/kbuild/reproducible-builds.rst
Extension
.rst
Size
5610 bytes
Lines
144
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

===================
Reproducible builds
===================

It is generally desirable that building the same source code with
the same set of tools is reproducible, i.e. the output is always
exactly the same.  This makes it possible to verify that the build
infrastructure for a binary distribution or embedded system has not
been subverted.  This can also make it easier to verify that a source
or tool change does not make any difference to the resulting binaries.

The `Reproducible Builds project`_ has more information about this
general topic.  This document covers the various reasons why building
the kernel may be unreproducible, and how to avoid them.

Timestamps
----------

The kernel embeds timestamps in three places:

* The version string exposed by ``uname()`` and included in
  ``/proc/version``

* File timestamps in the embedded initramfs

* If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel
  headers embedded in the kernel or respective module,
  exposed via ``/sys/kernel/kheaders.tar.xz``

By default the timestamp is the current time and in the case of
``kheaders`` the various files' modification times. This must
be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable.
If you are building from a git commit, you could use its commit date.

The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
and enables warnings if they are used.  If you incorporate external
code that does use these, you must override the timestamp they
correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
variable.

User, host
----------

The kernel embeds the building user and host names in
``/proc/version``.  These must be overridden using the
`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables.  If you are
building from a git commit, you could use its committer address.

Absolute filenames
------------------

When the kernel is built out-of-tree, debug information may include
absolute filenames for the source files and build directory.  These must
be overridden by including a ``-fdebug-prefix-map`` option for each in
the `KCFLAGS`_ and `KAFLAGS`_ variables to cover both ``.c`` and ``.S``
files.

Depending on the compiler used, the ``__FILE__`` macro may also expand
to an absolute filename in an out-of-tree build.  Kbuild automatically
uses the ``-fmacro-prefix-map`` option to prevent this, if it is
supported.

The Reproducible Builds web site has more information about these
`prefix-map options`_.

Some CONFIG options such as `CONFIG_DEBUG_EFI` embed absolute paths in
object files. Such options should be disabled.

Generated files in source packages
----------------------------------

Annotation

Implementation Notes