blob: 36c9efc1e20ca4093e92822468ce6bb826e4ac9d [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
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
Andrew Geisslerc926e172021-05-07 16:11:35 -0500156possible targets to build. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500157
158 $ source oe-init-build-env
159
160 ### Shell environment set up for builds. ###
161
162 You can now run 'bitbake <target>'
163
164 Common targets are:
165 core-image-minimal
166 core-image-sato
167 meta-toolchain
168 meta-ide-support
169
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500170 You can also run generated QEMU images with a command like 'runqemu qemux86-64'
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171
172The default output of the ``oe-init-build-env`` script is from the
173``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
174within the :term:`Source Directory`. If you design a
175custom distribution, you can include your own version of this
176configuration file to mention the targets defined by your distribution.
177See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600178":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179section in the Yocto Project Development Tasks Manual for more
180information.
181
182By default, running this script without a Build Directory argument
183creates the ``build/`` directory in your current working directory. If
184you provide a Build Directory argument when you ``source`` the script,
185you direct the OpenEmbedded build system to create a Build Directory of
186your choice. For example, the following command creates a Build
Andrew Geisslerc926e172021-05-07 16:11:35 -0500187Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500188
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500189 $ source oe-init-build-env ~/mybuilds
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190
191The OpenEmbedded build system uses the template configuration files, which
192are found by default in the ``meta-poky/conf/`` directory in the Source
193Directory. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600194":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500195section in the Yocto Project Development Tasks Manual for more
196information.
197
198.. note::
199
200 The OpenEmbedded build system does not support file or directory
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500201 names that contain spaces. If you attempt to run the ``oe-init-build-env``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202 script from a Source Directory that contains spaces in either the
203 filenames or directory names, the script returns an error indicating
204 no such file or directory. Be sure to use a Source Directory free of
205 names containing spaces.
206
207.. _structure-basic-top-level:
208
209``LICENSE, README, and README.hardware``
210----------------------------------------
211
212These files are standard top-level files.
213
214.. _structure-build:
215
216The Build Directory - ``build/``
217================================
218
219The OpenEmbedded build system creates the :term:`Build Directory`
220when you run the build environment setup
221script :ref:`structure-core-script`. If you do not give the Build
222Directory a specific name when you run the setup script, the name
223defaults to ``build/``.
224
225For subsequent parsing and processing, the name of the Build directory
226is available via the :term:`TOPDIR` variable.
227
228.. _structure-build-buildhistory:
229
230``build/buildhistory/``
231-----------------------
232
233The OpenEmbedded build system creates this directory when you enable
234build history via the ``buildhistory`` class file. The directory
235organizes build information into image, packages, and SDK
236subdirectories. For information on the build history feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600237":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238section in the Yocto Project Development Tasks Manual.
239
240.. _structure-build-conf-local.conf:
241
242``build/conf/local.conf``
243-------------------------
244
245This configuration file contains all the local user configurations for
246your build environment. The ``local.conf`` file contains documentation
247on the various configuration options. Any variable set here overrides
248any variable set elsewhere within the environment unless that variable
249is hard-coded within a file (e.g. by using '=' instead of '?='). Some
250variables are hard-coded for various reasons but such variables are
251relatively rare.
252
253At a minimum, you would normally edit this file to select the target
254``MACHINE``, which package types you wish to use
255(:term:`PACKAGE_CLASSES`), and the location from
256which you want to access downloaded files (``DL_DIR``).
257
258If ``local.conf`` is not present when you start the build, the
259OpenEmbedded build system creates it from ``local.conf.sample`` when you
260``source`` the top-level build environment setup script
261:ref:`structure-core-script`.
262
263The source ``local.conf.sample`` file used depends on the
264``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
265when you are building from the Yocto Project development environment,
266and to ``meta/conf/`` when you are building from the OpenEmbedded-Core
267environment. Because the script variable points to the source of the
268``local.conf.sample`` file, this implies that you can configure your
269build environment from any layer by setting the variable in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500270top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
272 TEMPLATECONF=your_layer/conf
273
274Once the build process gets the sample
275file, it uses ``sed`` to substitute final
276``${``\ :term:`OEROOT`\ ``}`` values for all
277``##OEROOT##`` values.
278
279.. note::
280
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500281 You can see how the ``TEMPLATECONF`` variable is used by looking at the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700282 ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500283 You can find the Yocto Project version of the ``local.conf.sample`` file in
284 the ``meta-poky/conf`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285
286.. _structure-build-conf-bblayers.conf:
287
288``build/conf/bblayers.conf``
289----------------------------
290
291This configuration file defines
Andrew Geissler09209ee2020-12-13 08:44:15 -0600292:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293which are directory trees, traversed (or walked) by BitBake. The
294``bblayers.conf`` file uses the :term:`BBLAYERS`
295variable to list the layers BitBake tries to find.
296
297If ``bblayers.conf`` is not present when you start the build, the
298OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
299you ``source`` the top-level build environment setup script (i.e.
300:ref:`structure-core-script`).
301
302As with the ``local.conf`` file, the source ``bblayers.conf.sample``
303file used depends on the ``$TEMPLATECONF`` script variable, which
304defaults to ``meta-poky/conf/`` when you are building from the Yocto
305Project development environment, and to ``meta/conf/`` when you are
306building from the OpenEmbedded-Core environment. Because the script
307variable points to the source of the ``bblayers.conf.sample`` file, this
308implies that you can base your build from any layer by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500309variable in the top-level build environment setup script as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500310
311 TEMPLATECONF=your_layer/conf
312
313Once the build process gets the sample file, it uses ``sed`` to substitute final
314``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
315
316.. note::
317
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500318 You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir``
319 script in the :term:`Source Directory`. You can find the Yocto Project
320 version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500321 directory.
322
323.. _structure-build-conf-sanity_info:
324
325``build/cache/sanity_info``
326---------------------------
327
328This file indicates the state of the sanity checks and is created during
329the build.
330
331.. _structure-build-downloads:
332
333``build/downloads/``
334--------------------
335
336This directory contains downloaded upstream source tarballs. You can
337reuse the directory for multiple builds or move the directory to another
338location. You can control the location of this directory through the
339``DL_DIR`` variable.
340
341.. _structure-build-sstate-cache:
342
343``build/sstate-cache/``
344-----------------------
345
346This directory contains the shared state cache. You can reuse the
347directory for multiple builds or move the directory to another location.
348You can control the location of this directory through the
349``SSTATE_DIR`` variable.
350
351.. _structure-build-tmp:
352
353``build/tmp/``
354--------------
355
356The OpenEmbedded build system creates and uses this directory for all
357the build system's output. The :term:`TMPDIR` variable
358points to this directory.
359
360BitBake creates this directory if it does not exist. As a last resort,
361to clean up a build and start it from scratch (other than the
362downloads), you can remove everything in the ``tmp`` directory or get
363rid of the directory completely. If you do, you should also completely
364remove the ``build/sstate-cache`` directory.
365
366.. _structure-build-tmp-buildstats:
367
368``build/tmp/buildstats/``
369-------------------------
370
371This directory stores the build statistics.
372
373.. _structure-build-tmp-cache:
374
375``build/tmp/cache/``
376--------------------
377
378When BitBake parses the metadata (recipes and configuration files), it
379caches the results in ``build/tmp/cache/`` to speed up future builds.
380The results are stored on a per-machine basis.
381
382During subsequent builds, BitBake checks each recipe (together with, for
383example, any files included or appended to it) to see if they have been
384modified. Changes can be detected, for example, through file
385modification time (mtime) changes and hashing of file contents. If no
386changes to the file are detected, then the parsed result stored in the
387cache is reused. If the file has changed, it is reparsed.
388
389.. _structure-build-tmp-deploy:
390
391``build/tmp/deploy/``
392---------------------
393
394This directory contains any "end result" output from the OpenEmbedded
395build process. The :term:`DEPLOY_DIR` variable points
396to this directory. For more detail on the contents of the ``deploy``
397directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600398":ref:`overview-manual/concepts:images`" and
399":ref:`overview-manual/concepts:application development sdk`" sections in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500400Project Overview and Concepts Manual.
401
402.. _structure-build-tmp-deploy-deb:
403
404``build/tmp/deploy/deb/``
405-------------------------
406
407This directory receives any ``.deb`` packages produced by the build
408process. The packages are sorted into feeds for different architecture
409types.
410
411.. _structure-build-tmp-deploy-rpm:
412
413``build/tmp/deploy/rpm/``
414-------------------------
415
416This directory receives any ``.rpm`` packages produced by the build
417process. The packages are sorted into feeds for different architecture
418types.
419
420.. _structure-build-tmp-deploy-ipk:
421
422``build/tmp/deploy/ipk/``
423-------------------------
424
425This directory receives ``.ipk`` packages produced by the build process.
426
427.. _structure-build-tmp-deploy-licenses:
428
429``build/tmp/deploy/licenses/``
430------------------------------
431
432This directory receives package licensing information. For example, the
433directory contains sub-directories for ``bash``, ``busybox``, and
434``glibc`` (among others) that in turn contain appropriate ``COPYING``
435license files with other licensing information. For information on
436licensing, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600437":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500438section in the Yocto Project Development Tasks Manual.
439
440.. _structure-build-tmp-deploy-images:
441
442``build/tmp/deploy/images/``
443----------------------------
444
445This directory is populated with the basic output objects of the build
446(think of them as the "generated artifacts" of the build process),
447including things like the boot loader image, kernel, root filesystem and
448more. If you want to flash the resulting image from a build onto a
449device, look here for the necessary components.
450
451Be careful when deleting files in this directory. You can safely delete
452old images from this directory (e.g. ``core-image-*``). However, the
453kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other
454supplementary files might be deployed here prior to building an image.
455Because these files are not directly produced from the image, if you
456delete them they will not be automatically re-created when you build the
457image again.
458
459If you do accidentally delete files here, you will need to force them to
460be re-created. In order to do that, you will need to know the target
461that produced them. For example, these commands rebuild and re-create
Andrew Geisslerc926e172021-05-07 16:11:35 -0500462the kernel files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463
464 $ bitbake -c clean virtual/kernel
465 $ bitbake virtual/kernel
466
467.. _structure-build-tmp-deploy-sdk:
468
469``build/tmp/deploy/sdk/``
470-------------------------
471
472The OpenEmbedded build system creates this directory to hold toolchain
473installer scripts which, when executed, install the sysroot that matches
474your target hardware. You can find out more about these installers in
Andrew Geissler09209ee2020-12-13 08:44:15 -0600475the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500476section in the Yocto Project Application Development and the Extensible
477Software Development Kit (eSDK) manual.
478
479.. _structure-build-tmp-sstate-control:
480
481``build/tmp/sstate-control/``
482-----------------------------
483
484The OpenEmbedded build system uses this directory for the shared state
485manifest files. The shared state code uses these files to record the
486files installed by each sstate task so that the files can be removed
487when cleaning the recipe or when a newer version is about to be
488installed. The build system also uses the manifests to detect and
489produce a warning when files from one task are overwriting those from
490another.
491
492.. _structure-build-tmp-sysroots-components:
493
494``build/tmp/sysroots-components/``
495----------------------------------
496
497This directory is the location of the sysroot contents that the task
498:ref:`ref-tasks-prepare_recipe_sysroot`
499links or copies into the recipe-specific sysroot for each recipe listed
500in :term:`DEPENDS`. Population of this directory is
501handled through shared state, while the path is specified by the
502:term:`COMPONENTS_DIR` variable. Apart from a few
503unusual circumstances, handling of the ``sysroots-components`` directory
504should be automatic, and recipes should not directly reference
505``build/tmp/sysroots-components``.
506
507.. _structure-build-tmp-sysroots:
508
509``build/tmp/sysroots/``
510-----------------------
511
512Previous versions of the OpenEmbedded build system used to create a
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700513global shared sysroot per machine along with a native sysroot. Since
514the 2.3 version of the Yocto Project, there are sysroots in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500515recipe-specific :term:`WORKDIR` directories. Thus, the
516``build/tmp/sysroots/`` directory is unused.
517
518.. note::
519
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500520 The ``build/tmp/sysroots/`` directory can still be populated using the
521 ``bitbake build-sysroots`` command and can be used for compatibility in some
522 cases. However, in general it is not recommended to populate this directory.
523 Individual recipe-specific sysroots should be used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500524
525.. _structure-build-tmp-stamps:
526
527``build/tmp/stamps/``
528---------------------
529
530This directory holds information that BitBake uses for accounting
531purposes to track what tasks have run and when they have run. The
532directory is sub-divided by architecture, package name, and version.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500533Following is an example::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500534
535 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
536
537Although the files in the directory are empty of data, BitBake uses the filenames
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500538and timestamps for tracking purposes.
539
540For information on how BitBake uses stamp files to determine if a task
541should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600542":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500543section in the Yocto Project Overview and Concepts Manual.
544
545.. _structure-build-tmp-log:
546
547``build/tmp/log/``
548------------------
549
550This directory contains general logs that are not otherwise placed using
551the package's ``WORKDIR``. Examples of logs are the output from the
552``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
553necessarily mean this directory is created.
554
555.. _structure-build-tmp-work:
556
557``build/tmp/work/``
558-------------------
559
560This directory contains architecture-specific work sub-directories for
561packages built by BitBake. All tasks execute from the appropriate work
562directory. For example, the source for a particular package is unpacked,
563patched, configured and compiled all within its own work directory.
564Within the work directory, organization is based on the package group
565and version for which the source is being compiled as defined by the
566:term:`WORKDIR`.
567
568It is worth considering the structure of a typical work directory. As an
569example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
570built within the Yocto Project. For this package, a work directory of
571``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
572to as the ``WORKDIR``, is created. Within this directory, the source is
573unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600574(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500575the Yocto Project Development Tasks Manual for more information.) Within
576the ``linux-qemux86-standard-build`` directory, standard Quilt
577directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
578standard Quilt commands can be used.
579
580There are other directories generated within ``WORKDIR``. The most
581important directory is ``WORKDIR/temp/``, which has log files for each
582task (``log.do_*.pid``) and contains the scripts BitBake runs for each
583task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
584install" places its output that is then split into sub-packages within
585``WORKDIR/packages-split/``.
586
587.. _structure-build-tmp-work-tunearch-recipename-version:
588
589``build/tmp/work/tunearch/recipename/version/``
590-----------------------------------------------
591
592The recipe work directory - ``${WORKDIR}``.
593
594As described earlier in the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500595":ref:`structure-build-tmp-sysroots`" section,
596beginning with the 2.3 release of the Yocto Project, the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500597build system builds each recipe in its own work directory (i.e.
598:term:`WORKDIR`). The path to the work directory is
599constructed using the architecture of the given build (e.g.
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500600:term:`TUNE_PKGARCH`, :term:`MACHINE_ARCH`, or "allarch"), the recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500601name, and the version of the recipe (i.e.
602:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
603
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700604Here are key subdirectories within each recipe work directory:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500605
606- ``${WORKDIR}/temp``: Contains the log files of each task executed for
607 this recipe, the "run" files for each executed task, which contain
608 the code run, and a ``log.task_order`` file, which lists the order in
609 which tasks were executed.
610
611- ``${WORKDIR}/image``: Contains the output of the
612 :ref:`ref-tasks-install` task, which corresponds to
613 the ``${``\ :term:`D`\ ``}`` variable in that task.
614
615- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any
616 tasks executed under pseudo for the recipe.
617
618- ``${WORKDIR}/sysroot-destdir``: Contains the output of the
619 :ref:`ref-tasks-populate_sysroot` task.
620
621- ``${WORKDIR}/package``: Contains the output of the
622 :ref:`ref-tasks-package` task before the output is
623 split into individual packages.
624
625- ``${WORKDIR}/packages-split``: Contains the output of the
626 ``do_package`` task after the output has been split into individual
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700627 packages. There are subdirectories for each individual package created by
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500628 the recipe.
629
630- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
631 dependencies of the recipe. This directory looks like the target
632 filesystem and contains libraries that the recipe might need to link
633 against (e.g. the C library).
634
635- ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the
636 native dependencies of the recipe. This directory contains the tools
637 the recipe needs to build (e.g. the compiler, Autoconf, libtool, and
638 so forth).
639
640- ``${WORKDIR}/build``: This subdirectory applies only to recipes that
641 support builds where the source is separate from the build artifacts.
642 The OpenEmbedded build system uses this directory as a separate build
643 directory (i.e. ``${``\ :term:`B`\ ``}``).
644
645.. _structure-build-work-shared:
646
647``build/tmp/work-shared/``
648--------------------------
649
650For efficiency, the OpenEmbedded build system creates and uses this
651directory to hold recipes that share a work directory with other
652recipes. In practice, this is only used for ``gcc`` and its variants
653(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth).
654
655.. _structure-meta:
656
657The Metadata - ``meta/``
658========================
659
660As mentioned previously, :term:`Metadata` is the core of the
661Yocto Project. Metadata has several important subdivisions:
662
663.. _structure-meta-classes:
664
665``meta/classes/``
666-----------------
667
668This directory contains the ``*.bbclass`` files. Class files are used to
669abstract common code so it can be reused by multiple packages. Every
670package inherits the ``base.bbclass`` file. Examples of other important
671classes are ``autotools.bbclass``, which in theory allows any
672Autotool-enabled package to work with the Yocto Project with minimal
673effort. Another example is ``kernel.bbclass`` that contains common code
674and functions for working with the Linux kernel. Functions like image
675generation or packaging also have their specific class files such as
676``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``.
677
678For reference information on classes, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600679":ref:`ref-manual/classes:Classes`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680
681.. _structure-meta-conf:
682
683``meta/conf/``
684--------------
685
686This directory contains the core set of configuration files that start
687from ``bitbake.conf`` and from which all other configuration files are
688included. See the include statements at the end of the ``bitbake.conf``
689file and you will note that even ``local.conf`` is loaded from there.
690While ``bitbake.conf`` sets up the defaults, you can often override
691these by using the (``local.conf``) file, machine file or the
692distribution configuration file.
693
694.. _structure-meta-conf-machine:
695
696``meta/conf/machine/``
697----------------------
698
699This directory contains all the machine configuration files. If you set
700``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a
701``qemux86.conf`` file in this directory. The ``include`` directory
702contains various data common to multiple machines. If you want to add
703support for a new machine to the Yocto Project, look in this directory.
704
705.. _structure-meta-conf-distro:
706
707``meta/conf/distro/``
708---------------------
709
710The contents of this directory controls any distribution-specific
711configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
712main file here. This directory includes the versions and the ``SRCDATE``
713definitions for applications that are configured here. An example of an
714alternative configuration might be ``poky-bleeding.conf``. Although this
715file mainly inherits its configuration from Poky.
716
717.. _structure-meta-conf-machine-sdk:
718
719``meta/conf/machine-sdk/``
720--------------------------
721
722The OpenEmbedded build system searches this directory for configuration
723files that correspond to the value of
724:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86
725files ship with the Yocto Project that support some SDK hosts. However,
726it is possible to extend that support to other SDK hosts by adding
727additional configuration files in this subdirectory within another
728layer.
729
730.. _structure-meta-files:
731
732``meta/files/``
733---------------
734
735This directory contains common license files and several text files used
736by the build system. The text files contain minimal device information
737and lists of files and directories with known permissions.
738
739.. _structure-meta-lib:
740
741``meta/lib/``
742-------------
743
744This directory contains OpenEmbedded Python library code used during the
745build process.
746
747.. _structure-meta-recipes-bsp:
748
749``meta/recipes-bsp/``
750---------------------
751
752This directory contains anything linking to specific hardware or
753hardware configuration information such as "u-boot" and "grub".
754
755.. _structure-meta-recipes-connectivity:
756
757``meta/recipes-connectivity/``
758------------------------------
759
760This directory contains libraries and applications related to
761communication with other devices.
762
763.. _structure-meta-recipes-core:
764
765``meta/recipes-core/``
766----------------------
767
768This directory contains what is needed to build a basic working Linux
769image including commonly used dependencies.
770
771.. _structure-meta-recipes-devtools:
772
773``meta/recipes-devtools/``
774--------------------------
775
776This directory contains tools that are primarily used by the build
777system. The tools, however, can also be used on targets.
778
779.. _structure-meta-recipes-extended:
780
781``meta/recipes-extended/``
782--------------------------
783
784This directory contains non-essential applications that add features
785compared to the alternatives in core. You might need this directory for
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700786full tool functionality.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500787
788.. _structure-meta-recipes-gnome:
789
790``meta/recipes-gnome/``
791-----------------------
792
793This directory contains all things related to the GTK+ application
794framework.
795
796.. _structure-meta-recipes-graphics:
797
798``meta/recipes-graphics/``
799--------------------------
800
801This directory contains X and other graphically related system
802libraries.
803
804.. _structure-meta-recipes-kernel:
805
806``meta/recipes-kernel/``
807------------------------
808
809This directory contains the kernel and generic applications and
810libraries that have strong kernel dependencies.
811
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500812.. _structure-meta-recipes-multimedia:
813
814``meta/recipes-multimedia/``
815----------------------------
816
817This directory contains codecs and support utilities for audio, images
818and video.
819
820.. _structure-meta-recipes-rt:
821
822``meta/recipes-rt/``
823--------------------
824
825This directory contains package and image recipes for using and testing
826the ``PREEMPT_RT`` kernel.
827
828.. _structure-meta-recipes-sato:
829
830``meta/recipes-sato/``
831----------------------
832
833This directory contains the Sato demo/reference UI/UX and its associated
834applications and configuration data.
835
836.. _structure-meta-recipes-support:
837
838``meta/recipes-support/``
839-------------------------
840
841This directory contains recipes used by other recipes, but that are not
842directly included in images (i.e. dependencies of other recipes).
843
844.. _structure-meta-site:
845
846``meta/site/``
847--------------
848
849This directory contains a list of cached results for various
850architectures. Because certain "autoconf" test results cannot be
851determined when cross-compiling due to the tests not able to run on a
852live system, the information in this directory is passed to "autoconf"
853for the various architectures.
854
855.. _structure-meta-recipes-txt:
856
857``meta/recipes.txt``
858--------------------
859
860This file is a description of the contents of ``recipes-*``.