blob: 429f81e14c70d40816da9b772cf183f3fd39180a [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3**************************
4Source Directory Structure
5**************************
6
7The :term:`Source Directory` consists of numerous files,
8directories and subdirectories; understanding their locations and
9contents is key to using the Yocto Project effectively. This chapter
10describes the Source Directory and gives information about those files
11and directories.
12
13For information on how to establish a local Source Directory on your
14development system, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060015":ref:`dev-manual/start:locating yocto project source files`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050016section in the Yocto Project Development Tasks Manual.
17
18.. note::
19
20 The OpenEmbedded build system does not support file or directory
21 names that contain spaces. Be sure that the Source Directory you use
22 does not contain these types of names.
23
24.. _structure-core:
25
26Top-Level Core Components
27=========================
28
29This section describes the top-level components of the :term:`Source Directory`.
30
31.. _structure-core-bitbake:
32
33``bitbake/``
34------------
35
36This directory includes a copy of BitBake for ease of use. The copy
37usually matches the current stable BitBake release from the BitBake
38project. BitBake, a :term:`Metadata` interpreter, reads the
39Yocto Project Metadata and runs the tasks defined by that data. Failures
40are usually caused by errors in your Metadata and not from BitBake
William A. Kennington IIIac69b482021-06-02 12:28:27 -070041itself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050042
43When you run the ``bitbake`` command, the main BitBake executable (which
44resides in the ``bitbake/bin/`` directory) starts. Sourcing the
45environment setup script (i.e. :ref:`structure-core-script`) places
46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
47the shell's ``PATH`` environment variable.
48
49For more information on BitBake, see the :doc:`BitBake User Manual
50<bitbake:index>`.
51
52.. _structure-core-build:
53
54``build/``
55----------
56
57This directory contains user configuration files and the output
58generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source``
61the OpenEmbedded build environment setup script (i.e.
62:ref:`structure-core-script`).
63
64It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by
66providing a directory name when you ``source`` the setup script. For
67information on separating output from your local Source Directory files
68(commonly described as an "out of tree" build), see the
69":ref:`structure-core-script`" section.
70
Andrew Geissler87f5cff2022-09-30 13:13:31 -050071See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details
72about the contents of the :term:`Build Directory`.
73
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074.. _handbook:
75
76``documentation/``
77------------------
78
79This directory holds the source for the Yocto Project documentation as
80well as templates and tools that allow you to generate PDF and HTML
81versions of the manuals. Each manual is contained in its own sub-folder;
82for example, the files for this reference manual reside in the
83``ref-manual/`` directory.
84
85.. _structure-core-meta:
86
87``meta/``
88---------
89
90This directory contains the minimal, underlying OpenEmbedded-Core
91metadata. The directory holds recipes, common classes, and machine
92configuration for strictly emulated targets (``qemux86``, ``qemuarm``,
93and so forth.)
94
95.. _structure-core-meta-poky:
96
97``meta-poky/``
98--------------
99
100Designed above the ``meta/`` content, this directory adds just enough
101metadata to define the Poky reference distribution.
102
103.. _structure-core-meta-yocto-bsp:
104
105``meta-yocto-bsp/``
106-------------------
107
108This directory contains the Yocto Project reference hardware Board
109Support Packages (BSPs). For more information on BSPs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600110:doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500111
112.. _structure-meta-selftest:
113
114``meta-selftest/``
115------------------
116
117This directory adds additional recipes and append files used by the
118OpenEmbedded selftests to verify the behavior of the build system. You
119do not have to add this layer to your ``bblayers.conf`` file unless you
120want to run the selftests.
121
122.. _structure-meta-skeleton:
123
124``meta-skeleton/``
125------------------
126
127This directory contains template recipes for BSP and kernel development.
128
129.. _structure-core-scripts:
130
131``scripts/``
132------------
133
134This directory contains various integration scripts that implement extra
135functionality in the Yocto Project environment (e.g. QEMU scripts). The
136:ref:`structure-core-script` script prepends this directory to the
137shell's ``PATH`` environment variable.
138
139The ``scripts`` directory has useful scripts that assist in contributing
140back to the Yocto Project, such as ``create-pull-request`` and
141``send-pull-request``.
142
143.. _structure-core-script:
144
145``oe-init-build-env``
146---------------------
147
148This script sets up the OpenEmbedded build environment. Running this
149script with the ``source`` command in a shell makes changes to ``PATH``
150and sets other core BitBake variables based on the current working
151directory. You need to run an environment setup script before running
152BitBake commands. The script uses other scripts within the ``scripts``
153directory to do the bulk of the work.
154
155When you run this script, your Yocto Project environment is set up, a
156:term:`Build Directory` is created, your working
157directory becomes the Build Directory, and you are presented with some
158simple suggestions as to what to do next, including a list of some
Andrew Geisslerc926e172021-05-07 16:11:35 -0500159possible targets to build. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160
161 $ source oe-init-build-env
162
163 ### Shell environment set up for builds. ###
164
165 You can now run 'bitbake <target>'
166
167 Common targets are:
168 core-image-minimal
169 core-image-sato
170 meta-toolchain
171 meta-ide-support
172
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500173 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500174
175The default output of the ``oe-init-build-env`` script is from the
176``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
177within the :term:`Source Directory`. If you design a
178custom distribution, you can include your own version of this
179configuration file to mention the targets defined by your distribution.
180See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600181":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182section in the Yocto Project Development Tasks Manual for more
183information.
184
185By default, running this script without a Build Directory argument
186creates the ``build/`` directory in your current working directory. If
187you provide a Build Directory argument when you ``source`` the script,
188you direct the OpenEmbedded build system to create a Build Directory of
189your choice. For example, the following command creates a Build
Andrew Geisslerc926e172021-05-07 16:11:35 -0500190Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500192 $ source oe-init-build-env ~/mybuilds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193
194The OpenEmbedded build system uses the template configuration files, which
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500195are found by default in the ``meta-poky/conf/templates/default`` directory in the Source
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196Directory. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600197":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198section in the Yocto Project Development Tasks Manual for more
199information.
200
201.. note::
202
203 The OpenEmbedded build system does not support file or directory
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500204 names that contain spaces. If you attempt to run the ``oe-init-build-env``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205 script from a Source Directory that contains spaces in either the
206 filenames or directory names, the script returns an error indicating
207 no such file or directory. Be sure to use a Source Directory free of
208 names containing spaces.
209
210.. _structure-basic-top-level:
211
212``LICENSE, README, and README.hardware``
213----------------------------------------
214
215These files are standard top-level files.
216
217.. _structure-build:
218
Andrew Geissler615f2f12022-07-15 14:00:58 -0500219The Build Directory --- ``build/``
220==================================
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
222The OpenEmbedded build system creates the :term:`Build Directory`
223when you run the build environment setup
224script :ref:`structure-core-script`. If you do not give the Build
225Directory a specific name when you run the setup script, the name
226defaults to ``build/``.
227
228For subsequent parsing and processing, the name of the Build directory
229is available via the :term:`TOPDIR` variable.
230
231.. _structure-build-buildhistory:
232
233``build/buildhistory/``
234-----------------------
235
236The OpenEmbedded build system creates this directory when you enable
Andrew Geissler595f6302022-01-24 19:11:47 +0000237build history via the :ref:`buildhistory <ref-classes-buildhistory>` class file. The directory
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238organizes build information into image, packages, and SDK
239subdirectories. For information on the build history feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600240":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500241section in the Yocto Project Development Tasks Manual.
242
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500243.. _structure-build-cache:
244
245``build/cache/``
246----------------
247
248This directory contains several internal files used by the OpenEmbedded
249build system.
250
251It also contains ``sanity_info``, a text file keeping track of important
252build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`,
253as well as the name and version of the host distribution.
254
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255.. _structure-build-conf-local.conf:
256
257``build/conf/local.conf``
258-------------------------
259
260This configuration file contains all the local user configurations for
261your build environment. The ``local.conf`` file contains documentation
262on the various configuration options. Any variable set here overrides
263any variable set elsewhere within the environment unless that variable
264is hard-coded within a file (e.g. by using '=' instead of '?='). Some
265variables are hard-coded for various reasons but such variables are
266relatively rare.
267
268At a minimum, you would normally edit this file to select the target
Andrew Geissler09036742021-06-25 14:25:14 -0500269:term:`MACHINE`, which package types you wish to use
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500270(:term:`PACKAGE_CLASSES`), and the location from
Andrew Geissler09036742021-06-25 14:25:14 -0500271which you want to access downloaded files (:term:`DL_DIR`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500272
273If ``local.conf`` is not present when you start the build, the
274OpenEmbedded build system creates it from ``local.conf.sample`` when you
275``source`` the top-level build environment setup script
276:ref:`structure-core-script`.
277
278The source ``local.conf.sample`` file used depends on the
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500279:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280when you are building from the Yocto Project development environment,
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500281and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282environment. Because the script variable points to the source of the
283``local.conf.sample`` file, this implies that you can configure your
284build environment from any layer by setting the variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500285top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500286
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500287 TEMPLATECONF=your_layer/conf/templates/your_template_name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288
289Once the build process gets the sample
290file, it uses ``sed`` to substitute final
291``${``\ :term:`OEROOT`\ ``}`` values for all
292``##OEROOT##`` values.
293
294.. note::
295
Andrew Geisslerd5838332022-05-27 11:33:10 -0500296 You can see how the :term:`TEMPLATECONF` variable is used by looking at the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700297 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500298 You can find the Yocto Project version of the ``local.conf.sample`` file in
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500299 the ``meta-poky/conf/templates/default`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500300
301.. _structure-build-conf-bblayers.conf:
302
303``build/conf/bblayers.conf``
304----------------------------
305
306This configuration file defines
Andrew Geissler09209ee2020-12-13 08:44:15 -0600307:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500308which are directory trees, traversed (or walked) by BitBake. The
309``bblayers.conf`` file uses the :term:`BBLAYERS`
310variable to list the layers BitBake tries to find.
311
312If ``bblayers.conf`` is not present when you start the build, the
313OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
314you ``source`` the top-level build environment setup script (i.e.
315:ref:`structure-core-script`).
316
317As with the ``local.conf`` file, the source ``bblayers.conf.sample``
Andrew Geisslerd5838332022-05-27 11:33:10 -0500318file used depends on the :term:`TEMPLATECONF` script variable, which
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500319defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto
320Project development environment, and to ``meta/conf/templates/default`` when you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500321building from the OpenEmbedded-Core environment. Because the script
322variable points to the source of the ``bblayers.conf.sample`` file, this
323implies that you can base your build from any layer by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500324variable in the top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500326 TEMPLATECONF=your_layer/conf/templates/your_template_name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327
328Once the build process gets the sample file, it uses ``sed`` to substitute final
329``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
330
331.. note::
332
Andrew Geisslerd5838332022-05-27 11:33:10 -0500333 You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir``
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500334 script in the :term:`Source Directory`. You can find the Yocto Project
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500335 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500336 directory.
337
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500338.. _structure-build-downloads:
339
340``build/downloads/``
341--------------------
342
343This directory contains downloaded upstream source tarballs. You can
344reuse the directory for multiple builds or move the directory to another
345location. You can control the location of this directory through the
Andrew Geissler09036742021-06-25 14:25:14 -0500346:term:`DL_DIR` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347
348.. _structure-build-sstate-cache:
349
350``build/sstate-cache/``
351-----------------------
352
353This directory contains the shared state cache. You can reuse the
354directory for multiple builds or move the directory to another location.
355You can control the location of this directory through the
Andrew Geissler09036742021-06-25 14:25:14 -0500356:term:`SSTATE_DIR` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500357
358.. _structure-build-tmp:
359
360``build/tmp/``
361--------------
362
363The OpenEmbedded build system creates and uses this directory for all
364the build system's output. The :term:`TMPDIR` variable
365points to this directory.
366
367BitBake creates this directory if it does not exist. As a last resort,
368to clean up a build and start it from scratch (other than the
369downloads), you can remove everything in the ``tmp`` directory or get
370rid of the directory completely. If you do, you should also completely
371remove the ``build/sstate-cache`` directory.
372
373.. _structure-build-tmp-buildstats:
374
375``build/tmp/buildstats/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500376~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377
378This directory stores the build statistics.
379
380.. _structure-build-tmp-cache:
381
382``build/tmp/cache/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500383~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500384
385When BitBake parses the metadata (recipes and configuration files), it
386caches the results in ``build/tmp/cache/`` to speed up future builds.
387The results are stored on a per-machine basis.
388
389During subsequent builds, BitBake checks each recipe (together with, for
390example, any files included or appended to it) to see if they have been
391modified. Changes can be detected, for example, through file
392modification time (mtime) changes and hashing of file contents. If no
393changes to the file are detected, then the parsed result stored in the
394cache is reused. If the file has changed, it is reparsed.
395
396.. _structure-build-tmp-deploy:
397
398``build/tmp/deploy/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500399~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500400
401This directory contains any "end result" output from the OpenEmbedded
402build process. The :term:`DEPLOY_DIR` variable points
403to this directory. For more detail on the contents of the ``deploy``
404directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600405":ref:`overview-manual/concepts:images`" and
406":ref:`overview-manual/concepts:application development sdk`" sections in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500407Project Overview and Concepts Manual.
408
409.. _structure-build-tmp-deploy-deb:
410
411``build/tmp/deploy/deb/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500412^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500413
414This directory receives any ``.deb`` packages produced by the build
415process. The packages are sorted into feeds for different architecture
416types.
417
418.. _structure-build-tmp-deploy-rpm:
419
420``build/tmp/deploy/rpm/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500421^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500422
423This directory receives any ``.rpm`` packages produced by the build
424process. The packages are sorted into feeds for different architecture
425types.
426
427.. _structure-build-tmp-deploy-ipk:
428
429``build/tmp/deploy/ipk/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500430^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500431
432This directory receives ``.ipk`` packages produced by the build process.
433
434.. _structure-build-tmp-deploy-licenses:
435
436``build/tmp/deploy/licenses/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500437^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500438
439This directory receives package licensing information. For example, the
440directory contains sub-directories for ``bash``, ``busybox``, and
441``glibc`` (among others) that in turn contain appropriate ``COPYING``
442license files with other licensing information. For information on
443licensing, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600444":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445section in the Yocto Project Development Tasks Manual.
446
447.. _structure-build-tmp-deploy-images:
448
449``build/tmp/deploy/images/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500450^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500451
452This directory is populated with the basic output objects of the build
453(think of them as the "generated artifacts" of the build process),
454including things like the boot loader image, kernel, root filesystem and
455more. If you want to flash the resulting image from a build onto a
456device, look here for the necessary components.
457
458Be careful when deleting files in this directory. You can safely delete
459old images from this directory (e.g. ``core-image-*``). However, the
460kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other
461supplementary files might be deployed here prior to building an image.
462Because these files are not directly produced from the image, if you
463delete them they will not be automatically re-created when you build the
464image again.
465
466If you do accidentally delete files here, you will need to force them to
467be re-created. In order to do that, you will need to know the target
468that produced them. For example, these commands rebuild and re-create
Andrew Geisslerc926e172021-05-07 16:11:35 -0500469the kernel files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500470
471 $ bitbake -c clean virtual/kernel
472 $ bitbake virtual/kernel
473
474.. _structure-build-tmp-deploy-sdk:
475
476``build/tmp/deploy/sdk/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500477^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500478
479The OpenEmbedded build system creates this directory to hold toolchain
480installer scripts which, when executed, install the sysroot that matches
481your target hardware. You can find out more about these installers in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600482the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500483section in the Yocto Project Application Development and the Extensible
484Software Development Kit (eSDK) manual.
485
486.. _structure-build-tmp-sstate-control:
487
488``build/tmp/sstate-control/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500489~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500490
491The OpenEmbedded build system uses this directory for the shared state
492manifest files. The shared state code uses these files to record the
493files installed by each sstate task so that the files can be removed
494when cleaning the recipe or when a newer version is about to be
495installed. The build system also uses the manifests to detect and
496produce a warning when files from one task are overwriting those from
497another.
498
499.. _structure-build-tmp-sysroots-components:
500
501``build/tmp/sysroots-components/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500502~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503
504This directory is the location of the sysroot contents that the task
505:ref:`ref-tasks-prepare_recipe_sysroot`
506links or copies into the recipe-specific sysroot for each recipe listed
507in :term:`DEPENDS`. Population of this directory is
508handled through shared state, while the path is specified by the
509:term:`COMPONENTS_DIR` variable. Apart from a few
510unusual circumstances, handling of the ``sysroots-components`` directory
511should be automatic, and recipes should not directly reference
512``build/tmp/sysroots-components``.
513
514.. _structure-build-tmp-sysroots:
515
516``build/tmp/sysroots/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500517~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500518
519Previous versions of the OpenEmbedded build system used to create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700520global shared sysroot per machine along with a native sysroot. Since
521the 2.3 version of the Yocto Project, there are sysroots in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500522recipe-specific :term:`WORKDIR` directories. Thus, the
523``build/tmp/sysroots/`` directory is unused.
524
525.. note::
526
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500527 The ``build/tmp/sysroots/`` directory can still be populated using the
528 ``bitbake build-sysroots`` command and can be used for compatibility in some
529 cases. However, in general it is not recommended to populate this directory.
530 Individual recipe-specific sysroots should be used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500531
532.. _structure-build-tmp-stamps:
533
534``build/tmp/stamps/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500535~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500536
537This directory holds information that BitBake uses for accounting
538purposes to track what tasks have run and when they have run. The
539directory is sub-divided by architecture, package name, and version.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500540Following is an example::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500541
542 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
543
544Although the files in the directory are empty of data, BitBake uses the filenames
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500545and timestamps for tracking purposes.
546
547For information on how BitBake uses stamp files to determine if a task
548should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600549":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500550section in the Yocto Project Overview and Concepts Manual.
551
552.. _structure-build-tmp-log:
553
554``build/tmp/log/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500555~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500556
557This directory contains general logs that are not otherwise placed using
Andrew Geissler09036742021-06-25 14:25:14 -0500558the package's :term:`WORKDIR`. Examples of logs are the output from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
560necessarily mean this directory is created.
561
562.. _structure-build-tmp-work:
563
564``build/tmp/work/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500565~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500566
567This directory contains architecture-specific work sub-directories for
568packages built by BitBake. All tasks execute from the appropriate work
569directory. For example, the source for a particular package is unpacked,
570patched, configured and compiled all within its own work directory.
571Within the work directory, organization is based on the package group
572and version for which the source is being compiled as defined by the
573:term:`WORKDIR`.
574
575It is worth considering the structure of a typical work directory. As an
576example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
577built within the Yocto Project. For this package, a work directory of
578``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
Andrew Geissler09036742021-06-25 14:25:14 -0500579to as the :term:`WORKDIR`, is created. Within this directory, the source is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500580unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600581(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500582the Yocto Project Development Tasks Manual for more information.) Within
583the ``linux-qemux86-standard-build`` directory, standard Quilt
584directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
585standard Quilt commands can be used.
586
Andrew Geissler09036742021-06-25 14:25:14 -0500587There are other directories generated within :term:`WORKDIR`. The most
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500588important directory is ``WORKDIR/temp/``, which has log files for each
589task (``log.do_*.pid``) and contains the scripts BitBake runs for each
590task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
591install" places its output that is then split into sub-packages within
592``WORKDIR/packages-split/``.
593
594.. _structure-build-tmp-work-tunearch-recipename-version:
595
596``build/tmp/work/tunearch/recipename/version/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500597^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500598
Andrew Geissler615f2f12022-07-15 14:00:58 -0500599The recipe work directory --- ``${WORKDIR}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500600
601As described earlier in the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500602":ref:`structure-build-tmp-sysroots`" section,
603beginning with the 2.3 release of the Yocto Project, the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500604build system builds each recipe in its own work directory (i.e.
605:term:`WORKDIR`). The path to the work directory is
606constructed using the architecture of the given build (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500607:term:`TUNE_PKGARCH`, :term:`MACHINE_ARCH`, or "allarch"), the recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500608name, and the version of the recipe (i.e.
609:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
610
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700611Here are key subdirectories within each recipe work directory:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500612
613- ``${WORKDIR}/temp``: Contains the log files of each task executed for
614 this recipe, the "run" files for each executed task, which contain
615 the code run, and a ``log.task_order`` file, which lists the order in
616 which tasks were executed.
617
618- ``${WORKDIR}/image``: Contains the output of the
619 :ref:`ref-tasks-install` task, which corresponds to
620 the ``${``\ :term:`D`\ ``}`` variable in that task.
621
622- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any
623 tasks executed under pseudo for the recipe.
624
625- ``${WORKDIR}/sysroot-destdir``: Contains the output of the
626 :ref:`ref-tasks-populate_sysroot` task.
627
628- ``${WORKDIR}/package``: Contains the output of the
629 :ref:`ref-tasks-package` task before the output is
630 split into individual packages.
631
632- ``${WORKDIR}/packages-split``: Contains the output of the
633 ``do_package`` task after the output has been split into individual
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700634 packages. There are subdirectories for each individual package created by
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500635 the recipe.
636
637- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
638 dependencies of the recipe. This directory looks like the target
639 filesystem and contains libraries that the recipe might need to link
640 against (e.g. the C library).
641
642- ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the
643 native dependencies of the recipe. This directory contains the tools
644 the recipe needs to build (e.g. the compiler, Autoconf, libtool, and
645 so forth).
646
647- ``${WORKDIR}/build``: This subdirectory applies only to recipes that
648 support builds where the source is separate from the build artifacts.
649 The OpenEmbedded build system uses this directory as a separate build
650 directory (i.e. ``${``\ :term:`B`\ ``}``).
651
652.. _structure-build-work-shared:
653
654``build/tmp/work-shared/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500655~~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500656
657For efficiency, the OpenEmbedded build system creates and uses this
658directory to hold recipes that share a work directory with other
659recipes. In practice, this is only used for ``gcc`` and its variants
660(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth).
661
662.. _structure-meta:
663
Andrew Geissler615f2f12022-07-15 14:00:58 -0500664The Metadata --- ``meta/``
665==========================
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500666
667As mentioned previously, :term:`Metadata` is the core of the
668Yocto Project. Metadata has several important subdivisions:
669
670.. _structure-meta-classes:
671
672``meta/classes/``
673-----------------
674
675This directory contains the ``*.bbclass`` files. Class files are used to
676abstract common code so it can be reused by multiple packages. Every
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000677package inherits the :ref:`ref-classes-base` file. Examples of other important
678classes are :ref:`ref-classes-autotools`, which in theory allows any
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500679Autotool-enabled package to work with the Yocto Project with minimal
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000680effort. Another example is :ref:`ref-classes-kernel` that contains common code
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500681and functions for working with the Linux kernel. Functions like image
682generation or packaging also have their specific class files such as
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000683:ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and
684:ref:`package*.bbclass <ref-classes-package>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500685
686For reference information on classes, see the
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000687":doc:`/ref-manual/classes`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500688
689.. _structure-meta-conf:
690
691``meta/conf/``
692--------------
693
694This directory contains the core set of configuration files that start
695from ``bitbake.conf`` and from which all other configuration files are
696included. See the include statements at the end of the ``bitbake.conf``
697file and you will note that even ``local.conf`` is loaded from there.
698While ``bitbake.conf`` sets up the defaults, you can often override
699these by using the (``local.conf``) file, machine file or the
700distribution configuration file.
701
702.. _structure-meta-conf-machine:
703
704``meta/conf/machine/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500705~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500706
707This directory contains all the machine configuration files. If you set
708``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a
709``qemux86.conf`` file in this directory. The ``include`` directory
710contains various data common to multiple machines. If you want to add
711support for a new machine to the Yocto Project, look in this directory.
712
713.. _structure-meta-conf-distro:
714
715``meta/conf/distro/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500716~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500717
718The contents of this directory controls any distribution-specific
719configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
Andrew Geissler09036742021-06-25 14:25:14 -0500720main file here. This directory includes the versions and the :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500721definitions for applications that are configured here. An example of an
722alternative configuration might be ``poky-bleeding.conf``. Although this
723file mainly inherits its configuration from Poky.
724
725.. _structure-meta-conf-machine-sdk:
726
727``meta/conf/machine-sdk/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500728~~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500729
730The OpenEmbedded build system searches this directory for configuration
731files that correspond to the value of
732:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86
733files ship with the Yocto Project that support some SDK hosts. However,
734it is possible to extend that support to other SDK hosts by adding
735additional configuration files in this subdirectory within another
736layer.
737
738.. _structure-meta-files:
739
740``meta/files/``
741---------------
742
743This directory contains common license files and several text files used
744by the build system. The text files contain minimal device information
745and lists of files and directories with known permissions.
746
747.. _structure-meta-lib:
748
749``meta/lib/``
750-------------
751
752This directory contains OpenEmbedded Python library code used during the
753build process.
754
755.. _structure-meta-recipes-bsp:
756
757``meta/recipes-bsp/``
758---------------------
759
760This directory contains anything linking to specific hardware or
761hardware configuration information such as "u-boot" and "grub".
762
763.. _structure-meta-recipes-connectivity:
764
765``meta/recipes-connectivity/``
766------------------------------
767
768This directory contains libraries and applications related to
769communication with other devices.
770
771.. _structure-meta-recipes-core:
772
773``meta/recipes-core/``
774----------------------
775
776This directory contains what is needed to build a basic working Linux
777image including commonly used dependencies.
778
779.. _structure-meta-recipes-devtools:
780
781``meta/recipes-devtools/``
782--------------------------
783
784This directory contains tools that are primarily used by the build
785system. The tools, however, can also be used on targets.
786
787.. _structure-meta-recipes-extended:
788
789``meta/recipes-extended/``
790--------------------------
791
792This directory contains non-essential applications that add features
793compared to the alternatives in core. You might need this directory for
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700794full tool functionality.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500795
796.. _structure-meta-recipes-gnome:
797
798``meta/recipes-gnome/``
799-----------------------
800
801This directory contains all things related to the GTK+ application
802framework.
803
804.. _structure-meta-recipes-graphics:
805
806``meta/recipes-graphics/``
807--------------------------
808
809This directory contains X and other graphically related system
810libraries.
811
812.. _structure-meta-recipes-kernel:
813
814``meta/recipes-kernel/``
815------------------------
816
817This directory contains the kernel and generic applications and
818libraries that have strong kernel dependencies.
819
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500820.. _structure-meta-recipes-multimedia:
821
822``meta/recipes-multimedia/``
823----------------------------
824
825This directory contains codecs and support utilities for audio, images
826and video.
827
828.. _structure-meta-recipes-rt:
829
830``meta/recipes-rt/``
831--------------------
832
833This directory contains package and image recipes for using and testing
834the ``PREEMPT_RT`` kernel.
835
836.. _structure-meta-recipes-sato:
837
838``meta/recipes-sato/``
839----------------------
840
841This directory contains the Sato demo/reference UI/UX and its associated
842applications and configuration data.
843
844.. _structure-meta-recipes-support:
845
846``meta/recipes-support/``
847-------------------------
848
849This directory contains recipes used by other recipes, but that are not
850directly included in images (i.e. dependencies of other recipes).
851
852.. _structure-meta-site:
853
854``meta/site/``
855--------------
856
857This directory contains a list of cached results for various
858architectures. Because certain "autoconf" test results cannot be
859determined when cross-compiling due to the tests not able to run on a
860live system, the information in this directory is passed to "autoconf"
861for the various architectures.
862
863.. _structure-meta-recipes-txt:
864
865``meta/recipes.txt``
866--------------------
867
868This file is a description of the contents of ``recipes-*``.