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