blob: 91f94a5c74e8e0387f1857cbbdf38e7170bb5248 [file] [log] [blame]
Andrew Geissler09036742021-06-25 14:25:14 -05001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3*******************
4Reproducible Builds
5*******************
6
7================
8How we define it
9================
10
11The Yocto Project defines reproducibility as where a given input build
12configuration will give the same binary output regardless of when it is built
13(now or in 5 years time), regardless of the path on the filesystem the build is
14run in, and regardless of the distro and tools on the underlying host system the
15build is running on.
16
17==============
18Why it matters
19==============
20
21The project aligns with the `Reproducible Builds project
Patrick Williams2390b1b2022-11-03 13:47:49 -050022<https://reproducible-builds.org/>`__, which shares information about why
Andrew Geissler09036742021-06-25 14:25:14 -050023reproducibility matters. The primary focus of the project is the ability to
24detect security issues being introduced. However, from a Yocto Project
25perspective, it is also hugely important that our builds are deterministic. When
26you build a given input set of metadata, we expect you to get consistent output.
Andrew Geissler6aa7eec2023-03-03 12:41:14 -060027This has always been a key focus but, :ref:`since release 3.1 ("dunfell")
28<migration-guides/migration-3.1:reproducible builds now enabled by default>`,
Andrew Geissler09036742021-06-25 14:25:14 -050029it is now true down to the binary level including timestamps.
30
31For example, at some point in the future life of a product, you find that you
32need to rebuild to add a security fix. If this happens, only the components that
33have been modified should change at the binary level. This would lead to much
34easier and clearer bounds on where validation is needed.
35
Andrew Geissler595f6302022-01-24 19:11:47 +000036This also gives an additional benefit to the project builds themselves, our
37:ref:`overview-manual/concepts:Hash Equivalence` for
38:ref:`overview-manual/concepts:Shared State` object reuse works much more
39effectively when the binary output remains the same.
Andrew Geissler09036742021-06-25 14:25:14 -050040
41.. note::
42
43 We strongly advise you to make sure your project builds reproducibly
44 before finalizing your production images. It would be too late if you
45 only address this issue when the first updates are required.
46
47===================
48How we implement it
49===================
50
51There are many different aspects to build reproducibility, but some particular
52things we do within the build system to ensure reproducibility include:
53
54- Adding mappings to the compiler options to ensure debug filepaths are mapped
55 to consistent target compatible paths. This is done through the
Andrew Geisslereff27472021-10-29 15:35:00 -050056 :term:`DEBUG_PREFIX_MAP` variable which sets the ``-fmacro-prefix-map`` and
Andrew Geissler09036742021-06-25 14:25:14 -050057 ``-fdebug-prefix-map`` compiler options correctly to map to target paths.
58- Being explicit about recipe dependencies and their configuration (no floating
59 configure options or host dependencies creeping in). In particular this means
60 making sure :term:`PACKAGECONFIG` coverage covers configure options which may
61 otherwise try and auto-detect host dependencies.
62- Using recipe specific sysroots to isolate recipes so they only see their
63 dependencies. These are visible as ``recipe-sysroot`` and
64 ``recipe-sysroot-native`` directories within the :term:`WORKDIR` of a given
65 recipe and are populated only with the dependencies a recipe has.
66- Build images from a reduced package set: only packages from recipes the image
67 depends upon.
68- Filtering the tools available from the host's ``PATH`` to only a specific set
69 of tools, set using the :term:`HOSTTOOLS` variable.
70
Andrew Geissler09036742021-06-25 14:25:14 -050071=========================================
72Can we prove the project is reproducible?
73=========================================
74
75Yes, we can prove it and we regularly test this on the Autobuilder. At the
76time of writing (release 3.3, "hardknott"), :term:`OpenEmbedded-Core (OE-Core)`
77is 100% reproducible for all its recipes (i.e. world builds) apart from the Go
78language and Ruby documentation packages. Unfortunately, the current
79implementation of the Go language has fundamental reproducibility problems as
80it always depends upon the paths it is built in.
81
82.. note::
83
84 Only BitBake and :term:`OpenEmbedded-Core (OE-Core)`, which is the ``meta``
85 layer in Poky, guarantee complete reproducibility. The moment you add
86 another layer, this warranty is voided, because of additional configuration
87 files, ``bbappend`` files, overridden classes, etc.
88
89To run our automated selftest, as we use in our CI on the Autobuilder, you can
90run::
91
92 oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
93
94This defaults to including a ``world`` build so, if other layers are added, it would
Patrick Williams520786c2023-06-25 16:20:36 -050095also run the tests for recipes in the additional layers. Different build targets
96can be defined using the :term:`OEQA_REPRODUCIBLE_TEST_TARGET` variable in ``local.conf``.
97The first build will be run using :ref:`Shared State <overview-manual/concepts:Shared State>` if
Andrew Geissler09036742021-06-25 14:25:14 -050098available, the second build explicitly disables
Patrick Williams520786c2023-06-25 16:20:36 -050099:ref:`Shared State <overview-manual/concepts:Shared State>` except for recipes defined in
100the :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` variable, and builds on the
Andrew Geissler09036742021-06-25 14:25:14 -0500101specific host the build is running on. This means we can test reproducibility
102builds between different host distributions over time on the Autobuilder.
103
104If ``OEQA_DEBUGGING_SAVED_OUTPUT`` is set, any differing packages will be saved
105here. The test is also able to run the ``diffoscope`` command on the output to
106generate HTML files showing the differences between the packages, to aid
107debugging. On the Autobuilder, these appear under
108https://autobuilder.yocto.io/pub/repro-fail/ in the form ``oe-reproducible +
109<date> + <random ID>``, e.g. ``oe-reproducible-20200202-1lm8o1th``.
110
111The project's current reproducibility status can be seen at
112:yocto_home:`/reproducible-build-results/`
113
114You can also check the reproducibility status on supported host distributions:
115
116- CentOS: :yocto_ab:`/typhoon/#/builders/reproducible-centos`
117- Debian: :yocto_ab:`/typhoon/#/builders/reproducible-debian`
118- Fedora: :yocto_ab:`/typhoon/#/builders/reproducible-fedora`
119- Ubuntu: :yocto_ab:`/typhoon/#/builders/reproducible-ubuntu`
120
121===============================
122Can I test my layer or recipes?
123===============================
124
125Once again, you can run a ``world`` test using the
126:ref:`oe-selftest <ref-manual/release-process:Testing and Quality Assurance>`
127command provided above. This functionality is implemented
128in :oe_git:`meta/lib/oeqa/selftest/cases/reproducible.py
129</openembedded-core/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`.
130
131You could subclass the test and change ``targets`` to a different target.
132
133You may also change ``sstate_targets`` which would allow you to "pre-cache" some
134set of recipes before the test, meaning they are excluded from reproducibility
135testing. As a practical example, you could set ``sstate_targets`` to
136``core-image-sato``, then setting ``targets`` to ``core-image-sato-sdk`` would
137run reproducibility tests only on the targets belonging only to ``core-image-sato-sdk``.