diff options
Diffstat (limited to 'documentation/ref-manual/structure.rst')
| -rw-r--r-- | documentation/ref-manual/structure.rst | 203 |
1 files changed, 107 insertions, 96 deletions
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst index 2106a8083b..e4d8b54bb9 100644 --- a/documentation/ref-manual/structure.rst +++ b/documentation/ref-manual/structure.rst @@ -57,9 +57,8 @@ For more information on BitBake, see the :doc:`BitBake User Manual This directory contains user configuration files and the output generated by the OpenEmbedded build system in its standard configuration where the source tree is combined with the output. The :term:`Build Directory` -is created initially when you ``source`` -the OpenEmbedded build environment setup script (i.e. -:ref:`structure-core-script`). +is created initially when you ``source`` the OpenEmbedded build environment +setup script (i.e. :ref:`structure-core-script`). It is also possible to place output and configuration files in a directory separate from the :term:`Source Directory` by @@ -68,6 +67,9 @@ information on separating output from your local Source Directory files (commonly described as an "out of tree" build), see the ":ref:`structure-core-script`" section. +See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details +about the contents of the :term:`Build Directory`. + .. _handbook: ``documentation/`` @@ -150,10 +152,10 @@ BitBake commands. The script uses other scripts within the ``scripts`` directory to do the bulk of the work. When you run this script, your Yocto Project environment is set up, a -:term:`Build Directory` is created, your working -directory becomes the Build Directory, and you are presented with some -simple suggestions as to what to do next, including a list of some -possible targets to build. Here is an example:: +:term:`Build Directory` is created, your working directory becomes the +:term:`Build Directory`, and you are presented with some simple +suggestions as to what to do next, including a list of some possible +targets to build. Here is an example:: $ source oe-init-build-env @@ -170,28 +172,30 @@ possible targets to build. Here is an example:: You can also run generated QEMU images with a command like 'runqemu qemux86-64' The default output of the ``oe-init-build-env`` script is from the -``conf-notes.txt`` file, which is found in the ``meta-poky`` directory +``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the ``meta-poky`` directory within the :term:`Source Directory`. If you design a -custom distribution, you can include your own version of this -configuration file to mention the targets defined by your distribution. +custom distribution, you can include your own versions of these +configuration files where you can provide a brief summary and detailed usage +notes, such as a list of the targets defined by your distribution. See the -":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" +":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`" section in the Yocto Project Development Tasks Manual for more information. -By default, running this script without a Build Directory argument +By default, running this script without a :term:`Build Directory` argument creates the ``build/`` directory in your current working directory. If -you provide a Build Directory argument when you ``source`` the script, -you direct the OpenEmbedded build system to create a Build Directory of -your choice. For example, the following command creates a Build -Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: +you provide a :term:`Build Directory` argument when you ``source`` the script, +you direct the OpenEmbedded build system to create a :term:`Build Directory` of +your choice. For example, the following command creates a +:term:`Build Directory` named ``mybuilds/`` that is outside of the +:term:`Source Directory`:: $ source oe-init-build-env ~/mybuilds The OpenEmbedded build system uses the template configuration files, which -are found by default in the ``meta-poky/conf/`` directory in the Source +are found by default in the ``meta-poky/conf/templates/default`` directory in the Source Directory. See the -":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" +":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`" section in the Yocto Project Development Tasks Manual for more information. @@ -213,14 +217,13 @@ These files are standard top-level files. .. _structure-build: -The Build Directory - ``build/`` -================================ +The Build Directory --- ``build/`` +================================== -The OpenEmbedded build system creates the :term:`Build Directory` -when you run the build environment setup -script :ref:`structure-core-script`. If you do not give the Build -Directory a specific name when you run the setup script, the name -defaults to ``build/``. +The OpenEmbedded build system creates the :term:`Build Directory` when you run +the build environment setup script :ref:`structure-core-script`. If you do not +give the :term:`Build Directory` a specific name when you run the setup script, +the name defaults to ``build/``. For subsequent parsing and processing, the name of the Build directory is available via the :term:`TOPDIR` variable. @@ -231,12 +234,24 @@ is available via the :term:`TOPDIR` variable. ----------------------- The OpenEmbedded build system creates this directory when you enable -build history via the ``buildhistory`` class file. The directory +build history via the :ref:`ref-classes-buildhistory` class file. The directory organizes build information into image, packages, and SDK subdirectories. For information on the build history feature, see the -":ref:`dev-manual/common-tasks:maintaining build output quality`" +":ref:`dev-manual/build-quality:maintaining build output quality`" section in the Yocto Project Development Tasks Manual. +.. _structure-build-cache: + +``build/cache/`` +---------------- + +This directory contains several internal files used by the OpenEmbedded +build system. + +It also contains ``sanity_info``, a text file keeping track of important +build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`, +as well as the name and version of the host distribution. + .. _structure-build-conf-local.conf: ``build/conf/local.conf`` @@ -251,9 +266,9 @@ variables are hard-coded for various reasons but such variables are relatively rare. At a minimum, you would normally edit this file to select the target -``MACHINE``, which package types you wish to use +:term:`MACHINE`, which package types you wish to use (:term:`PACKAGE_CLASSES`), and the location from -which you want to access downloaded files (``DL_DIR``). +which you want to access downloaded files (:term:`DL_DIR`). If ``local.conf`` is not present when you start the build, the OpenEmbedded build system creates it from ``local.conf.sample`` when you @@ -261,15 +276,15 @@ OpenEmbedded build system creates it from ``local.conf.sample`` when you :ref:`structure-core-script`. The source ``local.conf.sample`` file used depends on the -``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` +:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto Project development environment, -and to ``meta/conf/`` when you are building from the OpenEmbedded-Core +and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``local.conf.sample`` file, this implies that you can configure your build environment from any layer by setting the variable in the top-level build environment setup script as follows:: - TEMPLATECONF=your_layer/conf + TEMPLATECONF=your_layer/conf/templates/your_template_name Once the build process gets the sample file, it uses ``sed`` to substitute final @@ -278,10 +293,10 @@ file, it uses ``sed`` to substitute final .. note:: - You can see how the ``TEMPLATECONF`` variable is used by looking at the + You can see how the :term:`TEMPLATECONF` variable is used by looking at the ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. You can find the Yocto Project version of the ``local.conf.sample`` file in - the ``meta-poky/conf`` directory. + the ``meta-poky/conf/templates/default`` directory. .. _structure-build-conf-bblayers.conf: @@ -289,7 +304,7 @@ file, it uses ``sed`` to substitute final ---------------------------- This configuration file defines -:ref:`layers <dev-manual/common-tasks:understanding and creating layers>`, +:ref:`layers <dev-manual/layers:understanding and creating layers>`, which are directory trees, traversed (or walked) by BitBake. The ``bblayers.conf`` file uses the :term:`BBLAYERS` variable to list the layers BitBake tries to find. @@ -300,34 +315,26 @@ you ``source`` the top-level build environment setup script (i.e. :ref:`structure-core-script`). As with the ``local.conf`` file, the source ``bblayers.conf.sample`` -file used depends on the ``$TEMPLATECONF`` script variable, which -defaults to ``meta-poky/conf/`` when you are building from the Yocto -Project development environment, and to ``meta/conf/`` when you are +file used depends on the :term:`TEMPLATECONF` script variable, which +defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto +Project development environment, and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``bblayers.conf.sample`` file, this implies that you can base your build from any layer by setting the variable in the top-level build environment setup script as follows:: - TEMPLATECONF=your_layer/conf + TEMPLATECONF=your_layer/conf/templates/your_template_name Once the build process gets the sample file, it uses ``sed`` to substitute final ``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. .. note:: - You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir`` + You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. You can find the Yocto Project - version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/`` + version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default`` directory. -.. _structure-build-conf-sanity_info: - -``build/cache/sanity_info`` ---------------------------- - -This file indicates the state of the sanity checks and is created during -the build. - .. _structure-build-downloads: ``build/downloads/`` @@ -336,7 +343,7 @@ the build. This directory contains downloaded upstream source tarballs. You can reuse the directory for multiple builds or move the directory to another location. You can control the location of this directory through the -``DL_DIR`` variable. +:term:`DL_DIR` variable. .. _structure-build-sstate-cache: @@ -346,7 +353,7 @@ location. You can control the location of this directory through the This directory contains the shared state cache. You can reuse the directory for multiple builds or move the directory to another location. You can control the location of this directory through the -``SSTATE_DIR`` variable. +:term:`SSTATE_DIR` variable. .. _structure-build-tmp: @@ -366,14 +373,15 @@ remove the ``build/sstate-cache`` directory. .. _structure-build-tmp-buildstats: ``build/tmp/buildstats/`` -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ -This directory stores the build statistics. +This directory stores the build statistics as generated by the +:ref:`ref-classes-buildstats` class. .. _structure-build-tmp-cache: ``build/tmp/cache/`` --------------------- +~~~~~~~~~~~~~~~~~~~~ When BitBake parses the metadata (recipes and configuration files), it caches the results in ``build/tmp/cache/`` to speed up future builds. @@ -389,7 +397,7 @@ cache is reused. If the file has changed, it is reparsed. .. _structure-build-tmp-deploy: ``build/tmp/deploy/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This directory contains any "end result" output from the OpenEmbedded build process. The :term:`DEPLOY_DIR` variable points @@ -402,7 +410,7 @@ Project Overview and Concepts Manual. .. _structure-build-tmp-deploy-deb: ``build/tmp/deploy/deb/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives any ``.deb`` packages produced by the build process. The packages are sorted into feeds for different architecture @@ -411,7 +419,7 @@ types. .. _structure-build-tmp-deploy-rpm: ``build/tmp/deploy/rpm/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives any ``.rpm`` packages produced by the build process. The packages are sorted into feeds for different architecture @@ -420,27 +428,27 @@ types. .. _structure-build-tmp-deploy-ipk: ``build/tmp/deploy/ipk/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives ``.ipk`` packages produced by the build process. .. _structure-build-tmp-deploy-licenses: ``build/tmp/deploy/licenses/`` ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives package licensing information. For example, the directory contains sub-directories for ``bash``, ``busybox``, and ``glibc`` (among others) that in turn contain appropriate ``COPYING`` license files with other licensing information. For information on licensing, see the -":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" +":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. .. _structure-build-tmp-deploy-images: ``build/tmp/deploy/images/`` ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This directory is populated with the basic output objects of the build (think of them as the "generated artifacts" of the build process), @@ -467,7 +475,7 @@ the kernel files:: .. _structure-build-tmp-deploy-sdk: ``build/tmp/deploy/sdk/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ The OpenEmbedded build system creates this directory to hold toolchain installer scripts which, when executed, install the sysroot that matches @@ -479,7 +487,7 @@ Software Development Kit (eSDK) manual. .. _structure-build-tmp-sstate-control: ``build/tmp/sstate-control/`` ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OpenEmbedded build system uses this directory for the shared state manifest files. The shared state code uses these files to record the @@ -492,7 +500,7 @@ another. .. _structure-build-tmp-sysroots-components: ``build/tmp/sysroots-components/`` ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This directory is the location of the sysroot contents that the task :ref:`ref-tasks-prepare_recipe_sysroot` @@ -507,11 +515,11 @@ should be automatic, and recipes should not directly reference .. _structure-build-tmp-sysroots: ``build/tmp/sysroots/`` ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Previous versions of the OpenEmbedded build system used to create a -global shared sysroot per machine along with a native sysroot. Beginning -with the 2.3 version of the Yocto Project, sysroots exist in +global shared sysroot per machine along with a native sysroot. Since +the 2.3 version of the Yocto Project, there are sysroots in recipe-specific :term:`WORKDIR` directories. Thus, the ``build/tmp/sysroots/`` directory is unused. @@ -525,12 +533,12 @@ recipe-specific :term:`WORKDIR` directories. Thus, the .. _structure-build-tmp-stamps: ``build/tmp/stamps/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This directory holds information that BitBake uses for accounting purposes to track what tasks have run and when they have run. The directory is sub-divided by architecture, package name, and version. -Following is an example:: +Here is an example:: stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do @@ -545,17 +553,17 @@ section in the Yocto Project Overview and Concepts Manual. .. _structure-build-tmp-log: ``build/tmp/log/`` ------------------- +~~~~~~~~~~~~~~~~~~ This directory contains general logs that are not otherwise placed using -the package's ``WORKDIR``. Examples of logs are the output from the +the package's :term:`WORKDIR`. Examples of logs are the output from the ``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not necessarily mean this directory is created. .. _structure-build-tmp-work: ``build/tmp/work/`` -------------------- +~~~~~~~~~~~~~~~~~~~ This directory contains architecture-specific work sub-directories for packages built by BitBake. All tasks execute from the appropriate work @@ -569,15 +577,15 @@ It is worth considering the structure of a typical work directory. As an example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` built within the Yocto Project. For this package, a work directory of ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred -to as the ``WORKDIR``, is created. Within this directory, the source is +to as the :term:`WORKDIR`, is created. Within this directory, the source is unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. -(See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in +(See the ":ref:`dev-manual/quilt:using quilt in your workflow`" section in the Yocto Project Development Tasks Manual for more information.) Within the ``linux-qemux86-standard-build`` directory, standard Quilt directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and standard Quilt commands can be used. -There are other directories generated within ``WORKDIR``. The most +There are other directories generated within :term:`WORKDIR`. The most important directory is ``WORKDIR/temp/``, which has log files for each task (``log.do_*.pid``) and contains the scripts BitBake runs for each task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make @@ -587,9 +595,9 @@ install" places its output that is then split into sub-packages within .. _structure-build-tmp-work-tunearch-recipename-version: ``build/tmp/work/tunearch/recipename/version/`` ------------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The recipe work directory - ``${WORKDIR}``. +The recipe work directory --- ``${WORKDIR}``. As described earlier in the ":ref:`structure-build-tmp-sysroots`" section, @@ -601,7 +609,7 @@ constructed using the architecture of the given build (e.g. name, and the version of the recipe (i.e. :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). -A number of key subdirectories exist within each recipe work directory: +Here are key subdirectories within each recipe work directory: - ``${WORKDIR}/temp``: Contains the log files of each task executed for this recipe, the "run" files for each executed task, which contain @@ -623,8 +631,8 @@ A number of key subdirectories exist within each recipe work directory: split into individual packages. - ``${WORKDIR}/packages-split``: Contains the output of the - ``do_package`` task after the output has been split into individual - packages. Subdirectories exist for each individual package created by + :ref:`ref-tasks-package` task after the output has been split into individual + packages. There are subdirectories for each individual package created by the recipe. - ``${WORKDIR}/recipe-sysroot``: A directory populated with the target @@ -645,7 +653,7 @@ A number of key subdirectories exist within each recipe work directory: .. _structure-build-work-shared: ``build/tmp/work-shared/`` --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ For efficiency, the OpenEmbedded build system creates and uses this directory to hold recipes that share a work directory with other @@ -654,29 +662,30 @@ recipes. In practice, this is only used for ``gcc`` and its variants .. _structure-meta: -The Metadata - ``meta/`` -======================== +The Metadata --- ``meta/`` +========================== As mentioned previously, :term:`Metadata` is the core of the Yocto Project. Metadata has several important subdivisions: .. _structure-meta-classes: -``meta/classes/`` ------------------ +``meta/classes*/`` +------------------ -This directory contains the ``*.bbclass`` files. Class files are used to +These directories contain the ``*.bbclass`` files. Class files are used to abstract common code so it can be reused by multiple packages. Every -package inherits the ``base.bbclass`` file. Examples of other important -classes are ``autotools.bbclass``, which in theory allows any +package inherits the :ref:`ref-classes-base` file. Examples of other important +classes are :ref:`ref-classes-autotools`, which in theory allows any Autotool-enabled package to work with the Yocto Project with minimal -effort. Another example is ``kernel.bbclass`` that contains common code +effort. Another example is :ref:`ref-classes-kernel` that contains common code and functions for working with the Linux kernel. Functions like image generation or packaging also have their specific class files such as -``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. +:ref:`ref-classes-image`, :ref:`ref-classes-rootfs*` and +:ref:`package*.bbclass <ref-classes-package>`. For reference information on classes, see the -":ref:`ref-manual/classes:Classes`" chapter. +":doc:`/ref-manual/classes`" chapter. .. _structure-meta-conf: @@ -694,7 +703,7 @@ distribution configuration file. .. _structure-meta-conf-machine: ``meta/conf/machine/`` ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ This directory contains all the machine configuration files. If you set ``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a @@ -705,11 +714,11 @@ support for a new machine to the Yocto Project, look in this directory. .. _structure-meta-conf-distro: ``meta/conf/distro/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ The contents of this directory controls any distribution-specific configurations. For the Yocto Project, the ``defaultsetup.conf`` is the -main file here. This directory includes the versions and the ``SRCDATE`` +main file here. This directory includes the versions and the :term:`SRCDATE` definitions for applications that are configured here. An example of an alternative configuration might be ``poky-bleeding.conf``. Although this file mainly inherits its configuration from Poky. @@ -717,7 +726,7 @@ file mainly inherits its configuration from Poky. .. _structure-meta-conf-machine-sdk: ``meta/conf/machine-sdk/`` --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ The OpenEmbedded build system searches this directory for configuration files that correspond to the value of @@ -742,7 +751,9 @@ and lists of files and directories with known permissions. ------------- This directory contains OpenEmbedded Python library code used during the -build process. +build process. It is enabled via the ``addpylib`` directive in +``meta/conf/local.conf``. For more information, see +:ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`. .. _structure-meta-recipes-bsp: |