blob: ad3f4ab44a0acab26ccb7554696649a9e4e23b79 [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
41itself; consequently, most users do not need to worry about BitBake.
42
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
71.. _handbook:
72
73``documentation/``
74------------------
75
76This directory holds the source for the Yocto Project documentation as
77well as templates and tools that allow you to generate PDF and HTML
78versions of the manuals. Each manual is contained in its own sub-folder;
79for example, the files for this reference manual reside in the
80``ref-manual/`` directory.
81
82.. _structure-core-meta:
83
84``meta/``
85---------
86
87This directory contains the minimal, underlying OpenEmbedded-Core
88metadata. The directory holds recipes, common classes, and machine
89configuration for strictly emulated targets (``qemux86``, ``qemuarm``,
90and so forth.)
91
92.. _structure-core-meta-poky:
93
94``meta-poky/``
95--------------
96
97Designed above the ``meta/`` content, this directory adds just enough
98metadata to define the Poky reference distribution.
99
100.. _structure-core-meta-yocto-bsp:
101
102``meta-yocto-bsp/``
103-------------------
104
105This directory contains the Yocto Project reference hardware Board
106Support Packages (BSPs). For more information on BSPs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600107:doc:`/bsp-guide/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
109.. _structure-meta-selftest:
110
111``meta-selftest/``
112------------------
113
114This directory adds additional recipes and append files used by the
115OpenEmbedded selftests to verify the behavior of the build system. You
116do not have to add this layer to your ``bblayers.conf`` file unless you
117want to run the selftests.
118
119.. _structure-meta-skeleton:
120
121``meta-skeleton/``
122------------------
123
124This directory contains template recipes for BSP and kernel development.
125
126.. _structure-core-scripts:
127
128``scripts/``
129------------
130
131This directory contains various integration scripts that implement extra
132functionality in the Yocto Project environment (e.g. QEMU scripts). The
133:ref:`structure-core-script` script prepends this directory to the
134shell's ``PATH`` environment variable.
135
136The ``scripts`` directory has useful scripts that assist in contributing
137back to the Yocto Project, such as ``create-pull-request`` and
138``send-pull-request``.
139
140.. _structure-core-script:
141
142``oe-init-build-env``
143---------------------
144
145This script sets up the OpenEmbedded build environment. Running this
146script with the ``source`` command in a shell makes changes to ``PATH``
147and sets other core BitBake variables based on the current working
148directory. You need to run an environment setup script before running
149BitBake commands. The script uses other scripts within the ``scripts``
150directory to do the bulk of the work.
151
152When you run this script, your Yocto Project environment is set up, a
153:term:`Build Directory` is created, your working
154directory becomes the Build Directory, and you are presented with some
155simple suggestions as to what to do next, including a list of some
156possible targets to build. Here is an example:
157::
158
159 $ source oe-init-build-env
160
161 ### Shell environment set up for builds. ###
162
163 You can now run 'bitbake <target>'
164
165 Common targets are:
166 core-image-minimal
167 core-image-sato
168 meta-toolchain
169 meta-ide-support
170
171 You can also run generated qemu images with a command like 'runqemu qemux86-64'
172
173The default output of the ``oe-init-build-env`` script is from the
174``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
175within the :term:`Source Directory`. If you design a
176custom distribution, you can include your own version of this
177configuration file to mention the targets defined by your distribution.
178See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600179":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500180section in the Yocto Project Development Tasks Manual for more
181information.
182
183By default, running this script without a Build Directory argument
184creates the ``build/`` directory in your current working directory. If
185you provide a Build Directory argument when you ``source`` the script,
186you direct the OpenEmbedded build system to create a Build Directory of
187your choice. For example, the following command creates a Build
188Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
189::
190
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500191 $ source oe-init-build-env ~/mybuilds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500192
193The OpenEmbedded build system uses the template configuration files, which
194are found by default in the ``meta-poky/conf/`` directory in the Source
195Directory. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600196":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197section in the Yocto Project Development Tasks Manual for more
198information.
199
200.. note::
201
202 The OpenEmbedded build system does not support file or directory
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500203 names that contain spaces. If you attempt to run the ``oe-init-build-env``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500204 script from a Source Directory that contains spaces in either the
205 filenames or directory names, the script returns an error indicating
206 no such file or directory. Be sure to use a Source Directory free of
207 names containing spaces.
208
209.. _structure-basic-top-level:
210
211``LICENSE, README, and README.hardware``
212----------------------------------------
213
214These files are standard top-level files.
215
216.. _structure-build:
217
218The Build Directory - ``build/``
219================================
220
221The OpenEmbedded build system creates the :term:`Build Directory`
222when you run the build environment setup
223script :ref:`structure-core-script`. If you do not give the Build
224Directory a specific name when you run the setup script, the name
225defaults to ``build/``.
226
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
236build history via the ``buildhistory`` class file. The directory
237organizes build information into image, packages, and SDK
238subdirectories. For information on the build history feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600239":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500240section in the Yocto Project Development Tasks Manual.
241
242.. _structure-build-conf-local.conf:
243
244``build/conf/local.conf``
245-------------------------
246
247This configuration file contains all the local user configurations for
248your build environment. The ``local.conf`` file contains documentation
249on the various configuration options. Any variable set here overrides
250any variable set elsewhere within the environment unless that variable
251is hard-coded within a file (e.g. by using '=' instead of '?='). Some
252variables are hard-coded for various reasons but such variables are
253relatively rare.
254
255At a minimum, you would normally edit this file to select the target
256``MACHINE``, which package types you wish to use
257(:term:`PACKAGE_CLASSES`), and the location from
258which you want to access downloaded files (``DL_DIR``).
259
260If ``local.conf`` is not present when you start the build, the
261OpenEmbedded build system creates it from ``local.conf.sample`` when you
262``source`` the top-level build environment setup script
263:ref:`structure-core-script`.
264
265The source ``local.conf.sample`` file used depends on the
266``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
267when you are building from the Yocto Project development environment,
268and to ``meta/conf/`` when you are building from the OpenEmbedded-Core
269environment. Because the script variable points to the source of the
270``local.conf.sample`` file, this implies that you can configure your
271build environment from any layer by setting the variable in the
272top-level build environment setup script as follows:
273::
274
275 TEMPLATECONF=your_layer/conf
276
277Once the build process gets the sample
278file, it uses ``sed`` to substitute final
279``${``\ :term:`OEROOT`\ ``}`` values for all
280``##OEROOT##`` values.
281
282.. note::
283
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500284 You can see how the ``TEMPLATECONF`` variable is used by looking at the
285 ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`.
286 You can find the Yocto Project version of the ``local.conf.sample`` file in
287 the ``meta-poky/conf`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288
289.. _structure-build-conf-bblayers.conf:
290
291``build/conf/bblayers.conf``
292----------------------------
293
294This configuration file defines
Andrew Geissler09209ee2020-12-13 08:44:15 -0600295:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500296which are directory trees, traversed (or walked) by BitBake. The
297``bblayers.conf`` file uses the :term:`BBLAYERS`
298variable to list the layers BitBake tries to find.
299
300If ``bblayers.conf`` is not present when you start the build, the
301OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
302you ``source`` the top-level build environment setup script (i.e.
303:ref:`structure-core-script`).
304
305As with the ``local.conf`` file, the source ``bblayers.conf.sample``
306file used depends on the ``$TEMPLATECONF`` script variable, which
307defaults to ``meta-poky/conf/`` when you are building from the Yocto
308Project development environment, and to ``meta/conf/`` when you are
309building from the OpenEmbedded-Core environment. Because the script
310variable points to the source of the ``bblayers.conf.sample`` file, this
311implies that you can base your build from any layer by setting the
312variable in the top-level build environment setup script as follows:
313::
314
315 TEMPLATECONF=your_layer/conf
316
317Once the build process gets the sample file, it uses ``sed`` to substitute final
318``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
319
320.. note::
321
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500322 You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir``
323 script in the :term:`Source Directory`. You can find the Yocto Project
324 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325 directory.
326
327.. _structure-build-conf-sanity_info:
328
329``build/cache/sanity_info``
330---------------------------
331
332This file indicates the state of the sanity checks and is created during
333the build.
334
335.. _structure-build-downloads:
336
337``build/downloads/``
338--------------------
339
340This directory contains downloaded upstream source tarballs. You can
341reuse the directory for multiple builds or move the directory to another
342location. You can control the location of this directory through the
343``DL_DIR`` variable.
344
345.. _structure-build-sstate-cache:
346
347``build/sstate-cache/``
348-----------------------
349
350This directory contains the shared state cache. You can reuse the
351directory for multiple builds or move the directory to another location.
352You can control the location of this directory through the
353``SSTATE_DIR`` variable.
354
355.. _structure-build-tmp:
356
357``build/tmp/``
358--------------
359
360The OpenEmbedded build system creates and uses this directory for all
361the build system's output. The :term:`TMPDIR` variable
362points to this directory.
363
364BitBake creates this directory if it does not exist. As a last resort,
365to clean up a build and start it from scratch (other than the
366downloads), you can remove everything in the ``tmp`` directory or get
367rid of the directory completely. If you do, you should also completely
368remove the ``build/sstate-cache`` directory.
369
370.. _structure-build-tmp-buildstats:
371
372``build/tmp/buildstats/``
373-------------------------
374
375This directory stores the build statistics.
376
377.. _structure-build-tmp-cache:
378
379``build/tmp/cache/``
380--------------------
381
382When BitBake parses the metadata (recipes and configuration files), it
383caches the results in ``build/tmp/cache/`` to speed up future builds.
384The results are stored on a per-machine basis.
385
386During subsequent builds, BitBake checks each recipe (together with, for
387example, any files included or appended to it) to see if they have been
388modified. Changes can be detected, for example, through file
389modification time (mtime) changes and hashing of file contents. If no
390changes to the file are detected, then the parsed result stored in the
391cache is reused. If the file has changed, it is reparsed.
392
393.. _structure-build-tmp-deploy:
394
395``build/tmp/deploy/``
396---------------------
397
398This directory contains any "end result" output from the OpenEmbedded
399build process. The :term:`DEPLOY_DIR` variable points
400to this directory. For more detail on the contents of the ``deploy``
401directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600402":ref:`overview-manual/concepts:images`" and
403":ref:`overview-manual/concepts:application development sdk`" sections in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404Project Overview and Concepts Manual.
405
406.. _structure-build-tmp-deploy-deb:
407
408``build/tmp/deploy/deb/``
409-------------------------
410
411This directory receives any ``.deb`` packages produced by the build
412process. The packages are sorted into feeds for different architecture
413types.
414
415.. _structure-build-tmp-deploy-rpm:
416
417``build/tmp/deploy/rpm/``
418-------------------------
419
420This directory receives any ``.rpm`` packages produced by the build
421process. The packages are sorted into feeds for different architecture
422types.
423
424.. _structure-build-tmp-deploy-ipk:
425
426``build/tmp/deploy/ipk/``
427-------------------------
428
429This directory receives ``.ipk`` packages produced by the build process.
430
431.. _structure-build-tmp-deploy-licenses:
432
433``build/tmp/deploy/licenses/``
434------------------------------
435
436This directory receives package licensing information. For example, the
437directory contains sub-directories for ``bash``, ``busybox``, and
438``glibc`` (among others) that in turn contain appropriate ``COPYING``
439license files with other licensing information. For information on
440licensing, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600441":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442section in the Yocto Project Development Tasks Manual.
443
444.. _structure-build-tmp-deploy-images:
445
446``build/tmp/deploy/images/``
447----------------------------
448
449This directory is populated with the basic output objects of the build
450(think of them as the "generated artifacts" of the build process),
451including things like the boot loader image, kernel, root filesystem and
452more. If you want to flash the resulting image from a build onto a
453device, look here for the necessary components.
454
455Be careful when deleting files in this directory. You can safely delete
456old images from this directory (e.g. ``core-image-*``). However, the
457kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other
458supplementary files might be deployed here prior to building an image.
459Because these files are not directly produced from the image, if you
460delete them they will not be automatically re-created when you build the
461image again.
462
463If you do accidentally delete files here, you will need to force them to
464be re-created. In order to do that, you will need to know the target
465that produced them. For example, these commands rebuild and re-create
466the kernel files:
467::
468
469 $ bitbake -c clean virtual/kernel
470 $ bitbake virtual/kernel
471
472.. _structure-build-tmp-deploy-sdk:
473
474``build/tmp/deploy/sdk/``
475-------------------------
476
477The OpenEmbedded build system creates this directory to hold toolchain
478installer scripts which, when executed, install the sysroot that matches
479your target hardware. You can find out more about these installers in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600480the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500481section in the Yocto Project Application Development and the Extensible
482Software Development Kit (eSDK) manual.
483
484.. _structure-build-tmp-sstate-control:
485
486``build/tmp/sstate-control/``
487-----------------------------
488
489The OpenEmbedded build system uses this directory for the shared state
490manifest files. The shared state code uses these files to record the
491files installed by each sstate task so that the files can be removed
492when cleaning the recipe or when a newer version is about to be
493installed. The build system also uses the manifests to detect and
494produce a warning when files from one task are overwriting those from
495another.
496
497.. _structure-build-tmp-sysroots-components:
498
499``build/tmp/sysroots-components/``
500----------------------------------
501
502This directory is the location of the sysroot contents that the task
503:ref:`ref-tasks-prepare_recipe_sysroot`
504links or copies into the recipe-specific sysroot for each recipe listed
505in :term:`DEPENDS`. Population of this directory is
506handled through shared state, while the path is specified by the
507:term:`COMPONENTS_DIR` variable. Apart from a few
508unusual circumstances, handling of the ``sysroots-components`` directory
509should be automatic, and recipes should not directly reference
510``build/tmp/sysroots-components``.
511
512.. _structure-build-tmp-sysroots:
513
514``build/tmp/sysroots/``
515-----------------------
516
517Previous versions of the OpenEmbedded build system used to create a
518global shared sysroot per machine along with a native sysroot. Beginning
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500519with the 2.3 version of the Yocto Project, sysroots exist in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520recipe-specific :term:`WORKDIR` directories. Thus, the
521``build/tmp/sysroots/`` directory is unused.
522
523.. note::
524
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500525 The ``build/tmp/sysroots/`` directory can still be populated using the
526 ``bitbake build-sysroots`` command and can be used for compatibility in some
527 cases. However, in general it is not recommended to populate this directory.
528 Individual recipe-specific sysroots should be used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500529
530.. _structure-build-tmp-stamps:
531
532``build/tmp/stamps/``
533---------------------
534
535This directory holds information that BitBake uses for accounting
536purposes to track what tasks have run and when they have run. The
537directory is sub-divided by architecture, package name, and version.
538Following is an example:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500539::
540
541 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
542
543Although the files in the directory are empty of data, BitBake uses the filenames
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500544and timestamps for tracking purposes.
545
546For information on how BitBake uses stamp files to determine if a task
547should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600548":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500549section in the Yocto Project Overview and Concepts Manual.
550
551.. _structure-build-tmp-log:
552
553``build/tmp/log/``
554------------------
555
556This directory contains general logs that are not otherwise placed using
557the package's ``WORKDIR``. Examples of logs are the output from the
558``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
559necessarily mean this directory is created.
560
561.. _structure-build-tmp-work:
562
563``build/tmp/work/``
564-------------------
565
566This directory contains architecture-specific work sub-directories for
567packages built by BitBake. All tasks execute from the appropriate work
568directory. For example, the source for a particular package is unpacked,
569patched, configured and compiled all within its own work directory.
570Within the work directory, organization is based on the package group
571and version for which the source is being compiled as defined by the
572:term:`WORKDIR`.
573
574It is worth considering the structure of a typical work directory. As an
575example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
576built within the Yocto Project. For this package, a work directory of
577``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
578to as the ``WORKDIR``, is created. Within this directory, the source is
579unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600580(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500581the Yocto Project Development Tasks Manual for more information.) Within
582the ``linux-qemux86-standard-build`` directory, standard Quilt
583directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
584standard Quilt commands can be used.
585
586There are other directories generated within ``WORKDIR``. The most
587important directory is ``WORKDIR/temp/``, which has log files for each
588task (``log.do_*.pid``) and contains the scripts BitBake runs for each
589task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
590install" places its output that is then split into sub-packages within
591``WORKDIR/packages-split/``.
592
593.. _structure-build-tmp-work-tunearch-recipename-version:
594
595``build/tmp/work/tunearch/recipename/version/``
596-----------------------------------------------
597
598The recipe work directory - ``${WORKDIR}``.
599
600As described earlier in the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500601":ref:`structure-build-tmp-sysroots`" section,
602beginning with the 2.3 release of the Yocto Project, the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500603build system builds each recipe in its own work directory (i.e.
604:term:`WORKDIR`). The path to the work directory is
605constructed using the architecture of the given build (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500606:term:`TUNE_PKGARCH`, :term:`MACHINE_ARCH`, or "allarch"), the recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607name, and the version of the recipe (i.e.
608:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
609
610A number of key subdirectories exist within each recipe work directory:
611
612- ``${WORKDIR}/temp``: Contains the log files of each task executed for
613 this recipe, the "run" files for each executed task, which contain
614 the code run, and a ``log.task_order`` file, which lists the order in
615 which tasks were executed.
616
617- ``${WORKDIR}/image``: Contains the output of the
618 :ref:`ref-tasks-install` task, which corresponds to
619 the ``${``\ :term:`D`\ ``}`` variable in that task.
620
621- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any
622 tasks executed under pseudo for the recipe.
623
624- ``${WORKDIR}/sysroot-destdir``: Contains the output of the
625 :ref:`ref-tasks-populate_sysroot` task.
626
627- ``${WORKDIR}/package``: Contains the output of the
628 :ref:`ref-tasks-package` task before the output is
629 split into individual packages.
630
631- ``${WORKDIR}/packages-split``: Contains the output of the
632 ``do_package`` task after the output has been split into individual
633 packages. Subdirectories exist for each individual package created by
634 the recipe.
635
636- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
637 dependencies of the recipe. This directory looks like the target
638 filesystem and contains libraries that the recipe might need to link
639 against (e.g. the C library).
640
641- ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the
642 native dependencies of the recipe. This directory contains the tools
643 the recipe needs to build (e.g. the compiler, Autoconf, libtool, and
644 so forth).
645
646- ``${WORKDIR}/build``: This subdirectory applies only to recipes that
647 support builds where the source is separate from the build artifacts.
648 The OpenEmbedded build system uses this directory as a separate build
649 directory (i.e. ``${``\ :term:`B`\ ``}``).
650
651.. _structure-build-work-shared:
652
653``build/tmp/work-shared/``
654--------------------------
655
656For efficiency, the OpenEmbedded build system creates and uses this
657directory to hold recipes that share a work directory with other
658recipes. In practice, this is only used for ``gcc`` and its variants
659(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth).
660
661.. _structure-meta:
662
663The Metadata - ``meta/``
664========================
665
666As mentioned previously, :term:`Metadata` is the core of the
667Yocto Project. Metadata has several important subdivisions:
668
669.. _structure-meta-classes:
670
671``meta/classes/``
672-----------------
673
674This directory contains the ``*.bbclass`` files. Class files are used to
675abstract common code so it can be reused by multiple packages. Every
676package inherits the ``base.bbclass`` file. Examples of other important
677classes are ``autotools.bbclass``, which in theory allows any
678Autotool-enabled package to work with the Yocto Project with minimal
679effort. Another example is ``kernel.bbclass`` that contains common code
680and functions for working with the Linux kernel. Functions like image
681generation or packaging also have their specific class files such as
682``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``.
683
684For reference information on classes, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600685":ref:`ref-manual/classes:Classes`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500686
687.. _structure-meta-conf:
688
689``meta/conf/``
690--------------
691
692This directory contains the core set of configuration files that start
693from ``bitbake.conf`` and from which all other configuration files are
694included. See the include statements at the end of the ``bitbake.conf``
695file and you will note that even ``local.conf`` is loaded from there.
696While ``bitbake.conf`` sets up the defaults, you can often override
697these by using the (``local.conf``) file, machine file or the
698distribution configuration file.
699
700.. _structure-meta-conf-machine:
701
702``meta/conf/machine/``
703----------------------
704
705This directory contains all the machine configuration files. If you set
706``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a
707``qemux86.conf`` file in this directory. The ``include`` directory
708contains various data common to multiple machines. If you want to add
709support for a new machine to the Yocto Project, look in this directory.
710
711.. _structure-meta-conf-distro:
712
713``meta/conf/distro/``
714---------------------
715
716The contents of this directory controls any distribution-specific
717configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
718main file here. This directory includes the versions and the ``SRCDATE``
719definitions for applications that are configured here. An example of an
720alternative configuration might be ``poky-bleeding.conf``. Although this
721file mainly inherits its configuration from Poky.
722
723.. _structure-meta-conf-machine-sdk:
724
725``meta/conf/machine-sdk/``
726--------------------------
727
728The OpenEmbedded build system searches this directory for configuration
729files that correspond to the value of
730:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86
731files ship with the Yocto Project that support some SDK hosts. However,
732it is possible to extend that support to other SDK hosts by adding
733additional configuration files in this subdirectory within another
734layer.
735
736.. _structure-meta-files:
737
738``meta/files/``
739---------------
740
741This directory contains common license files and several text files used
742by the build system. The text files contain minimal device information
743and lists of files and directories with known permissions.
744
745.. _structure-meta-lib:
746
747``meta/lib/``
748-------------
749
750This directory contains OpenEmbedded Python library code used during the
751build process.
752
753.. _structure-meta-recipes-bsp:
754
755``meta/recipes-bsp/``
756---------------------
757
758This directory contains anything linking to specific hardware or
759hardware configuration information such as "u-boot" and "grub".
760
761.. _structure-meta-recipes-connectivity:
762
763``meta/recipes-connectivity/``
764------------------------------
765
766This directory contains libraries and applications related to
767communication with other devices.
768
769.. _structure-meta-recipes-core:
770
771``meta/recipes-core/``
772----------------------
773
774This directory contains what is needed to build a basic working Linux
775image including commonly used dependencies.
776
777.. _structure-meta-recipes-devtools:
778
779``meta/recipes-devtools/``
780--------------------------
781
782This directory contains tools that are primarily used by the build
783system. The tools, however, can also be used on targets.
784
785.. _structure-meta-recipes-extended:
786
787``meta/recipes-extended/``
788--------------------------
789
790This directory contains non-essential applications that add features
791compared to the alternatives in core. You might need this directory for
792full tool functionality or for Linux Standard Base (LSB) compliance.
793
794.. _structure-meta-recipes-gnome:
795
796``meta/recipes-gnome/``
797-----------------------
798
799This directory contains all things related to the GTK+ application
800framework.
801
802.. _structure-meta-recipes-graphics:
803
804``meta/recipes-graphics/``
805--------------------------
806
807This directory contains X and other graphically related system
808libraries.
809
810.. _structure-meta-recipes-kernel:
811
812``meta/recipes-kernel/``
813------------------------
814
815This directory contains the kernel and generic applications and
816libraries that have strong kernel dependencies.
817
818.. _structure-meta-recipes-lsb4:
819
820``meta/recipes-lsb4/``
821----------------------
822
823This directory contains recipes specifically added to support the Linux
824Standard Base (LSB) version 4.x.
825
826.. _structure-meta-recipes-multimedia:
827
828``meta/recipes-multimedia/``
829----------------------------
830
831This directory contains codecs and support utilities for audio, images
832and video.
833
834.. _structure-meta-recipes-rt:
835
836``meta/recipes-rt/``
837--------------------
838
839This directory contains package and image recipes for using and testing
840the ``PREEMPT_RT`` kernel.
841
842.. _structure-meta-recipes-sato:
843
844``meta/recipes-sato/``
845----------------------
846
847This directory contains the Sato demo/reference UI/UX and its associated
848applications and configuration data.
849
850.. _structure-meta-recipes-support:
851
852``meta/recipes-support/``
853-------------------------
854
855This directory contains recipes used by other recipes, but that are not
856directly included in images (i.e. dependencies of other recipes).
857
858.. _structure-meta-site:
859
860``meta/site/``
861--------------
862
863This directory contains a list of cached results for various
864architectures. Because certain "autoconf" test results cannot be
865determined when cross-compiling due to the tests not able to run on a
866live system, the information in this directory is passed to "autoconf"
867for the various architectures.
868
869.. _structure-meta-recipes-txt:
870
871``meta/recipes.txt``
872--------------------
873
874This file is a description of the contents of ``recipes-*``.