blob: f1b11ad69b7ae7a5df5a9e7a1ec6ce3f0658630f [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`
Patrick Williams2390b1b2022-11-03 13:47:49 -050060is created initially when you ``source`` the OpenEmbedded build environment
61setup script (i.e. :ref:`structure-core-script`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062
63It is also possible to place output and configuration files in a
64directory separate from the :term:`Source Directory` by
65providing a directory name when you ``source`` the setup script. For
66information on separating output from your local Source Directory files
67(commonly described as an "out of tree" build), see the
68":ref:`structure-core-script`" section.
69
Andrew Geissler87f5cff2022-09-30 13:13:31 -050070See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details
71about the contents of the :term:`Build Directory`.
72
Andrew Geisslerc9f78652020-09-18 14:11:35 -050073.. _handbook:
74
75``documentation/``
76------------------
77
78This directory holds the source for the Yocto Project documentation as
79well as templates and tools that allow you to generate PDF and HTML
80versions of the manuals. Each manual is contained in its own sub-folder;
81for example, the files for this reference manual reside in the
82``ref-manual/`` directory.
83
84.. _structure-core-meta:
85
86``meta/``
87---------
88
89This directory contains the minimal, underlying OpenEmbedded-Core
90metadata. The directory holds recipes, common classes, and machine
91configuration for strictly emulated targets (``qemux86``, ``qemuarm``,
92and so forth.)
93
94.. _structure-core-meta-poky:
95
96``meta-poky/``
97--------------
98
99Designed above the ``meta/`` content, this directory adds just enough
100metadata to define the Poky reference distribution.
101
102.. _structure-core-meta-yocto-bsp:
103
104``meta-yocto-bsp/``
105-------------------
106
107This directory contains the Yocto Project reference hardware Board
108Support Packages (BSPs). For more information on BSPs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600109:doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110
111.. _structure-meta-selftest:
112
113``meta-selftest/``
114------------------
115
116This directory adds additional recipes and append files used by the
117OpenEmbedded selftests to verify the behavior of the build system. You
118do not have to add this layer to your ``bblayers.conf`` file unless you
119want to run the selftests.
120
121.. _structure-meta-skeleton:
122
123``meta-skeleton/``
124------------------
125
126This directory contains template recipes for BSP and kernel development.
127
128.. _structure-core-scripts:
129
130``scripts/``
131------------
132
133This directory contains various integration scripts that implement extra
134functionality in the Yocto Project environment (e.g. QEMU scripts). The
135:ref:`structure-core-script` script prepends this directory to the
136shell's ``PATH`` environment variable.
137
138The ``scripts`` directory has useful scripts that assist in contributing
139back to the Yocto Project, such as ``create-pull-request`` and
140``send-pull-request``.
141
142.. _structure-core-script:
143
144``oe-init-build-env``
145---------------------
146
147This script sets up the OpenEmbedded build environment. Running this
148script with the ``source`` command in a shell makes changes to ``PATH``
149and sets other core BitBake variables based on the current working
150directory. You need to run an environment setup script before running
151BitBake commands. The script uses other scripts within the ``scripts``
152directory to do the bulk of the work.
153
154When you run this script, your Yocto Project environment is set up, a
Patrick Williams2390b1b2022-11-03 13:47:49 -0500155:term:`Build Directory` is created, your working directory becomes the
156:term:`Build Directory`, and you are presented with some simple
157suggestions as to what to do next, including a list of some possible
158targets to build. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159
160 $ source oe-init-build-env
161
162 ### Shell environment set up for builds. ###
163
164 You can now run 'bitbake <target>'
165
166 Common targets are:
167 core-image-minimal
168 core-image-sato
169 meta-toolchain
170 meta-ide-support
171
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500172 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
174The default output of the ``oe-init-build-env`` script is from the
175``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
176within the :term:`Source Directory`. If you design a
177custom distribution, you can include your own version of this
178configuration file to mention the targets defined by your distribution.
179See the
Andrew Geissler517393d2023-01-13 08:55:19 -0600180":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181section in the Yocto Project Development Tasks Manual for more
182information.
183
Patrick Williams2390b1b2022-11-03 13:47:49 -0500184By default, running this script without a :term:`Build Directory` argument
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500185creates the ``build/`` directory in your current working directory. If
Patrick Williams2390b1b2022-11-03 13:47:49 -0500186you provide a :term:`Build Directory` argument when you ``source`` the script,
187you direct the OpenEmbedded build system to create a :term:`Build Directory` of
188your choice. For example, the following command creates a
189:term:`Build Directory` named ``mybuilds/`` that is outside of the
190: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 Geissler517393d2023-01-13 08:55:19 -0600197":ref:`dev-manual/custom-template-configuration-directory: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
Patrick Williams2390b1b2022-11-03 13:47:49 -0500222The OpenEmbedded build system creates the :term:`Build Directory` when you run
223the build environment setup script :ref:`structure-core-script`. If you do not
224give the :term:`Build Directory` a specific name when you run the setup script,
225the name defaults to ``build/``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500226
227For subsequent parsing and processing, the name of the Build directory
228is available via the :term:`TOPDIR` variable.
229
230.. _structure-build-buildhistory:
231
232``build/buildhistory/``
233-----------------------
234
235The OpenEmbedded build system creates this directory when you enable
Andrew Geissler517393d2023-01-13 08:55:19 -0600236build history via the :ref:`ref-classes-buildhistory` class file. The directory
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500237organizes build information into image, packages, and SDK
238subdirectories. For information on the build history feature, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600239":ref:`dev-manual/build-quality:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500240section in the Yocto Project Development Tasks Manual.
241
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500242.. _structure-build-cache:
243
244``build/cache/``
245----------------
246
247This directory contains several internal files used by the OpenEmbedded
248build system.
249
250It also contains ``sanity_info``, a text file keeping track of important
251build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`,
252as well as the name and version of the host distribution.
253
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254.. _structure-build-conf-local.conf:
255
256``build/conf/local.conf``
257-------------------------
258
259This configuration file contains all the local user configurations for
260your build environment. The ``local.conf`` file contains documentation
261on the various configuration options. Any variable set here overrides
262any variable set elsewhere within the environment unless that variable
263is hard-coded within a file (e.g. by using '=' instead of '?='). Some
264variables are hard-coded for various reasons but such variables are
265relatively rare.
266
267At a minimum, you would normally edit this file to select the target
Andrew Geissler09036742021-06-25 14:25:14 -0500268:term:`MACHINE`, which package types you wish to use
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269(:term:`PACKAGE_CLASSES`), and the location from
Andrew Geissler09036742021-06-25 14:25:14 -0500270which you want to access downloaded files (:term:`DL_DIR`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
272If ``local.conf`` is not present when you start the build, the
273OpenEmbedded build system creates it from ``local.conf.sample`` when you
274``source`` the top-level build environment setup script
275:ref:`structure-core-script`.
276
277The source ``local.conf.sample`` file used depends on the
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500278:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279when you are building from the Yocto Project development environment,
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500280and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500281environment. Because the script variable points to the source of the
282``local.conf.sample`` file, this implies that you can configure your
283build environment from any layer by setting the variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500284top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500286 TEMPLATECONF=your_layer/conf/templates/your_template_name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287
288Once the build process gets the sample
289file, it uses ``sed`` to substitute final
290``${``\ :term:`OEROOT`\ ``}`` values for all
291``##OEROOT##`` values.
292
293.. note::
294
Andrew Geisslerd5838332022-05-27 11:33:10 -0500295 You can see how the :term:`TEMPLATECONF` variable is used by looking at the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700296 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500297 You can find the Yocto Project version of the ``local.conf.sample`` file in
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500298 the ``meta-poky/conf/templates/default`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500299
300.. _structure-build-conf-bblayers.conf:
301
302``build/conf/bblayers.conf``
303----------------------------
304
305This configuration file defines
Andrew Geissler517393d2023-01-13 08:55:19 -0600306:ref:`layers <dev-manual/layers:understanding and creating layers>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307which are directory trees, traversed (or walked) by BitBake. The
308``bblayers.conf`` file uses the :term:`BBLAYERS`
309variable to list the layers BitBake tries to find.
310
311If ``bblayers.conf`` is not present when you start the build, the
312OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
313you ``source`` the top-level build environment setup script (i.e.
314:ref:`structure-core-script`).
315
316As with the ``local.conf`` file, the source ``bblayers.conf.sample``
Andrew Geisslerd5838332022-05-27 11:33:10 -0500317file used depends on the :term:`TEMPLATECONF` script variable, which
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500318defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto
319Project development environment, and to ``meta/conf/templates/default`` when you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500320building from the OpenEmbedded-Core environment. Because the script
321variable points to the source of the ``bblayers.conf.sample`` file, this
322implies that you can base your build from any layer by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500323variable in the top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500324
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500325 TEMPLATECONF=your_layer/conf/templates/your_template_name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500326
327Once the build process gets the sample file, it uses ``sed`` to substitute final
328``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
329
330.. note::
331
Andrew Geisslerd5838332022-05-27 11:33:10 -0500332 You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir``
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500333 script in the :term:`Source Directory`. You can find the Yocto Project
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500334 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500335 directory.
336
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500337.. _structure-build-downloads:
338
339``build/downloads/``
340--------------------
341
342This directory contains downloaded upstream source tarballs. You can
343reuse the directory for multiple builds or move the directory to another
344location. You can control the location of this directory through the
Andrew Geissler09036742021-06-25 14:25:14 -0500345:term:`DL_DIR` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500346
347.. _structure-build-sstate-cache:
348
349``build/sstate-cache/``
350-----------------------
351
352This directory contains the shared state cache. You can reuse the
353directory for multiple builds or move the directory to another location.
354You can control the location of this directory through the
Andrew Geissler09036742021-06-25 14:25:14 -0500355:term:`SSTATE_DIR` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356
357.. _structure-build-tmp:
358
359``build/tmp/``
360--------------
361
362The OpenEmbedded build system creates and uses this directory for all
363the build system's output. The :term:`TMPDIR` variable
364points to this directory.
365
366BitBake creates this directory if it does not exist. As a last resort,
367to clean up a build and start it from scratch (other than the
368downloads), you can remove everything in the ``tmp`` directory or get
369rid of the directory completely. If you do, you should also completely
370remove the ``build/sstate-cache`` directory.
371
372.. _structure-build-tmp-buildstats:
373
374``build/tmp/buildstats/``
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500375~~~~~~~~~~~~~~~~~~~~~~~~~
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500376
Andrew Geissler517393d2023-01-13 08:55:19 -0600377This directory stores the build statistics as generated by the
378:ref:`ref-classes-buildstats` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500379
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 Geissler517393d2023-01-13 08:55:19 -0600444":ref:`dev-manual/licenses: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 Geissler517393d2023-01-13 08:55:19 -0600581(See the ":ref:`dev-manual/quilt: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
Patrick Williams2194f502022-10-16 14:26:09 -0500633 :ref:`ref-tasks-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
Patrick Williams975a06f2022-10-21 14:42:47 -0500672``meta/classes*/``
673------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500674
Patrick Williams975a06f2022-10-21 14:42:47 -0500675These directories contain the ``*.bbclass`` files. Class files are used to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500676abstract 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
Patrick Williams8e7b46e2023-05-01 14:19:06 -0500753build process. It is enabled via the ``addpylib`` directive in
754``meta/conf/local.conf``. For more information, see
755:ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500756
757.. _structure-meta-recipes-bsp:
758
759``meta/recipes-bsp/``
760---------------------
761
762This directory contains anything linking to specific hardware or
763hardware configuration information such as "u-boot" and "grub".
764
765.. _structure-meta-recipes-connectivity:
766
767``meta/recipes-connectivity/``
768------------------------------
769
770This directory contains libraries and applications related to
771communication with other devices.
772
773.. _structure-meta-recipes-core:
774
775``meta/recipes-core/``
776----------------------
777
778This directory contains what is needed to build a basic working Linux
779image including commonly used dependencies.
780
781.. _structure-meta-recipes-devtools:
782
783``meta/recipes-devtools/``
784--------------------------
785
786This directory contains tools that are primarily used by the build
787system. The tools, however, can also be used on targets.
788
789.. _structure-meta-recipes-extended:
790
791``meta/recipes-extended/``
792--------------------------
793
794This directory contains non-essential applications that add features
795compared to the alternatives in core. You might need this directory for
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700796full tool functionality.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500797
798.. _structure-meta-recipes-gnome:
799
800``meta/recipes-gnome/``
801-----------------------
802
803This directory contains all things related to the GTK+ application
804framework.
805
806.. _structure-meta-recipes-graphics:
807
808``meta/recipes-graphics/``
809--------------------------
810
811This directory contains X and other graphically related system
812libraries.
813
814.. _structure-meta-recipes-kernel:
815
816``meta/recipes-kernel/``
817------------------------
818
819This directory contains the kernel and generic applications and
820libraries that have strong kernel dependencies.
821
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500822.. _structure-meta-recipes-multimedia:
823
824``meta/recipes-multimedia/``
825----------------------------
826
827This directory contains codecs and support utilities for audio, images
828and video.
829
830.. _structure-meta-recipes-rt:
831
832``meta/recipes-rt/``
833--------------------
834
835This directory contains package and image recipes for using and testing
836the ``PREEMPT_RT`` kernel.
837
838.. _structure-meta-recipes-sato:
839
840``meta/recipes-sato/``
841----------------------
842
843This directory contains the Sato demo/reference UI/UX and its associated
844applications and configuration data.
845
846.. _structure-meta-recipes-support:
847
848``meta/recipes-support/``
849-------------------------
850
851This directory contains recipes used by other recipes, but that are not
852directly included in images (i.e. dependencies of other recipes).
853
854.. _structure-meta-site:
855
856``meta/site/``
857--------------
858
859This directory contains a list of cached results for various
860architectures. Because certain "autoconf" test results cannot be
861determined when cross-compiling due to the tests not able to run on a
862live system, the information in this directory is passed to "autoconf"
863for the various architectures.
864
865.. _structure-meta-recipes-txt:
866
867``meta/recipes.txt``
868--------------------
869
870This file is a description of the contents of ``recipes-*``.