diff options
Diffstat (limited to 'documentation/test-manual')
-rw-r--r-- | documentation/test-manual/history.rst | 16 | ||||
-rw-r--r-- | documentation/test-manual/index.rst | 3 | ||||
-rw-r--r-- | documentation/test-manual/intro.rst | 168 | ||||
-rw-r--r-- | documentation/test-manual/reproducible-builds.rst | 137 | ||||
-rw-r--r-- | documentation/test-manual/test-process.rst | 50 | ||||
-rw-r--r-- | documentation/test-manual/understand-autobuilder.rst | 80 | ||||
-rw-r--r-- | documentation/test-manual/yocto-project-compatible.rst | 129 |
7 files changed, 420 insertions, 163 deletions
diff --git a/documentation/test-manual/history.rst b/documentation/test-manual/history.rst deleted file mode 100644 index 89d4aad21c..0000000000 --- a/documentation/test-manual/history.rst +++ /dev/null | |||
@@ -1,16 +0,0 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | *********************** | ||
4 | Manual Revision History | ||
5 | *********************** | ||
6 | |||
7 | .. list-table:: | ||
8 | :widths: 10 15 40 | ||
9 | :header-rows: 1 | ||
10 | |||
11 | * - Revision | ||
12 | - Date | ||
13 | - Note | ||
14 | * - 3.2 | ||
15 | - October 2020 | ||
16 | - The initial document released with the Yocto Project 3.2 Release | ||
diff --git a/documentation/test-manual/index.rst b/documentation/test-manual/index.rst index e2198c4c39..86a2f436ea 100644 --- a/documentation/test-manual/index.rst +++ b/documentation/test-manual/index.rst | |||
@@ -13,6 +13,7 @@ Yocto Project Test Environment Manual | |||
13 | intro | 13 | intro |
14 | test-process | 14 | test-process |
15 | understand-autobuilder | 15 | understand-autobuilder |
16 | history | 16 | reproducible-builds |
17 | yocto-project-compatible | ||
17 | 18 | ||
18 | .. include:: /boilerplate.rst | 19 | .. include:: /boilerplate.rst |
diff --git a/documentation/test-manual/intro.rst b/documentation/test-manual/intro.rst index 81c24a8c3f..c31fd11c7a 100644 --- a/documentation/test-manual/intro.rst +++ b/documentation/test-manual/intro.rst | |||
@@ -14,19 +14,17 @@ release works as intended. All the project's testing infrastructure and | |||
14 | processes are publicly visible and available so that the community can | 14 | processes are publicly visible and available so that the community can |
15 | see what testing is being performed, how it's being done and the current | 15 | see what testing is being performed, how it's being done and the current |
16 | status of the tests and the project at any given time. It is intended | 16 | status of the tests and the project at any given time. It is intended |
17 | that Other organizations can leverage off the process and testing | 17 | that other organizations can leverage off the process and testing |
18 | environment used by the Yocto Project to create their own automated, | 18 | environment used by the Yocto Project to create their own automated, |
19 | production test environment, building upon the foundations from the | 19 | production test environment, building upon the foundations from the |
20 | project core. | 20 | project core. |
21 | 21 | ||
22 | Currently, the Yocto Project Test Environment Manual has no projected | 22 | This manual is a work-in-progress and is being initially loaded with |
23 | release date. This manual is a work-in-progress and is being initially | 23 | information from the README files and notes from key engineers: |
24 | loaded with information from the README files and notes from key | ||
25 | engineers: | ||
26 | 24 | ||
27 | - *yocto-autobuilder2:* This | 25 | - *yocto-autobuilder2:* This |
28 | :yocto_git:`README.md </yocto-autobuilder2/tree/README.md>` | 26 | :yocto_git:`README.md </yocto-autobuilder2/tree/README.md>` |
29 | is the main README which detials how to set up the Yocto Project | 27 | is the main README which details how to set up the Yocto Project |
30 | Autobuilder. The ``yocto-autobuilder2`` repository represents the | 28 | Autobuilder. The ``yocto-autobuilder2`` repository represents the |
31 | Yocto Project's console UI plugin to Buildbot and the configuration | 29 | Yocto Project's console UI plugin to Buildbot and the configuration |
32 | necessary to configure Buildbot to perform the testing the project | 30 | necessary to configure Buildbot to perform the testing the project |
@@ -39,7 +37,7 @@ engineers: | |||
39 | As a result, it can be used by any Continuous Improvement (CI) system | 37 | As a result, it can be used by any Continuous Improvement (CI) system |
40 | to run builds, support getting the correct code revisions, configure | 38 | to run builds, support getting the correct code revisions, configure |
41 | builds and layers, run builds, and collect results. The code is | 39 | builds and layers, run builds, and collect results. The code is |
42 | independent of any CI system, which means the code can work `Buildbot <https://docs.buildbot.net/0.9.15.post1/>`__, | 40 | independent of any CI system, which means the code can work `Buildbot <https://docs.buildbot.net/current/>`__, |
43 | Jenkins, or others. This repository has a branch per release of the | 41 | Jenkins, or others. This repository has a branch per release of the |
44 | project defining the tests to run on a per release basis. | 42 | project defining the tests to run on a per release basis. |
45 | 43 | ||
@@ -54,8 +52,8 @@ the Autobuilder tests if things work. The Autobuilder builds all test | |||
54 | targets and runs all the tests. | 52 | targets and runs all the tests. |
55 | 53 | ||
56 | The Yocto Project uses now uses standard upstream | 54 | The Yocto Project uses now uses standard upstream |
57 | `Buildbot <https://docs.buildbot.net/0.9.15.post1/>`__ (version 9) to | 55 | Buildbot (`version 3.8 <https://docs.buildbot.net/3.8.0/>`__) to |
58 | drive its integration and testing. Buildbot Nine has a plug-in interface | 56 | drive its integration and testing. Buildbot has a plug-in interface |
59 | that the Yocto Project customizes using code from the | 57 | that the Yocto Project customizes using code from the |
60 | ``yocto-autobuilder2`` repository, adding its own console UI plugin. The | 58 | ``yocto-autobuilder2`` repository, adding its own console UI plugin. The |
61 | resulting UI plug-in allows you to visualize builds in a way suited to | 59 | resulting UI plug-in allows you to visualize builds in a way suited to |
@@ -72,10 +70,9 @@ simple JSON files. | |||
72 | .. note:: | 70 | .. note:: |
73 | 71 | ||
74 | The project uses Buildbot for historical reasons but also because | 72 | The project uses Buildbot for historical reasons but also because |
75 | many of the project developers have knowledge of python. It is | 73 | many of the project developers have knowledge of Python. It is |
76 | possible to use the outer layers from another Continuous Integration | 74 | possible to use the outer layers from another Continuous Integration |
77 | (CI) system such as | 75 | (CI) system such as :wikipedia:`Jenkins <Jenkins_(software)>` |
78 | `Jenkins <https://en.wikipedia.org/wiki/Jenkins_(software)>`__ | ||
79 | instead of Buildbot. | 76 | instead of Buildbot. |
80 | 77 | ||
81 | The following figure shows the Yocto Project Autobuilder stack with a | 78 | The following figure shows the Yocto Project Autobuilder stack with a |
@@ -83,29 +80,29 @@ topology that includes a controller and a cluster of workers: | |||
83 | 80 | ||
84 | .. image:: figures/ab-test-cluster.png | 81 | .. image:: figures/ab-test-cluster.png |
85 | :align: center | 82 | :align: center |
83 | :width: 70% | ||
86 | 84 | ||
87 | Yocto Project Tests - Types of Testing Overview | 85 | Yocto Project Tests --- Types of Testing Overview |
88 | =============================================== | 86 | ================================================= |
89 | 87 | ||
90 | The Autobuilder tests different elements of the project by using | 88 | The Autobuilder tests different elements of the project by using |
91 | thefollowing types of tests: | 89 | the following types of tests: |
92 | 90 | ||
93 | - *Build Testing:* Tests whether specific configurations build by | 91 | - *Build Testing:* Tests whether specific configurations build by |
94 | varying :term:`MACHINE`, | 92 | varying :term:`MACHINE`, |
95 | :term:`DISTRO`, other configuration | 93 | :term:`DISTRO`, other configuration |
96 | options, and the specific target images being built (or world). Used | 94 | options, and the specific target images being built (or ``world``). This is |
97 | to trigger builds of all the different test configurations on the | 95 | used to trigger builds of all the different test configurations on the |
98 | Autobuilder. Builds usually cover many different targets for | 96 | Autobuilder. Builds usually cover many different targets for |
99 | different architectures, machines, and distributions, as well as | 97 | different architectures, machines, and distributions, as well as |
100 | different configurations, such as different init systems. The | 98 | different configurations, such as different init systems. The |
101 | Autobuilder tests literally hundreds of configurations and targets. | 99 | Autobuilder tests literally hundreds of configurations and targets. |
102 | 100 | ||
103 | - *Sanity Checks During the Build Process:* Tests initiated through | 101 | - *Sanity Checks During the Build Process:* Tests initiated through the |
104 | the :ref:`insane <ref-classes-insane>` | 102 | :ref:`ref-classes-insane` class. These checks ensure the output of the |
105 | class. These checks ensure the output of the builds are correct. | 103 | builds are correct. For example, does the ELF architecture in the |
106 | For example, does the ELF architecture in the generated binaries | 104 | generated binaries match the target system? ARM binaries would not work |
107 | match the target system? ARM binaries would not work in a MIPS | 105 | in a MIPS system! |
108 | system! | ||
109 | 106 | ||
110 | - *Build Performance Testing:* Tests whether or not commonly used steps | 107 | - *Build Performance Testing:* Tests whether or not commonly used steps |
111 | during builds work efficiently and avoid regressions. Tests to time | 108 | during builds work efficiently and avoid regressions. Tests to time |
@@ -121,18 +118,19 @@ thefollowing types of tests: | |||
121 | 118 | ||
122 | $ bitbake image -c testsdkext | 119 | $ bitbake image -c testsdkext |
123 | 120 | ||
124 | The tests utilize the ``testsdkext`` class and the ``do_testsdkext`` task. | 121 | The tests use the :ref:`ref-classes-testsdk` class and the |
122 | ``do_testsdkext`` task. | ||
125 | 123 | ||
126 | - *Feature Testing:* Various scenario-based tests are run through the | 124 | - *Feature Testing:* Various scenario-based tests are run through the |
127 | :ref:`OpenEmbedded Self test (oe-selftest) <ref-manual/release-process:Testing and Quality Assurance>`. We test oe-selftest on each of the main distrubutions | 125 | :ref:`OpenEmbedded Self test (oe-selftest) <ref-manual/release-process:Testing and Quality Assurance>`. We test oe-selftest on each of the main distributions |
128 | we support. | 126 | we support. |
129 | 127 | ||
130 | - *Image Testing:* Image tests initiated through the following command:: | 128 | - *Image Testing:* Image tests initiated through the following command:: |
131 | 129 | ||
132 | $ bitbake image -c testimage | 130 | $ bitbake image -c testimage |
133 | 131 | ||
134 | The tests utilize the :ref:`testimage* <ref-classes-testimage*>` | 132 | The tests use the :ref:`ref-classes-testimage` |
135 | classes and the :ref:`ref-tasks-testimage` task. | 133 | class and the :ref:`ref-tasks-testimage` task. |
136 | 134 | ||
137 | - *Layer Testing:* The Autobuilder has the possibility to test whether | 135 | - *Layer Testing:* The Autobuilder has the possibility to test whether |
138 | specific layers work with the test of the system. The layers tested | 136 | specific layers work with the test of the system. The layers tested |
@@ -142,7 +140,7 @@ thefollowing types of tests: | |||
142 | - *Package Testing:* A Package Test (ptest) runs tests against packages | 140 | - *Package Testing:* A Package Test (ptest) runs tests against packages |
143 | built by the OpenEmbedded build system on the target machine. See the | 141 | built by the OpenEmbedded build system on the target machine. See the |
144 | :ref:`Testing Packages With | 142 | :ref:`Testing Packages With |
145 | ptest <dev-manual/common-tasks:Testing Packages With ptest>` section | 143 | ptest <dev-manual/packages:Testing Packages With ptest>` section |
146 | in the Yocto Project Development Tasks Manual and the | 144 | in the Yocto Project Development Tasks Manual and the |
147 | ":yocto_wiki:`Ptest </Ptest>`" Wiki page for more | 145 | ":yocto_wiki:`Ptest </Ptest>`" Wiki page for more |
148 | information on Ptest. | 146 | information on Ptest. |
@@ -151,7 +149,7 @@ thefollowing types of tests: | |||
151 | 149 | ||
152 | $ bitbake image -c testsdk | 150 | $ bitbake image -c testsdk |
153 | 151 | ||
154 | The tests utilize the :ref:`testsdk <ref-classes-testsdk>` class and | 152 | The tests use the :ref:`ref-classes-testsdk` class and |
155 | the ``do_testsdk`` task. | 153 | the ``do_testsdk`` task. |
156 | 154 | ||
157 | - *Unit Testing:* Unit tests on various components of the system run | 155 | - *Unit Testing:* Unit tests on various components of the system run |
@@ -174,48 +172,55 @@ Tests map into the codebase as follows: | |||
174 | which include the fetchers. The tests are located in | 172 | which include the fetchers. The tests are located in |
175 | ``bitbake/lib/*/tests``. | 173 | ``bitbake/lib/*/tests``. |
176 | 174 | ||
175 | Some of these tests run the ``bitbake`` command, so ``bitbake/bin`` | ||
176 | must be added to the ``PATH`` before running ``bitbake-selftest``. | ||
177 | From within the BitBake repository, run the following:: | 177 | From within the BitBake repository, run the following:: |
178 | 178 | ||
179 | $ bitbake-selftest | 179 | $ export PATH=$PWD/bin:$PATH |
180 | 180 | ||
181 | To skip tests that access the Internet, use the ``BB_SKIP_NETTEST`` | 181 | After that, you can run the selftest script:: |
182 | variable when running "bitbake-selftest" as follows:: | ||
183 | 182 | ||
184 | $ BB_SKIP_NETTEST=yes bitbake-selftest | 183 | $ bitbake-selftest |
185 | 184 | ||
186 | The default output is quiet and just prints a summary of what was | 185 | The default output is quiet and just prints a summary of what was |
187 | run. To see more information, there is a verbose option:: | 186 | run. To see more information, there is a verbose option:: |
188 | 187 | ||
189 | $ bitbake-selftest -v | 188 | $ bitbake-selftest -v |
190 | 189 | ||
190 | To skip tests that access the Internet, use the ``BB_SKIP_NETTESTS`` | ||
191 | variable when running ``bitbake-selftest`` as follows:: | ||
192 | |||
193 | $ BB_SKIP_NETTESTS=yes bitbake-selftest | ||
194 | |||
191 | Use this option when you wish to skip tests that access the network, | 195 | Use this option when you wish to skip tests that access the network, |
192 | which are mostly necessary to test the fetcher modules. To specify | 196 | which are mostly necessary to test the fetcher modules. To specify |
193 | individual test modules to run, append the test module name to the | 197 | individual test modules to run, append the test module name to the |
194 | "bitbake-selftest" command. For example, to specify the tests for the | 198 | ``bitbake-selftest`` command. For example, to specify the tests for |
195 | bb.data.module, run:: | 199 | ``bb.tests.data.DataExpansions``, run:: |
196 | 200 | ||
197 | $ bitbake-selftest bb.test.data.module | 201 | $ bitbake-selftest bb.tests.data.DataExpansions |
198 | 202 | ||
199 | You can also specify individual tests by defining the full name and module | 203 | You can also specify individual tests by defining the full name and module |
200 | plus the class path of the test, for example:: | 204 | plus the class path of the test, for example:: |
201 | 205 | ||
202 | $ bitbake-selftest bb.tests.data.TestOverrides.test_one_override | 206 | $ bitbake-selftest bb.tests.data.DataExpansions.test_one_var |
203 | 207 | ||
204 | The tests are based on `Python | 208 | The tests are based on |
205 | unittest <https://docs.python.org/3/library/unittest.html>`__. | 209 | `Python unittest <https://docs.python.org/3/library/unittest.html>`__. |
206 | 210 | ||
207 | - *oe-selftest:* | 211 | - *oe-selftest:* |
208 | 212 | ||
209 | - These tests use OE to test the workflows, which include testing | 213 | - These tests use OE to test the workflows, which include testing |
210 | specific features, behaviors of tasks, and API unit tests. | 214 | specific features, behaviors of tasks, and API unit tests. |
211 | 215 | ||
212 | - The tests can take advantage of parallelism through the "-j" | 216 | - The tests can take advantage of parallelism through the ``-j`` |
213 | option, which can specify a number of threads to spread the tests | 217 | option, which can specify a number of threads to spread the tests |
214 | across. Note that all tests from a given class of tests will run | 218 | across. Note that all tests from a given class of tests will run |
215 | in the same thread. To parallelize large numbers of tests you can | 219 | in the same thread. To parallelize large numbers of tests you can |
216 | split the class into multiple units. | 220 | split the class into multiple units. |
217 | 221 | ||
218 | - The tests are based on Python unittest. | 222 | - The tests are based on |
223 | `Python unittest <https://docs.python.org/3/library/unittest.html>`__. | ||
219 | 224 | ||
220 | - The code for the tests resides in | 225 | - The code for the tests resides in |
221 | ``meta/lib/oeqa/selftest/cases/``. | 226 | ``meta/lib/oeqa/selftest/cases/``. |
@@ -225,18 +230,18 @@ Tests map into the codebase as follows: | |||
225 | $ oe-selftest -a | 230 | $ oe-selftest -a |
226 | 231 | ||
227 | - To run a specific test, use the following command form where | 232 | - To run a specific test, use the following command form where |
228 | testname is the name of the specific test:: | 233 | ``testname`` is the name of the specific test:: |
229 | 234 | ||
230 | $ oe-selftest -r <testname> | 235 | $ oe-selftest -r <testname> |
231 | 236 | ||
232 | For example, the following command would run the tinfoil | 237 | For example, the following command would run the ``tinfoil`` |
233 | getVar API test:: | 238 | ``getVar`` API test:: |
234 | 239 | ||
235 | $ oe-selftest -r tinfoil.TinfoilTests.test_getvar | 240 | $ oe-selftest -r tinfoil.TinfoilTests.test_getvar |
236 | 241 | ||
237 | It is also possible to run a set | 242 | It is also possible to run a set |
238 | of tests. For example the following command will run all of the | 243 | of tests. For example the following command will run all of the |
239 | tinfoil tests:: | 244 | ``tinfoil`` tests:: |
240 | 245 | ||
241 | $ oe-selftest -r tinfoil | 246 | $ oe-selftest -r tinfoil |
242 | 247 | ||
@@ -271,7 +276,7 @@ Tests map into the codebase as follows: | |||
271 | - These tests build an extended SDK (eSDK), install that eSDK, and | 276 | - These tests build an extended SDK (eSDK), install that eSDK, and |
272 | run tests against the eSDK. | 277 | run tests against the eSDK. |
273 | 278 | ||
274 | - The code for these tests resides in ``meta/lib/oeqa/esdk``. | 279 | - The code for these tests resides in ``meta/lib/oeqa/sdkext/cases/``. |
275 | 280 | ||
276 | - To run the tests, use the following command form:: | 281 | - To run the tests, use the following command form:: |
277 | 282 | ||
@@ -298,13 +303,13 @@ Tests map into the codebase as follows: | |||
298 | Git repository. | 303 | Git repository. |
299 | 304 | ||
300 | Use the ``oe-build-perf-report`` command to generate text reports | 305 | Use the ``oe-build-perf-report`` command to generate text reports |
301 | and HTML reports with graphs of the performance data. For | 306 | and HTML reports with graphs of the performance data. See |
302 | examples, see | 307 | :yocto_dl:`html </releases/yocto/yocto-4.3/testresults/buildperf-debian11/perf-debian11_nanbield_20231019191258_15b576c410.html>` |
303 | :yocto_dl:`/releases/yocto/yocto-2.7/testresults/buildperf-centos7/perf-centos7.yoctoproject.org_warrior_20190414204758_0e39202.html` | ||
304 | and | 308 | and |
305 | :yocto_dl:`/releases/yocto/yocto-2.7/testresults/buildperf-centos7/perf-centos7.yoctoproject.org_warrior_20190414204758_0e39202.txt`. | 309 | :yocto_dl:`txt </releases/yocto/yocto-4.3/testresults/buildperf-debian11/perf-debian11_nanbield_20231019191258_15b576c410.txt>` |
310 | examples. | ||
306 | 311 | ||
307 | - The tests are contained in ``lib/oeqa/buildperf/test_basic.py``. | 312 | - The tests are contained in ``meta/lib/oeqa/buildperf/test_basic.py``. |
308 | 313 | ||
309 | Test Examples | 314 | Test Examples |
310 | ============= | 315 | ============= |
@@ -312,16 +317,14 @@ Test Examples | |||
312 | This section provides example tests for each of the tests listed in the | 317 | This section provides example tests for each of the tests listed in the |
313 | :ref:`test-manual/intro:How Tests Map to Areas of Code` section. | 318 | :ref:`test-manual/intro:How Tests Map to Areas of Code` section. |
314 | 319 | ||
315 | For oeqa tests, testcases for each area reside in the main test | 320 | - ``oe-selftest`` testcases reside in the ``meta/lib/oeqa/selftest/cases`` directory. |
316 | directory at ``meta/lib/oeqa/selftest/cases`` directory. | ||
317 | 321 | ||
318 | For oe-selftest. bitbake testcases reside in the ``lib/bb/tests/`` | 322 | - ``bitbake-selftest`` testcases reside in the ``bitbake/lib/bb/tests/`` directory. |
319 | directory. | ||
320 | 323 | ||
321 | ``bitbake-selftest`` | 324 | ``bitbake-selftest`` |
322 | -------------------- | 325 | -------------------- |
323 | 326 | ||
324 | A simple test example from ``lib/bb/tests/data.py`` is:: | 327 | A simple test example from ``bitbake/lib/bb/tests/data.py`` is:: |
325 | 328 | ||
326 | class DataExpansions(unittest.TestCase): | 329 | class DataExpansions(unittest.TestCase): |
327 | def setUp(self): | 330 | def setUp(self): |
@@ -334,21 +337,24 @@ A simple test example from ``lib/bb/tests/data.py`` is:: | |||
334 | val = self.d.expand("${foo}") | 337 | val = self.d.expand("${foo}") |
335 | self.assertEqual(str(val), "value_of_foo") | 338 | self.assertEqual(str(val), "value_of_foo") |
336 | 339 | ||
337 | In this example, a ``DataExpansions`` class of tests is created, | 340 | In this example, a ``DataExpansions`` class of tests is created, derived from |
338 | derived from standard python unittest. The class has a common ``setUp`` | 341 | standard `Python unittest <https://docs.python.org/3/library/unittest.html>`__. |
339 | function which is shared by all the tests in the class. A simple test is | 342 | The class has a common ``setUp`` function which is shared by all the tests in |
340 | then added to test that when a variable is expanded, the correct value | 343 | the class. A simple test is then added to test that when a variable is |
341 | is found. | 344 | expanded, the correct value is found. |
342 | 345 | ||
343 | Bitbake selftests are straightforward python unittest. Refer to the | 346 | BitBake selftests are straightforward |
344 | Python unittest documentation for additional information on writing | 347 | `Python unittest <https://docs.python.org/3/library/unittest.html>`__. |
345 | these tests at: https://docs.python.org/3/library/unittest.html. | 348 | Refer to the `Python unittest documentation |
349 | <https://docs.python.org/3/library/unittest.html>`__ for additional information | ||
350 | on writing such tests. | ||
346 | 351 | ||
347 | ``oe-selftest`` | 352 | ``oe-selftest`` |
348 | --------------- | 353 | --------------- |
349 | 354 | ||
350 | These tests are more complex due to the setup required behind the scenes | 355 | These tests are more complex due to the setup required behind the scenes |
351 | for full builds. Rather than directly using Python's unittest, the code | 356 | for full builds. Rather than directly using `Python unittest |
357 | <https://docs.python.org/3/library/unittest.html>`__, the code | ||
352 | wraps most of the standard objects. The tests can be simple, such as | 358 | wraps most of the standard objects. The tests can be simple, such as |
353 | testing a command from within the OE build environment using the | 359 | testing a command from within the OE build environment using the |
354 | following example:: | 360 | following example:: |
@@ -385,14 +391,14 @@ so tests within a given test class should always run in the same build, | |||
385 | while tests in different classes or modules may be split into different | 391 | while tests in different classes or modules may be split into different |
386 | builds. There is no data store available for these tests since the tests | 392 | builds. There is no data store available for these tests since the tests |
387 | launch the ``bitbake`` command and exist outside of its context. As a | 393 | launch the ``bitbake`` command and exist outside of its context. As a |
388 | result, common bitbake library functions (bb.\*) are also unavailable. | 394 | result, common BitBake library functions (``bb.\*``) are also unavailable. |
389 | 395 | ||
390 | ``testimage`` | 396 | ``testimage`` |
391 | ------------- | 397 | ------------- |
392 | 398 | ||
393 | These tests are run once an image is up and running, either on target | 399 | These tests are run once an image is up and running, either on target |
394 | hardware or under QEMU. As a result, they are assumed to be running in a | 400 | hardware or under QEMU. As a result, they are assumed to be running in a |
395 | target image environment, as opposed to a host build environment. A | 401 | target image environment, as opposed to in a host build environment. A |
396 | simple example from ``meta/lib/oeqa/runtime/cases/python.py`` contains | 402 | simple example from ``meta/lib/oeqa/runtime/cases/python.py`` contains |
397 | the following:: | 403 | the following:: |
398 | 404 | ||
@@ -407,19 +413,19 @@ the following:: | |||
407 | 413 | ||
408 | In this example, the ``OERuntimeTestCase`` class wraps | 414 | In this example, the ``OERuntimeTestCase`` class wraps |
409 | ``unittest.TestCase``. Within the test, ``self.target`` represents the | 415 | ``unittest.TestCase``. Within the test, ``self.target`` represents the |
410 | target system, where commands can be run on it using the ``run()`` | 416 | target system, where commands can be run using the ``run()`` |
411 | method. | 417 | method. |
412 | 418 | ||
413 | To ensure certain test or package dependencies are met, you can use the | 419 | To ensure certain tests or package dependencies are met, you can use the |
414 | ``OETestDepends`` and ``OEHasPackage`` decorators. For example, the test | 420 | ``OETestDepends`` and ``OEHasPackage`` decorators. For example, the test |
415 | in this example would only make sense if python3-core is installed in | 421 | in this example would only make sense if ``python3-core`` is installed in |
416 | the image. | 422 | the image. |
417 | 423 | ||
418 | ``testsdk_ext`` | 424 | ``testsdk_ext`` |
419 | --------------- | 425 | --------------- |
420 | 426 | ||
421 | These tests are run against built extensible SDKs (eSDKs). The tests can | 427 | These tests are run against built extensible SDKs (eSDKs). The tests can |
422 | assume that the eSDK environment has already been setup. An example from | 428 | assume that the eSDK environment has already been set up. An example from |
423 | ``meta/lib/oeqa/sdk/cases/devtool.py`` contains the following:: | 429 | ``meta/lib/oeqa/sdk/cases/devtool.py`` contains the following:: |
424 | 430 | ||
425 | class DevtoolTest(OESDKExtTestCase): | 431 | class DevtoolTest(OESDKExtTestCase): |
@@ -466,15 +472,15 @@ following:: | |||
466 | output = self._run(cmd) | 472 | output = self._run(cmd) |
467 | self.assertEqual(output, "Hello, world\n") | 473 | self.assertEqual(output, "Hello, world\n") |
468 | 474 | ||
469 | In this example, if nativesdk-python3-core has been installed into the SDK, the code runs | 475 | In this example, if ``nativesdk-python3-core`` has been installed into the SDK, |
470 | the python3 interpreter with a basic command to check it is working | 476 | the code runs the ``python3`` interpreter with a basic command to check it is |
471 | correctly. The test would only run if python3 is installed in the SDK. | 477 | working correctly. The test would only run if Python3 is installed in the SDK. |
472 | 478 | ||
473 | ``oe-build-perf-test`` | 479 | ``oe-build-perf-test`` |
474 | ---------------------- | 480 | ---------------------- |
475 | 481 | ||
476 | The performance tests usually measure how long operations take and the | 482 | The performance tests usually measure how long operations take and the |
477 | resource utilisation as that happens. An example from | 483 | resource utilization as that happens. An example from |
478 | ``meta/lib/oeqa/buildperf/test_basic.py`` contains the following:: | 484 | ``meta/lib/oeqa/buildperf/test_basic.py`` contains the following:: |
479 | 485 | ||
480 | class Test3(BuildPerfTestCase): | 486 | class Test3(BuildPerfTestCase): |
@@ -506,15 +512,15 @@ workers, consider the following: | |||
506 | 512 | ||
507 | **Running "cleanall" is not permitted.** | 513 | **Running "cleanall" is not permitted.** |
508 | 514 | ||
509 | This can delete files from DL_DIR which would potentially break other | 515 | This can delete files from :term:`DL_DIR` which would potentially break other |
510 | builds running in parallel. If this is required, DL_DIR must be set to | 516 | builds running in parallel. If this is required, :term:`DL_DIR` must be set to |
511 | an isolated directory. | 517 | an isolated directory. |
512 | 518 | ||
513 | **Running "cleansstate" is not permitted.** | 519 | **Running "cleansstate" is not permitted.** |
514 | 520 | ||
515 | This can delete files from SSTATE_DIR which would potentially break | 521 | This can delete files from :term:`SSTATE_DIR` which would potentially break |
516 | other builds running in parallel. If this is required, SSTATE_DIR must | 522 | other builds running in parallel. If this is required, :term:`SSTATE_DIR` must |
517 | be set to an isolated directory. Alternatively, you can use the "-f" | 523 | be set to an isolated directory. Alternatively, you can use the ``-f`` |
518 | option with the ``bitbake`` command to "taint" tasks by changing the | 524 | option with the ``bitbake`` command to "taint" tasks by changing the |
519 | sstate checksums to ensure sstate cache items will not be reused. | 525 | sstate checksums to ensure sstate cache items will not be reused. |
520 | 526 | ||
@@ -524,5 +530,5 @@ This is particularly true for oe-selftests since these can run in | |||
524 | parallel and changing metadata leads to changing checksums, which | 530 | parallel and changing metadata leads to changing checksums, which |
525 | confuses BitBake while running in parallel. If this is necessary, copy | 531 | confuses BitBake while running in parallel. If this is necessary, copy |
526 | layers to a temporary location and modify them. Some tests need to | 532 | layers to a temporary location and modify them. Some tests need to |
527 | change metadata, such as the devtool tests. To prevent the metadate from | 533 | change metadata, such as the devtool tests. To protect the metadata from |
528 | changes, set up temporary copies of that data first. | 534 | changes, set up temporary copies of that data first. |
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst new file mode 100644 index 0000000000..91f94a5c74 --- /dev/null +++ b/documentation/test-manual/reproducible-builds.rst | |||
@@ -0,0 +1,137 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ******************* | ||
4 | Reproducible Builds | ||
5 | ******************* | ||
6 | |||
7 | ================ | ||
8 | How we define it | ||
9 | ================ | ||
10 | |||
11 | The Yocto Project defines reproducibility as where a given input build | ||
12 | configuration 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 | ||
14 | run in, and regardless of the distro and tools on the underlying host system the | ||
15 | build is running on. | ||
16 | |||
17 | ============== | ||
18 | Why it matters | ||
19 | ============== | ||
20 | |||
21 | The project aligns with the `Reproducible Builds project | ||
22 | <https://reproducible-builds.org/>`__, which shares information about why | ||
23 | reproducibility matters. The primary focus of the project is the ability to | ||
24 | detect security issues being introduced. However, from a Yocto Project | ||
25 | perspective, it is also hugely important that our builds are deterministic. When | ||
26 | you build a given input set of metadata, we expect you to get consistent output. | ||
27 | This 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>`, | ||
29 | it is now true down to the binary level including timestamps. | ||
30 | |||
31 | For example, at some point in the future life of a product, you find that you | ||
32 | need to rebuild to add a security fix. If this happens, only the components that | ||
33 | have been modified should change at the binary level. This would lead to much | ||
34 | easier and clearer bounds on where validation is needed. | ||
35 | |||
36 | This 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 | ||
39 | effectively when the binary output remains the same. | ||
40 | |||
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 | =================== | ||
48 | How we implement it | ||
49 | =================== | ||
50 | |||
51 | There are many different aspects to build reproducibility, but some particular | ||
52 | things 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 | ||
56 | :term:`DEBUG_PREFIX_MAP` variable which sets the ``-fmacro-prefix-map`` and | ||
57 | ``-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 | |||
71 | ========================================= | ||
72 | Can we prove the project is reproducible? | ||
73 | ========================================= | ||
74 | |||
75 | Yes, we can prove it and we regularly test this on the Autobuilder. At the | ||
76 | time of writing (release 3.3, "hardknott"), :term:`OpenEmbedded-Core (OE-Core)` | ||
77 | is 100% reproducible for all its recipes (i.e. world builds) apart from the Go | ||
78 | language and Ruby documentation packages. Unfortunately, the current | ||
79 | implementation of the Go language has fundamental reproducibility problems as | ||
80 | it 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 | |||
89 | To run our automated selftest, as we use in our CI on the Autobuilder, you can | ||
90 | run:: | ||
91 | |||
92 | oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds | ||
93 | |||
94 | This defaults to including a ``world`` build so, if other layers are added, it would | ||
95 | also run the tests for recipes in the additional layers. Different build targets | ||
96 | can be defined using the :term:`OEQA_REPRODUCIBLE_TEST_TARGET` variable in ``local.conf``. | ||
97 | The first build will be run using :ref:`Shared State <overview-manual/concepts:Shared State>` if | ||
98 | available, the second build explicitly disables | ||
99 | :ref:`Shared State <overview-manual/concepts:Shared State>` except for recipes defined in | ||
100 | the :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` variable, and builds on the | ||
101 | specific host the build is running on. This means we can test reproducibility | ||
102 | builds between different host distributions over time on the Autobuilder. | ||
103 | |||
104 | If ``OEQA_DEBUGGING_SAVED_OUTPUT`` is set, any differing packages will be saved | ||
105 | here. The test is also able to run the ``diffoscope`` command on the output to | ||
106 | generate HTML files showing the differences between the packages, to aid | ||
107 | debugging. On the Autobuilder, these appear under | ||
108 | https://autobuilder.yocto.io/pub/repro-fail/ in the form ``oe-reproducible + | ||
109 | <date> + <random ID>``, e.g. ``oe-reproducible-20200202-1lm8o1th``. | ||
110 | |||
111 | The project's current reproducibility status can be seen at | ||
112 | :yocto_home:`/reproducible-build-results/` | ||
113 | |||
114 | You 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 | =============================== | ||
122 | Can I test my layer or recipes? | ||
123 | =============================== | ||
124 | |||
125 | Once again, you can run a ``world`` test using the | ||
126 | :ref:`oe-selftest <ref-manual/release-process:Testing and Quality Assurance>` | ||
127 | command provided above. This functionality is implemented | ||
128 | in :oe_git:`meta/lib/oeqa/selftest/cases/reproducible.py | ||
129 | </openembedded-core/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`. | ||
130 | |||
131 | You could subclass the test and change ``targets`` to a different target. | ||
132 | |||
133 | You may also change ``sstate_targets`` which would allow you to "pre-cache" some | ||
134 | set of recipes before the test, meaning they are excluded from reproducibility | ||
135 | testing. As a practical example, you could set ``sstate_targets`` to | ||
136 | ``core-image-sato``, then setting ``targets`` to ``core-image-sato-sdk`` would | ||
137 | run reproducibility tests only on the targets belonging only to ``core-image-sato-sdk``. | ||
diff --git a/documentation/test-manual/test-process.rst b/documentation/test-manual/test-process.rst index 8a5e29d922..7bec5ba828 100644 --- a/documentation/test-manual/test-process.rst +++ b/documentation/test-manual/test-process.rst | |||
@@ -20,8 +20,8 @@ helps review and test patches and this is his testing tree). | |||
20 | We have two broad categories of test builds, including "full" and | 20 | We have two broad categories of test builds, including "full" and |
21 | "quick". On the Autobuilder, these can be seen as "a-quick" and | 21 | "quick". On the Autobuilder, these can be seen as "a-quick" and |
22 | "a-full", simply for ease of sorting in the UI. Use our Autobuilder | 22 | "a-full", simply for ease of sorting in the UI. Use our Autobuilder |
23 | console view to see where me manage most test-related items, available | 23 | :yocto_ab:`console view </typhoon/#/console>` to see where we manage most |
24 | at: :yocto_ab:`/typhoon/#/console`. | 24 | test-related items. |
25 | 25 | ||
26 | Builds are triggered manually when the test branches are ready. The | 26 | Builds are triggered manually when the test branches are ready. The |
27 | builds are monitored by the SWAT team. For additional information, see | 27 | builds are monitored by the SWAT team. For additional information, see |
@@ -34,24 +34,21 @@ which the result was required. | |||
34 | 34 | ||
35 | The Autobuilder does build the ``master`` branch once daily for several | 35 | The Autobuilder does build the ``master`` branch once daily for several |
36 | reasons, in particular, to ensure the current ``master`` branch does | 36 | reasons, in particular, to ensure the current ``master`` branch does |
37 | build, but also to keep ``yocto-testresults`` | 37 | build, but also to keep (:yocto_git:`yocto-testresults </yocto-testresults/>`), |
38 | (:yocto_git:`/yocto-testresults/`), | 38 | (:yocto_git:`buildhistory </poky-buildhistory/>`), and |
39 | buildhistory | 39 | our sstate up to date. On the weekend, there is a ``master-next`` build |
40 | (:yocto_git:`/poky-buildhistory/`), and | ||
41 | our sstate up to date. On the weekend, there is a master-next build | ||
42 | instead to ensure the test results are updated for the less frequently | 40 | instead to ensure the test results are updated for the less frequently |
43 | run targets. | 41 | run targets. |
44 | 42 | ||
45 | Performance builds (buildperf-\* targets in the console) are triggered | 43 | Performance builds (``buildperf-\*`` targets in the console) are triggered |
46 | separately every six hours and automatically push their results to the | 44 | separately every six hours and automatically push their results to the |
47 | buildstats repository at: | 45 | :yocto_git:`buildstats </yocto-buildstats/>` repository. |
48 | :yocto_git:`/yocto-buildstats/`. | ||
49 | 46 | ||
50 | The 'quick' targets have been selected to be the ones which catch the | 47 | The "quick" targets have been selected to be the ones which catch the |
51 | most failures or give the most valuable data. We run 'fast' ptests in | 48 | most failures or give the most valuable data. We run "fast" ptests in |
52 | this case for example but not the ones which take a long time. The quick | 49 | this case for example but not the ones which take a long time. The quick |
53 | target doesn't include \*-lsb builds for all architectures, some world | 50 | target doesn't include ``\*-lsb`` builds for all architectures, some ``world`` |
54 | builds and doesn't trigger performance tests or ltp testing. The full | 51 | builds and doesn't trigger performance tests or ``ltp`` testing. The full |
55 | build includes all these things and is slower but more comprehensive. | 52 | build includes all these things and is slower but more comprehensive. |
56 | 53 | ||
57 | Release Builds | 54 | Release Builds |
@@ -59,20 +56,20 @@ Release Builds | |||
59 | 56 | ||
60 | The project typically has two major releases a year with a six month | 57 | The project typically has two major releases a year with a six month |
61 | cadence in April and October. Between these there would be a number of | 58 | cadence in April and October. Between these there would be a number of |
62 | milestone releases (usually four) with the final one being stablization | 59 | milestone releases (usually four) with the final one being stabilization |
63 | only along with point releases of our stable branches. | 60 | only along with point releases of our stable branches. |
64 | 61 | ||
65 | The build and release process for these project releases is similar to | 62 | The build and release process for these project releases is similar to |
66 | that in `Day to Day Development <#test-daily-devel>`__, in that the | 63 | that in :ref:`test-manual/test-process:day to day development`, in that the |
67 | a-full target of the Autobuilder is used but in addition the form is | 64 | a-full target of the Autobuilder is used but in addition the form is |
68 | configured to generate and publish artefacts and the milestone number, | 65 | configured to generate and publish artifacts and the milestone number, |
69 | version, release candidate number and other information is entered. The | 66 | version, release candidate number and other information is entered. The |
70 | box to "generate an email to QA"is also checked. | 67 | box to "generate an email to QA" is also checked. |
71 | 68 | ||
72 | When the build completes, an email is sent out using the send-qa-email | 69 | When the build completes, an email is sent out using the ``send-qa-email`` |
73 | script in the ``yocto-autobuilder-helper`` repository to the list of | 70 | script in the :yocto_git:`yocto-autobuilder-helper </yocto-autobuilder-helper>` |
74 | people configured for that release. Release builds are placed into a | 71 | repository to the list of people configured for that release. Release builds |
75 | directory in https://autobuilder.yocto.io/pub/releases on the | 72 | are placed into a directory in https://autobuilder.yocto.io/pub/releases on the |
76 | Autobuilder which is included in the email. The process from here is | 73 | Autobuilder which is included in the email. The process from here is |
77 | more manual and control is effectively passed to release engineering. | 74 | more manual and control is effectively passed to release engineering. |
78 | The next steps include: | 75 | The next steps include: |
@@ -80,14 +77,15 @@ The next steps include: | |||
80 | - QA teams respond to the email saying which tests they plan to run and | 77 | - QA teams respond to the email saying which tests they plan to run and |
81 | when the results will be available. | 78 | when the results will be available. |
82 | 79 | ||
83 | - QA teams run their tests and share their results in the yocto- | 80 | - QA teams run their tests and share their results in the |
84 | testresults-contrib repository, along with a summary of their | 81 | :yocto_git:`yocto-testresults-contrib </yocto-testresults-contrib>` |
85 | findings. | 82 | repository, along with a summary of their findings. |
86 | 83 | ||
87 | - Release engineering prepare the release as per their process. | 84 | - Release engineering prepare the release as per their process. |
88 | 85 | ||
89 | - Test results from the QA teams are included into the release in | 86 | - Test results from the QA teams are included into the release in |
90 | separate directories and also uploaded to the yocto-testresults | 87 | separate directories and also uploaded to the |
88 | :yocto_git:`yocto-testresults </yocto-testresults>` | ||
91 | repository alongside the other test results for the given revision. | 89 | repository alongside the other test results for the given revision. |
92 | 90 | ||
93 | - The QA report in the final release is regenerated using resulttool to | 91 | - The QA report in the final release is regenerated using resulttool to |
diff --git a/documentation/test-manual/understand-autobuilder.rst b/documentation/test-manual/understand-autobuilder.rst index 199cc97a85..6b4fab4f0b 100644 --- a/documentation/test-manual/understand-autobuilder.rst +++ b/documentation/test-manual/understand-autobuilder.rst | |||
@@ -9,31 +9,31 @@ Execution Flow within the Autobuilder | |||
9 | 9 | ||
10 | The "a-full" and "a-quick" targets are the usual entry points into the | 10 | The "a-full" and "a-quick" targets are the usual entry points into the |
11 | Autobuilder and it makes sense to follow the process through the system | 11 | Autobuilder and it makes sense to follow the process through the system |
12 | starting there. This is best visualised from the Autobuilder Console | 12 | starting there. This is best visualized from the :yocto_ab:`Autobuilder |
13 | view (:yocto_ab:`/typhoon/#/console`). | 13 | Console view </typhoon/#/console>`. |
14 | 14 | ||
15 | Each item along the top of that view represents some "target build" and | 15 | Each item along the top of that view represents some "target build" and |
16 | these targets are all run in parallel. The 'full' build will trigger the | 16 | these targets are all run in parallel. The 'full' build will trigger the |
17 | majority of them, the "quick" build will trigger some subset of them. | 17 | majority of them, the "quick" build will trigger some subset of them. |
18 | The Autobuilder effectively runs whichever configuration is defined for | 18 | The Autobuilder effectively runs whichever configuration is defined for |
19 | each of those targets on a seperate buildbot worker. To understand the | 19 | each of those targets on a separate buildbot worker. To understand the |
20 | configuration, you need to look at the entry on ``config.json`` file | 20 | configuration, you need to look at the entry on ``config.json`` file |
21 | within the ``yocto-autobuilder-helper`` repository. The targets are | 21 | within the :yocto_git:`yocto-autobuilder-helper </yocto-autobuilder-helper>` |
22 | defined in the ‘overrides' section, a quick example could be qemux86-64 | 22 | repository. The targets are defined in the ``overrides`` section, a quick |
23 | which looks like:: | 23 | example could be ``qemux86-64`` which looks like:: |
24 | 24 | ||
25 | "qemux86-64" : { | 25 | "qemux86-64" : { |
26 | "MACHINE" : "qemux86-64", | 26 | "MACHINE" : "qemux86-64", |
27 | "TEMPLATE" : "arch-qemu", | 27 | "TEMPLATE" : "arch-qemu", |
28 | "step1" : { | 28 | "step1" : { |
29 | "extravars" : [ | 29 | "extravars" : [ |
30 | "IMAGE_FSTYPES_append = ' wic wic.bmap'" | 30 | "IMAGE_FSTYPES:append = ' wic wic.bmap'" |
31 | ] | 31 | ] |
32 | } | 32 | } |
33 | }, | 33 | }, |
34 | 34 | ||
35 | And to expand that, you need the "arch-qemu" entry from | 35 | And to expand that, you need the ``arch-qemu`` entry from |
36 | the "templates" section, which looks like:: | 36 | the ``templates`` section, which looks like:: |
37 | 37 | ||
38 | "arch-qemu" : { | 38 | "arch-qemu" : { |
39 | "BUILDINFO" : true, | 39 | "BUILDINFO" : true, |
@@ -54,20 +54,20 @@ the "templates" section, which looks like:: | |||
54 | } | 54 | } |
55 | }, | 55 | }, |
56 | 56 | ||
57 | Combining these two entries you can see that "qemux86-64" is a three step build where the | 57 | Combining these two entries you can see that ``qemux86-64`` is a three step |
58 | ``bitbake BBTARGETS`` would be run, then ``bitbake SANITYTARGETS`` for each step; all for | 58 | build where ``bitbake BBTARGETS`` would be run, then ``bitbake SANITYTARGETS`` |
59 | ``MACHINE="qemx86-64"`` but with differing SDKMACHINE settings. In step | 59 | for each step; all for ``MACHINE="qemux86-64"`` but with differing |
60 | 1 an extra variable is added to the ``auto.conf`` file to enable wic | 60 | :term:`SDKMACHINE` settings. In step 1, an extra variable is added to the |
61 | image generation. | 61 | ``auto.conf`` file to enable wic image generation. |
62 | 62 | ||
63 | While not every detail of this is covered here, you can see how the | 63 | While not every detail of this is covered here, you can see how the |
64 | template mechanism allows quite complex configurations to be built up | 64 | template mechanism allows quite complex configurations to be built up |
65 | yet allows duplication and repetition to be kept to a minimum. | 65 | yet allows duplication and repetition to be kept to a minimum. |
66 | 66 | ||
67 | The different build targets are designed to allow for parallelisation, | 67 | The different build targets are designed to allow for parallelization, |
68 | so different machines are usually built in parallel, operations using | 68 | so different machines are usually built in parallel, operations using |
69 | the same machine and metadata are built sequentially, with the aim of | 69 | the same machine and metadata are built sequentially, with the aim of |
70 | trying to optimise build efficiency as much as possible. | 70 | trying to optimize build efficiency as much as possible. |
71 | 71 | ||
72 | The ``config.json`` file is processed by the scripts in the Helper | 72 | The ``config.json`` file is processed by the scripts in the Helper |
73 | repository in the ``scripts`` directory. The following section details | 73 | repository in the ``scripts`` directory. The following section details |
@@ -88,9 +88,9 @@ roughly consist of: | |||
88 | 88 | ||
89 | #. *Obtain yocto-autobuilder-helper* | 89 | #. *Obtain yocto-autobuilder-helper* |
90 | 90 | ||
91 | This step clones the ``yocto-autobuilder-helper`` git repository. | 91 | This step clones the :yocto_git:`yocto-autobuilder-helper </yocto-autobuilder-helper>` |
92 | This is necessary to prevent the requirement to maintain all the | 92 | git repository. This is necessary to avoid the requirement to maintain all |
93 | release or project-specific code within Buildbot. The branch chosen | 93 | the release or project-specific code within Buildbot. The branch chosen |
94 | matches the release being built so we can support older releases and | 94 | matches the release being built so we can support older releases and |
95 | still make changes in newer ones. | 95 | still make changes in newer ones. |
96 | 96 | ||
@@ -111,7 +111,7 @@ roughly consist of: | |||
111 | :ref:`test-manual/understand-autobuilder:Autobuilder Clone Cache`. | 111 | :ref:`test-manual/understand-autobuilder:Autobuilder Clone Cache`. |
112 | 112 | ||
113 | This step has two possible modes of operation. If the build is part | 113 | This step has two possible modes of operation. If the build is part |
114 | of a parent build, its possible that all the repositories needed may | 114 | of a parent build, it's possible that all the repositories needed may |
115 | already be available, ready in a pre-prepared directory. An "a-quick" | 115 | already be available, ready in a pre-prepared directory. An "a-quick" |
116 | or "a-full" build would prepare this before starting the other | 116 | or "a-full" build would prepare this before starting the other |
117 | sub-target builds. This is done for two reasons: | 117 | sub-target builds. This is done for two reasons: |
@@ -130,7 +130,7 @@ roughly consist of: | |||
130 | 130 | ||
131 | #. *Call scripts/run-config* | 131 | #. *Call scripts/run-config* |
132 | 132 | ||
133 | This is another call into the Helper scripts where its expected that | 133 | This is another call into the Helper scripts where it's expected that |
134 | the main functionality of this target will be executed. | 134 | the main functionality of this target will be executed. |
135 | 135 | ||
136 | Autobuilder Technology | 136 | Autobuilder Technology |
@@ -163,16 +163,17 @@ Autobuilder Worker Janitor | |||
163 | -------------------------- | 163 | -------------------------- |
164 | 164 | ||
165 | This is a process running on each Worker that performs two basic | 165 | This is a process running on each Worker that performs two basic |
166 | operations, including background file deletion at IO idle (see :ref:`test-manual/understand-autobuilder:Autobuilder Target Execution Overview`: Run clobberdir) and | 166 | operations, including background file deletion at IO idle (see |
167 | maintainenance of a cache of cloned repositories to improve the speed | 167 | "Run clobberdir" in :ref:`test-manual/understand-autobuilder:Autobuilder Target Execution Overview`) |
168 | and maintenance of a cache of cloned repositories to improve the speed | ||
168 | the system can checkout repositories. | 169 | the system can checkout repositories. |
169 | 170 | ||
170 | Shared DL_DIR | 171 | Shared DL_DIR |
171 | ------------- | 172 | ------------- |
172 | 173 | ||
173 | The Workers are all connected over NFS which allows DL_DIR to be shared | 174 | The Workers are all connected over NFS which allows :term:`DL_DIR` to be shared |
174 | between them. This reduces network accesses from the system and allows | 175 | between them. This reduces network accesses from the system and allows |
175 | the build to be sped up. Usage of the directory within the build system | 176 | the build to be sped up. The usage of the directory within the build system |
176 | is designed to be able to be shared over NFS. | 177 | is designed to be able to be shared over NFS. |
177 | 178 | ||
178 | Shared SSTATE_DIR | 179 | Shared SSTATE_DIR |
@@ -180,8 +181,8 @@ Shared SSTATE_DIR | |||
180 | 181 | ||
181 | The Workers are all connected over NFS which allows the ``sstate`` | 182 | The Workers are all connected over NFS which allows the ``sstate`` |
182 | directory to be shared between them. This means once a Worker has built | 183 | directory to be shared between them. This means once a Worker has built |
183 | an artifact, all the others can benefit from it. Usage of the directory | 184 | an artifact, all the others can benefit from it. The usage of the directory |
184 | within the directory is designed for sharing over NFS. | 185 | within the build system is designed for sharing over NFS. |
185 | 186 | ||
186 | Resulttool | 187 | Resulttool |
187 | ---------- | 188 | ---------- |
@@ -192,7 +193,7 @@ in a given build and their status. Additional information, such as | |||
192 | failure logs or the time taken to run the tests, may also be included. | 193 | failure logs or the time taken to run the tests, may also be included. |
193 | 194 | ||
194 | Resulttool is part of OpenEmbedded-Core and is used to manipulate these | 195 | Resulttool is part of OpenEmbedded-Core and is used to manipulate these |
195 | json results files. It has the ability to merge files together, display | 196 | JSON results files. It has the ability to merge files together, display |
196 | reports of the test results and compare different result files. | 197 | reports of the test results and compare different result files. |
197 | 198 | ||
198 | For details, see :yocto_wiki:`/Resulttool`. | 199 | For details, see :yocto_wiki:`/Resulttool`. |
@@ -204,9 +205,9 @@ The ``scripts/run-config`` execution is where most of the work within | |||
204 | the Autobuilder happens. It runs through a number of steps; the first | 205 | the Autobuilder happens. It runs through a number of steps; the first |
205 | are general setup steps that are run once and include: | 206 | are general setup steps that are run once and include: |
206 | 207 | ||
207 | #. Set up any ``buildtools-tarball`` if configured. | 208 | #. Set up any :term:`buildtools` tarball if configured. |
208 | 209 | ||
209 | #. Call "buildhistory-init" if buildhistory is configured. | 210 | #. Call ``buildhistory-init`` if :ref:`ref-classes-buildhistory` is configured. |
210 | 211 | ||
211 | For each step that is configured in ``config.json``, it will perform the | 212 | For each step that is configured in ``config.json``, it will perform the |
212 | following: | 213 | following: |
@@ -242,7 +243,7 @@ of post-build steps, including: | |||
242 | #. Call ``scripts/upload-error-reports`` to send any error reports | 243 | #. Call ``scripts/upload-error-reports`` to send any error reports |
243 | generated to the remote server. | 244 | generated to the remote server. |
244 | 245 | ||
245 | #. Cleanup the build directory using | 246 | #. Cleanup the :term:`Build Directory` using |
246 | :ref:`test-manual/understand-autobuilder:clobberdir` if the build was successful, | 247 | :ref:`test-manual/understand-autobuilder:clobberdir` if the build was successful, |
247 | else rename it to "build-renamed" for potential future debugging. | 248 | else rename it to "build-renamed" for potential future debugging. |
248 | 249 | ||
@@ -250,15 +251,16 @@ Deploying Yocto Autobuilder | |||
250 | =========================== | 251 | =========================== |
251 | 252 | ||
252 | The most up to date information about how to setup and deploy your own | 253 | The most up to date information about how to setup and deploy your own |
253 | Autbuilder can be found in README.md in the ``yocto-autobuilder2`` | 254 | Autobuilder can be found in :yocto_git:`README.md </yocto-autobuilder2/tree/README.md>` |
254 | repository. | 255 | in the :yocto_git:`yocto-autobuilder2 </yocto-autobuilder2>` repository. |
255 | 256 | ||
256 | We hope that people can use the ``yocto-autobuilder2`` code directly but | 257 | We hope that people can use the :yocto_git:`yocto-autobuilder2 </yocto-autobuilder2>` |
257 | it is inevitable that users will end up needing to heavily customise the | 258 | code directly but it is inevitable that users will end up needing to heavily |
258 | ``yocto-autobuilder-helper`` repository, particularly the | 259 | customize the :yocto_git:`yocto-autobuilder-helper </yocto-autobuilder-helper>` |
259 | ``config.json`` file as they will want to define their own test matrix. | 260 | repository, particularly the ``config.json`` file as they will want to define |
261 | their own test matrix. | ||
260 | 262 | ||
261 | The Autobuilder supports wo customization options: | 263 | The Autobuilder supports two customization options: |
262 | 264 | ||
263 | - variable substitution | 265 | - variable substitution |
264 | 266 | ||
@@ -278,7 +280,7 @@ environment:: | |||
278 | $ ABHELPER_JSON="config.json /some/location/local.json" | 280 | $ ABHELPER_JSON="config.json /some/location/local.json" |
279 | 281 | ||
280 | One issue users often run into is validation of the ``config.json`` files. A | 282 | One issue users often run into is validation of the ``config.json`` files. A |
281 | tip for minimizing issues from invalid json files is to use a Git | 283 | tip for minimizing issues from invalid JSON files is to use a Git |
282 | ``pre-commit-hook.sh`` script to verify the JSON file before committing | 284 | ``pre-commit-hook.sh`` script to verify the JSON file before committing |
283 | it. Create a symbolic link as follows:: | 285 | it. Create a symbolic link as follows:: |
284 | 286 | ||
diff --git a/documentation/test-manual/yocto-project-compatible.rst b/documentation/test-manual/yocto-project-compatible.rst new file mode 100644 index 0000000000..65d924fad9 --- /dev/null +++ b/documentation/test-manual/yocto-project-compatible.rst | |||
@@ -0,0 +1,129 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ************************ | ||
4 | Yocto Project Compatible | ||
5 | ************************ | ||
6 | |||
7 | ============ | ||
8 | Introduction | ||
9 | ============ | ||
10 | |||
11 | After the introduction of layers to OpenEmbedded, it quickly became clear | ||
12 | that while some layers were popular and worked well, others developed a | ||
13 | reputation for being "problematic". Those were layers which didn't | ||
14 | interoperate well with others and tended to assume they controlled all | ||
15 | the aspects of the final output. This usually isn't intentional but happens | ||
16 | because such layers are often created by developers with a particular focus | ||
17 | (e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end | ||
18 | users have a different one (e.g. integrating that | ||
19 | :term:`BSP<Board Support Package (BSP)>` into a product). | ||
20 | |||
21 | As a result of noticing such patterns and friction between layers, the project | ||
22 | developed the "Yocto Project Compatible" badge program, allowing layers | ||
23 | following the best known practises to be marked as being widely compatible | ||
24 | with other ones. This takes the form of a set of "yes/no" binary answer | ||
25 | questions where layers can declare if they meet the appropriate criteria. | ||
26 | In the second version of the program, a script was added to make validation | ||
27 | easier and clearer, the script is called ``yocto-check-layer`` and is | ||
28 | available in :term:`OpenEmbedded-Core (OE-Core)`. | ||
29 | |||
30 | See :ref:`dev-manual/layers:making sure your layer is compatible with yocto project` | ||
31 | for details. | ||
32 | |||
33 | ======== | ||
34 | Benefits | ||
35 | ======== | ||
36 | |||
37 | :ref:`overview-manual/yp-intro:the yocto project layer model` is powerful | ||
38 | and flexible: it gives users the ultimate power to change pretty much any | ||
39 | aspect of the system but as with most things, power comes with responsibility. | ||
40 | The Yocto Project would like to see people able to mix and match BSPs with | ||
41 | distro configs or software stacks and be able to merge succesfully. | ||
42 | Over time, the project identified characteristics in layers that allow them | ||
43 | to operate well together. "anti-patterns" were also found, preventing layers | ||
44 | from working well together. | ||
45 | |||
46 | The intent of the compatibility program is simple: if the layer passes the | ||
47 | compatibility tests, it is considered "well behaved" and should operate | ||
48 | and cooperate well with other compatible layers. | ||
49 | |||
50 | The benefits of compatibility can be seen from multiple different user and | ||
51 | member perspectives. From a hardware perspective | ||
52 | (a :ref:`overview-manual/concepts:bsp layer`), compatibility means the | ||
53 | hardware can be used in many different products and use cases without | ||
54 | impacting the software stacks being run with it. For a company developing | ||
55 | a product, compatibility gives you a specification / standard you can | ||
56 | require in a contract and then know it will have certain desired | ||
57 | characteristics for interoperability. It also puts constraints on how invasive | ||
58 | the code bases are into the rest of the system, meaning that multiple | ||
59 | different separate hardware support layers can coexist (e.g. for multiple | ||
60 | product lines from different hardware manufacturers). This can also make it | ||
61 | easier for one or more parties to upgrade those system components for security | ||
62 | purposes during the lifecycle of a product. | ||
63 | |||
64 | ================== | ||
65 | Validating a layer | ||
66 | ================== | ||
67 | |||
68 | The badges are available to members of the Yocto Project (as member benefit) | ||
69 | and to open source projects run on a non-commercial basis. However, anyone can | ||
70 | answer the questions and run the script. | ||
71 | |||
72 | The project encourages all layer maintainers to review the questions and the | ||
73 | output from the script against their layer, as the way some layers are | ||
74 | constructed often has unintended consequences. The questions and the script | ||
75 | are designed to highlight known issues which are often easy to solve. This | ||
76 | makes layers easier to use and therefore more popular. | ||
77 | |||
78 | It is intended that over time, the tests will evolve as new best known | ||
79 | practices are identified, and as new interoperability issues are found, | ||
80 | unnecessarily restricting layer interoperability. If anyone becomes aware of | ||
81 | either type, please let the project know through the | ||
82 | :yocto_home:`technical calls </public-virtual-meetings/>`, | ||
83 | the :yocto_home:`mailing lists </community/mailing-lists/>` | ||
84 | or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`. | ||
85 | The TSC is responsible for the technical criteria used by the program. | ||
86 | |||
87 | Layers are divided into three types: | ||
88 | |||
89 | - :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>` | ||
90 | layers contain support for particular pieces of hardware. This includes | ||
91 | kernel and boot loader configuration, and any recipes for firmware or | ||
92 | kernel modules needed for the hardware. Such layers usually correspond | ||
93 | to a :term:`MACHINE` setting. | ||
94 | |||
95 | - :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined | ||
96 | as layers providing configuration options and settings such as the | ||
97 | choice of init system, compiler and optimisation options, and | ||
98 | configuration and choices of software components. This would usually | ||
99 | correspond to a :term:`DISTRO` setting. | ||
100 | |||
101 | - "software" layers are usually recipes. A layer might target a | ||
102 | particular graphical UI or software stack component. | ||
103 | |||
104 | Here are key best practices the program tries to encourage: | ||
105 | |||
106 | - A layer should clearly show who maintains it, and who change | ||
107 | submissions and bug reports should be sent to. | ||
108 | |||
109 | - Where multiple types of functionality are present, the layer should | ||
110 | be internally divided into sublayers to separate these components. | ||
111 | That's because some users may only need one of them and separability | ||
112 | is a key best practice. | ||
113 | |||
114 | - Adding a layer to a build should not modify that build, unless the | ||
115 | user changes a configuration setting to activate the layer, by selecting | ||
116 | a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting. | ||
117 | |||
118 | - Layers should be documenting where they don’t support normal "core" | ||
119 | functionality such as where debug symbols are disabled or missing, where | ||
120 | development headers and on-target library usage may not work or where | ||
121 | functionality like the SDK/eSDK would not be expected to work. | ||
122 | |||
123 | The project does test the compatibility status of the core project layers on | ||
124 | its :doc:`Autobuilder </test-manual/understand-autobuilder>`. | ||
125 | |||
126 | The official form to submit compatibility requests with is at | ||
127 | :yocto_home:`/ecosystem/branding/compatible-registration/`. | ||
128 | Applicants can display the badge they get when their application is successful. | ||
129 | |||