documentation/ref-manual/structure.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
15 ":ref:`dev-manual/start:locating yocto project source files`"
24 .. _structure-core:
26 Top-Level Core Components
29 This section describes the top-level components of the :term:`Source Directory`.
31 .. _structure-core-bitbake:
34 ------------
45 environment setup script (i.e. :ref:`structure-core-script`) places
52 .. _structure-core-build:
55 ----------
62 :ref:`structure-core-script`).
69 ":ref:`structure-core-script`" section.
74 ------------------
78 versions of the manuals. Each manual is contained in its own sub-folder;
80 ``ref-manual/`` directory.
82 .. _structure-core-meta:
85 ---------
87 This directory contains the minimal, underlying OpenEmbedded-Core
92 .. _structure-core-meta-poky:
94 ``meta-poky/``
95 --------------
100 .. _structure-core-meta-yocto-bsp:
102 ``meta-yocto-bsp/``
103 -------------------
107 :doc:`/bsp-guide/index`.
109 .. _structure-meta-selftest:
111 ``meta-selftest/``
112 ------------------
119 .. _structure-meta-skeleton:
121 ``meta-skeleton/``
122 ------------------
126 .. _structure-core-scripts:
129 ------------
133 :ref:`structure-core-script` script prepends this directory to the
137 back to the Yocto Project, such as ``create-pull-request`` and
138 ``send-pull-request``.
140 .. _structure-core-script:
142 ``oe-init-build-env``
143 ---------------------
158    $ source oe-init-build-env
165        core-image-minimal
166        core-image-sato
167        meta-toolchain
168        meta-ide-support
170    You can also run generated QEMU images with a command like 'runqemu qemux86-64'
172 The 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
178 ":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
189    $ source oe-init-build-env ~/mybuilds
192 are found by default in the ``meta-poky/conf/`` directory in the Source
194 ":ref:`dev-manual/common-tasks:creating a custom template configuration directory`"
201    names that contain spaces. If you attempt to run the ``oe-init-build-env``
207 .. _structure-basic-top-level:
210 ----------------------------------------
212 These files are standard top-level files.
214 .. _structure-build:
216 The Build Directory - ``build/``
221 script :ref:`structure-core-script`. If you do not give the Build
228 .. _structure-build-buildhistory:
231 -----------------------
234 build history via the :ref:`buildhistory <ref-classes-buildhistory>` class file. The directory
237 ":ref:`dev-manual/common-tasks:maintaining build output quality`"
240 .. _structure-build-conf-local.conf:
243 -------------------------
249 is hard-coded within a file (e.g. by using '=' instead of '?='). Some
250 variables are hard-coded for various reasons but such variables are
260 ``source`` the top-level build environment setup script
261 :ref:`structure-core-script`.
264 ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
266 and to ``meta/conf/`` when you are building from the OpenEmbedded-Core
270 top-level build environment setup script as follows::
282    ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
284    the ``meta-poky/conf`` directory.
286 .. _structure-build-conf-bblayers.conf:
289 ----------------------------
292 :ref:`layers <dev-manual/common-tasks:understanding and creating layers>`,
299 you ``source`` the top-level build environment setup script (i.e.
300 :ref:`structure-core-script`).
304 defaults to ``meta-poky/conf/`` when you are building from the Yocto
306 building from the OpenEmbedded-Core environment. Because the script
309 variable in the top-level build environment setup script as follows::
318    You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir``
320    version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/``
323 .. _structure-build-conf-sanity_info:
325 ``build/cache/sanity_info``
326 ---------------------------
331 .. _structure-build-downloads:
334 --------------------
341 .. _structure-build-sstate-cache:
343 ``build/sstate-cache/``
344 -----------------------
346 This directory contains the shared state cache. You can reuse the
351 .. _structure-build-tmp:
354 --------------
364 remove the ``build/sstate-cache`` directory.
366 .. _structure-build-tmp-buildstats:
369 -------------------------
373 .. _structure-build-tmp-cache:
375 ``build/tmp/cache/``
376 --------------------
379 caches the results in ``build/tmp/cache/`` to speed up future builds.
380 The results are stored on a per-machine basis.
387 cache is reused. If the file has changed, it is reparsed.
389 .. _structure-build-tmp-deploy:
392 ---------------------
398 ":ref:`overview-manual/concepts:images`" and
399 ":ref:`overview-manual/concepts:application development sdk`" sections in the Yocto
402 .. _structure-build-tmp-deploy-deb:
405 -------------------------
411 .. _structure-build-tmp-deploy-rpm:
414 -------------------------
420 .. _structure-build-tmp-deploy-ipk:
423 -------------------------
427 .. _structure-build-tmp-deploy-licenses:
430 ------------------------------
433 directory contains sub-directories for ``bash``, ``busybox``, and
437 ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lif…
440 .. _structure-build-tmp-deploy-images:
443 ----------------------------
452 old images from this directory (e.g. ``core-image-*``). However, the
456 delete them they will not be automatically re-created when you build the
460 be re-created. In order to do that, you will need to know the target
461 that produced them. For example, these commands rebuild and re-create
464    $ bitbake -c clean virtual/kernel
467 .. _structure-build-tmp-deploy-sdk:
470 -------------------------
475 the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
479 .. _structure-build-tmp-sstate-control:
481 ``build/tmp/sstate-control/``
482 -----------------------------
486 files installed by each sstate task so that the files can be removed
492 .. _structure-build-tmp-sysroots-components:
494 ``build/tmp/sysroots-components/``
495 ----------------------------------
498 :ref:`ref-tasks-prepare_recipe_sysroot`
499 links or copies into the recipe-specific sysroot for each recipe listed
503 unusual circumstances, handling of the ``sysroots-components`` directory
505 ``build/tmp/sysroots-components``.
507 .. _structure-build-tmp-sysroots:
510 -----------------------
515 recipe-specific :term:`WORKDIR` directories. Thus, the
521    ``bitbake build-sysroots`` command and can be used for compatibility in some
523    Individual recipe-specific sysroots should be used.
525 .. _structure-build-tmp-stamps:
528 ---------------------
532 directory is sub-divided by architecture, package name, and version.
535       stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
542 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
545 .. _structure-build-tmp-log:
548 ------------------
555 .. _structure-build-tmp-work:
558 -------------------
560 This directory contains architecture-specific work sub-directories for
569 example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
571 ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
573 unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
574 (See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in
576 the ``linux-qemux86-standard-build`` directory, standard Quilt
577 directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
584 install" places its output that is then split into sub-packages within
585 ``WORKDIR/packages-split/``.
587 .. _structure-build-tmp-work-tunearch-recipename-version:
590 -----------------------------------------------
592 The recipe work directory - ``${WORKDIR}``.
595 ":ref:`structure-build-tmp-sysroots`" section,
602 :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
606 -  ``${WORKDIR}/temp``: Contains the log files of each task executed for
611 -  ``${WORKDIR}/image``: Contains the output of the
612    :ref:`ref-tasks-install` task, which corresponds to
615 -  ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any
618 -  ``${WORKDIR}/sysroot-destdir``: Contains the output of the
619    :ref:`ref-tasks-populate_sysroot` task.
621 -  ``${WORKDIR}/package``: Contains the output of the
622    :ref:`ref-tasks-package` task before the output is
625 -  ``${WORKDIR}/packages-split``: Contains the output of the
630 -  ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
635 -  ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the
640 -  ``${WORKDIR}/build``: This subdirectory applies only to recipes that
645 .. _structure-build-work-shared:
647 ``build/tmp/work-shared/``
648 --------------------------
653 (e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth).
655 .. _structure-meta:
657 The Metadata - ``meta/``
663 .. _structure-meta-classes:
666 -----------------
670 package inherits the :ref:`ref-classes-base` file. Examples of other important
671 classes are :ref:`ref-classes-autotools`, which in theory allows any
672 Autotool-enabled package to work with the Yocto Project with minimal
673 effort. Another example is :ref:`ref-classes-kernel` that contains common code
676 :ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and
677 :ref:`package*.bbclass <ref-classes-package>`.
680 ":doc:`/ref-manual/classes`" chapter.
682 .. _structure-meta-conf:
685 --------------
695 .. _structure-meta-conf-machine:
698 ----------------------
706 .. _structure-meta-conf-distro:
709 ---------------------
711 The contents of this directory controls any distribution-specific
715 alternative configuration might be ``poky-bleeding.conf``. Although this
718 .. _structure-meta-conf-machine-sdk:
720 ``meta/conf/machine-sdk/``
721 --------------------------
725 :term:`SDKMACHINE`. By default, 32-bit and 64-bit x86
731 .. _structure-meta-files:
734 ---------------
740 .. _structure-meta-lib:
743 -------------
748 .. _structure-meta-recipes-bsp:
750 ``meta/recipes-bsp/``
751 ---------------------
754 hardware configuration information such as "u-boot" and "grub".
756 .. _structure-meta-recipes-connectivity:
758 ``meta/recipes-connectivity/``
759 ------------------------------
764 .. _structure-meta-recipes-core:
766 ``meta/recipes-core/``
767 ----------------------
772 .. _structure-meta-recipes-devtools:
774 ``meta/recipes-devtools/``
775 --------------------------
780 .. _structure-meta-recipes-extended:
782 ``meta/recipes-extended/``
783 --------------------------
785 This directory contains non-essential applications that add features
789 .. _structure-meta-recipes-gnome:
791 ``meta/recipes-gnome/``
792 -----------------------
797 .. _structure-meta-recipes-graphics:
799 ``meta/recipes-graphics/``
800 --------------------------
805 .. _structure-meta-recipes-kernel:
807 ``meta/recipes-kernel/``
808 ------------------------
813 .. _structure-meta-recipes-multimedia:
815 ``meta/recipes-multimedia/``
816 ----------------------------
821 .. _structure-meta-recipes-rt:
823 ``meta/recipes-rt/``
824 --------------------
829 .. _structure-meta-recipes-sato:
831 ``meta/recipes-sato/``
832 ----------------------
837 .. _structure-meta-recipes-support:
839 ``meta/recipes-support/``
840 -------------------------
845 .. _structure-meta-site:
848 --------------
852 determined when cross-compiling due to the tests not able to run on a
856 .. _structure-meta-recipes-txt:
859 --------------------
861 This file is a description of the contents of ``recipes-*``.