diff options
author | Andrew Geissler <geissonator@yahoo.com> | 2020-11-03 03:44:49 +0300 |
---|---|---|
committer | Andrew Geissler <geissonator@yahoo.com> | 2020-11-03 23:32:06 +0300 |
commit | 4873add6e11c1bd421c83cd08df589f1184aa673 (patch) | |
tree | aec4845be29329cca2a0b2d7c8f94249e48ed067 /poky/documentation/ref-manual/ref-structure.xml | |
parent | 56a8292be03a7cb27f3b3ad762f4779e7e5ff47d (diff) | |
download | openbmc-4873add6e11c1bd421c83cd08df589f1184aa673.tar.xz |
Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
Diffstat (limited to 'poky/documentation/ref-manual/ref-structure.xml')
-rw-r--r-- | poky/documentation/ref-manual/ref-structure.xml | 1123 |
1 files changed, 1123 insertions, 0 deletions
diff --git a/poky/documentation/ref-manual/ref-structure.xml b/poky/documentation/ref-manual/ref-structure.xml new file mode 100644 index 000000000..8588e9c2d --- /dev/null +++ b/poky/documentation/ref-manual/ref-structure.xml @@ -0,0 +1,1123 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<chapter id='ref-structure'> + +<title>Source Directory Structure</title> + +<para> + The <link linkend='source-directory'>Source Directory</link> + consists of numerous files, directories and subdirectories; + understanding their locations and contents is key to using the + Yocto Project effectively. + This chapter describes the Source Directory and gives information about + those files and directories. +</para> + +<para> + For information on how to establish a local Source Directory on your + development system, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" + section in the Yocto Project Development Tasks Manual. +</para> + + <note> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + Be sure that the Source Directory you use does not contain these types + of names. + </note> + +<section id='structure-core'> + <title>Top-Level Core Components</title> + + <para> + This section describes the top-level components of the + <link linkend='source-directory'>Source Directory</link>. + </para> + + <section id='structure-core-bitbake'> + <title><filename>bitbake/</filename></title> + + <para> + This directory includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from + the BitBake project. + BitBake, a + <link linkend='metadata'>Metadata</link> + interpreter, reads the Yocto Project Metadata and runs the tasks + defined by that data. + Failures are usually caused by errors in your Metadata and not from BitBake itself; + consequently, most users do not need to worry about BitBake. + </para> + + <para> + When you run the <filename>bitbake</filename> command, the + main BitBake executable (which resides in the + <filename>bitbake/bin/</filename> directory) starts. + Sourcing the environment setup script (i.e. + <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>) + places the <filename>scripts/</filename> and + <filename>bitbake/bin/</filename> directories (in that order) into + the shell's <filename>PATH</filename> environment variable. + </para> + + <para> + For more information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + </section> + + <section id='structure-core-build'> + <title><filename>build/</filename></title> + + <para> + 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 + <link linkend='build-directory'>Build Directory</link> + is created initially when you <filename>source</filename> + the OpenEmbedded build environment setup script + (i.e. + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). + </para> + + <para> + It is also possible to place output and configuration + files in a directory separate from the + <link linkend='source-directory'>Source Directory</link> + by providing a directory name when you <filename>source</filename> + the setup script. + For information on separating output from your local + Source Directory files (commonly described as an "out of tree" build), see the + "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>" + section. + </para> + </section> + + <section id='handbook'> + <title><filename>documentation/</filename></title> + + <para> + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in its own sub-folder; + for example, the files for this reference manual reside in + the <filename>ref-manual/</filename> directory. + </para> + </section> + + <section id='structure-core-meta'> + <title><filename>meta/</filename></title> + + <para> + This directory contains the minimal, underlying OpenEmbedded-Core metadata. + The directory holds recipes, common classes, and machine + configuration for strictly emulated targets (<filename>qemux86</filename>, + <filename>qemuarm</filename>, and so forth.) + </para> + </section> + + <section id='structure-core-meta-poky'> + <title><filename>meta-poky/</filename></title> + + <para> + Designed above the <filename>meta/</filename> content, this directory + adds just enough metadata to define the Poky reference distribution. + </para> + </section> + + <section id='structure-core-meta-yocto-bsp'> + <title><filename>meta-yocto-bsp/</filename></title> + + <para> + This directory contains the Yocto Project reference + hardware Board Support Packages (BSPs). + For more information on BSPs, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </para> + </section> + + <section id='structure-meta-selftest'> + <title><filename>meta-selftest/</filename></title> + + <para> + This directory adds additional recipes and append files + used by the OpenEmbedded selftests to verify the behavior + of the build system. + You do not have to add this layer to your + <filename>bblayers.conf</filename> file unless you want to run the + selftests. + </para> + </section> + + <section id='structure-meta-skeleton'> + <title><filename>meta-skeleton/</filename></title> + + <para> + This directory contains template recipes for BSP and kernel development. + </para> + </section> + + <section id='structure-core-scripts'> + <title><filename>scripts/</filename></title> + + <para> + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link> + script prepends this directory to the shell's + <filename>PATH</filename> environment variable. + </para> + + <para> + The <filename>scripts</filename> directory has useful scripts that assist in contributing + back to the Yocto Project, such as <filename>create-pull-request</filename> and + <filename>send-pull-request</filename>. + </para> + </section> + + <section id='structure-core-script'> + <title><filename>&OE_INIT_FILE;</filename></title> + + <para> + This script sets up the OpenEmbedded build environment. + Running this script with the <filename>source</filename> command in + a shell makes changes to <filename>PATH</filename> and sets other + core BitBake variables based on the current working directory. + You need to run an environment setup script before running BitBake + commands. + The script uses other scripts within the + <filename>scripts</filename> directory to do the bulk of the work. + </para> + + <para> + When you run this script, your Yocto Project environment is set + up, a + <link linkend='build-directory'>Build Directory</link> + 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: + <literallayout class='monospaced'> + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + meta-ide-support + + You can also run generated qemu images with a command like 'runqemu qemux86-64' + </literallayout> + The default output of the <filename>oe-init-build-env</filename> script + is from the <filename>conf-notes.txt</filename> file, which is found in the + <filename>meta-poky</filename> directory within the + <link linkend='source-directory'>Source Directory</link>. + If you design a custom distribution, you can include your own version + of this configuration file to mention the targets defined by your + distribution. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Tasks Manual for more + information. + </para> + + <para> + By default, running this script without a Build Directory + argument creates the <filename>build/</filename> directory + in your current working directory. + If you provide a Build Directory argument when you + <filename>source</filename> 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 + <filename>mybuilds/</filename> that is outside of the + <link linkend='source-directory'>Source Directory</link>: + <literallayout class='monospaced'> + $ source &OE_INIT_FILE; ~/mybuilds + </literallayout> + The OpenEmbedded build system uses the template configuration + files, which are found by default in the + <filename>meta-poky/conf/</filename> directory in the + Source Directory. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" + section in the Yocto Project Development Tasks Manual for more + information. + <note> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the <filename>&OE_INIT_FILE;</filename> script + from a Source Directory that contains spaces in either the filenames + or directory names, the script returns an error indicating no such + file or directory. + Be sure to use a Source Directory free of names containing spaces. + </note> + </para> + </section> + + <section id='structure-basic-top-level'> + <title><filename>LICENSE, README, and README.hardware</filename></title> + + <para> + These files are standard top-level files. + </para> + </section> +</section> + +<section id='structure-build'> + <title>The Build Directory - <filename>build/</filename></title> + + <para> + The OpenEmbedded build system creates the + <link linkend='build-directory'>Build Directory</link> + when you run the build environment setup script + <link +linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>. + If you do not give the Build Directory a specific name when you run + the setup script, the name defaults to <filename>build/</filename>. + </para> + + <para> + For subsequent parsing and processing, the name of the Build + directory is available via the + <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable. + </para> + + <section id='structure-build-buildhistory'> + <title><filename>build/buildhistory/</filename></title> + + <para> + The OpenEmbedded build system creates this directory when you + enable build history via the <filename>buildhistory</filename> class file. + The directory organizes build information into image, packages, and + SDK subdirectories. + For information on the build history feature, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='structure-build-conf-local.conf'> + <title><filename>build/conf/local.conf</filename></title> + + <para> + This configuration file contains all the local user configurations + for your build environment. + The <filename>local.conf</filename> file contains documentation on + the various configuration options. + Any variable set here overrides any variable set elsewhere within + the environment unless that variable is hard-coded within a file + (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but such + variables are relatively rare. + </para> + + <para> + At a minimum, you would normally edit this file to select the target + <filename><link linkend='var-MACHINE'>MACHINE</link></filename>, + which package types you wish to use + (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), + and the location from which you want to access downloaded files + (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>). + </para> + + <para> + If <filename>local.conf</filename> is not present when you + start the build, the OpenEmbedded build system creates it from + <filename>local.conf.sample</filename> when + you <filename>source</filename> the top-level build environment + setup script + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>. + </para> + + <para> + The source <filename>local.conf.sample</filename> file used + depends on the <filename>$TEMPLATECONF</filename> script variable, + which defaults to <filename>meta-poky/conf/</filename> + when you are building from the Yocto Project development + environment, and to <filename>meta/conf/</filename> when + you are building from the OpenEmbedded-Core environment. + Because the script variable points to the source of the + <filename>local.conf.sample</filename> 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: + <literallayout class='monospaced'> + TEMPLATECONF=<replaceable>your_layer</replaceable>/conf + </literallayout> + Once the build process gets the sample file, it uses + <filename>sed</filename> to substitute final + <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> + values for all <filename>##OEROOT##</filename> values. + <note> + You can see how the <filename>TEMPLATECONF</filename> variable + is used by looking at the + <filename>scripts/oe-setup-builddir</filename> script in the + <link linkend='source-directory'>Source Directory</link>. + You can find the Yocto Project version of the + <filename>local.conf.sample</filename> file in the + <filename>meta-poky/conf</filename> directory. + </note> + </para> + </section> + + <section id='structure-build-conf-bblayers.conf'> + <title><filename>build/conf/bblayers.conf</filename></title> + + <para> + This configuration file defines + <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>, + which are directory trees, traversed (or walked) by BitBake. + The <filename>bblayers.conf</filename> file uses the + <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> + variable to list the layers BitBake tries to find. + </para> + + <para> + If <filename>bblayers.conf</filename> is not present when you + start the build, the OpenEmbedded build system creates it from + <filename>bblayers.conf.sample</filename> when + you <filename>source</filename> the top-level build environment + setup script (i.e. + <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). + </para> + + <para> + As with the <filename>local.conf</filename> file, + the source <filename>bblayers.conf.sample</filename> file used + depends on the <filename>$TEMPLATECONF</filename> script variable, + which defaults to <filename>meta-poky/conf/</filename> + when you are building from the Yocto Project development + environment, and to <filename>meta/conf/</filename> when + you are building from the OpenEmbedded-Core environment. + Because the script variable points to the source of the + <filename>bblayers.conf.sample</filename> 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: + <literallayout class='monospaced'> + TEMPLATECONF=<replaceable>your_layer</replaceable>/conf + </literallayout> + Once the build process gets the sample file, it uses + <filename>sed</filename> to substitute final + <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> + values for all <filename>##OEROOT##</filename> values. + <note> + You can see how the <filename>TEMPLATECONF</filename> variable + <filename>scripts/oe-setup-builddir</filename> script in the + <link linkend='source-directory'>Source Directory</link>. + You can find the Yocto Project version of the + <filename>bblayers.conf.sample</filename> file in the + <filename>meta-poky/conf/</filename> directory. + </note> + </para> + </section> + + <section id='structure-build-conf-sanity_info'> + <title><filename>build/cache/sanity_info</filename></title> + + <para> + This file indicates the state of the sanity checks and is created + during the build. + </para> + </section> + + <section id='structure-build-downloads'> + <title><filename>build/downloads/</filename></title> + + <para> + 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 + <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable. + </para> + </section> + + <section id='structure-build-sstate-cache'> + <title><filename>build/sstate-cache/</filename></title> + + <para> + 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 + <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable. + </para> + </section> + + <section id='structure-build-tmp'> + <title><filename>build/tmp/</filename></title> + + <para> + The OpenEmbedded build system creates and uses this directory + for all the build system's output. + The + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + variable points to this directory. + </para> + + <para> + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch + (other than the downloads), you can remove everything in the + <filename>tmp</filename> directory or get rid of the + directory completely. + If you do, you should also completely remove the + <filename>build/sstate-cache</filename> directory. + </para> + </section> + + <section id='structure-build-tmp-buildstats'> + <title><filename>build/tmp/buildstats/</filename></title> + + <para> + This directory stores the build statistics. + </para> + </section> + + <section id='structure-build-tmp-cache'> + <title><filename>build/tmp/cache/</filename></title> + + <para> + When BitBake parses the metadata (recipes and configuration files), + it caches the results in <filename>build/tmp/cache/</filename> + to speed up future builds. + The results are stored on a per-machine basis. + </para> + + <para> + During subsequent builds, BitBake checks each recipe (together + with, for example, any files included or appended to it) to see + if they have been modified. + Changes can be detected, for example, through file modification + time (mtime) changes and hashing of file contents. + If no changes to the file are detected, then the parsed result + stored in the cache is reused. + If the file has changed, it is reparsed. + </para> + </section> + + <section id='structure-build-tmp-deploy'> + <title><filename>build/tmp/deploy/</filename></title> + + <para> + This directory contains any "end result" output from the + OpenEmbedded build process. + The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link> + variable points to this directory. + For more detail on the contents of the <filename>deploy</filename> + directory, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>" + and + "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>" + sections in the Yocto Project Overview and Concepts Manual. + </para> + </section> + + <section id='structure-build-tmp-deploy-deb'> + <title><filename>build/tmp/deploy/deb/</filename></title> + + <para> + This directory receives any <filename>.deb</filename> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </para> + </section> + + <section id='structure-build-tmp-deploy-rpm'> + <title><filename>build/tmp/deploy/rpm/</filename></title> + + <para> + This directory receives any <filename>.rpm</filename> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </para> + </section> + + <section id='structure-build-tmp-deploy-ipk'> + <title><filename>build/tmp/deploy/ipk/</filename></title> + + <para> + This directory receives <filename>.ipk</filename> packages produced by + the build process. + </para> + </section> + + <section id='structure-build-tmp-deploy-licenses'> + <title><filename>build/tmp/deploy/licenses/</filename></title> + + <para> + This directory receives package licensing information. + For example, the directory contains sub-directories for <filename>bash</filename>, + <filename>busybox</filename>, and <filename>glibc</filename> (among others) that in turn + contain appropriate <filename>COPYING</filename> license files with other licensing information. + For information on licensing, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='structure-build-tmp-deploy-images'> + <title><filename>build/tmp/deploy/images/</filename></title> + + <para> + This directory is populated with the basic output objects of the + build (think of them as the "generated artifacts" of the build process), + including things like the boot loader image, kernel, root filesystem and more. + If you want to flash the resulting image from a build onto a device, + look here for the necessary components. + </para> + + <para> + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + <filename>core-image-*</filename>). + However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + </para> + + <para> + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + <literallayout class='monospaced'> + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + </literallayout> + </para> + </section> + + <section id='structure-build-tmp-deploy-sdk'> + <title><filename>build/tmp/deploy/sdk/</filename></title> + + <para> + The OpenEmbedded build system creates this directory to hold + toolchain installer scripts which, when executed, install the + sysroot that matches your target hardware. + You can find out more about these installers in the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + </para> + </section> + + <section id='structure-build-tmp-sstate-control'> + <title><filename>build/tmp/sstate-control/</filename></title> + + <para> + The OpenEmbedded build system uses this directory for the + shared state manifest files. + The shared state code uses these files to record the files + installed by each sstate task so that the files can be removed + when cleaning the recipe or when a newer version is about to + be installed. + The build system also uses the manifests to detect and produce + a warning when files from one task are overwriting those from + another. + </para> + </section> + + <section id='structure-build-tmp-sysroots-components'> + <title><filename>build/tmp/sysroots-components/</filename></title> + + <para> + This directory is the location of the sysroot contents that the + task + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + links or copies into the recipe-specific sysroot for each + recipe listed in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + Population of this directory is handled through shared state, while + the path is specified by the + <link linkend='var-COMPONENTS_DIR'><filename>COMPONENTS_DIR</filename></link> + variable. Apart from a few unusual circumstances, handling of the + <filename>sysroots-components</filename> directory should be + automatic, and recipes should not directly reference + <filename>build/tmp/sysroots-components</filename>. + </para> + </section> + + <section id='structure-build-tmp-sysroots'> + <title><filename>build/tmp/sysroots/</filename></title> + + <para> + Previous versions of the OpenEmbedded build system used to + create a global shared sysroot per machine along with a native + sysroot. + Beginning with the &DISTRO; version of the Yocto Project, + sysroots exist in recipe-specific + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + directories. + Thus, the <filename>build/tmp/sysroots/</filename> directory + is unused. + <note> + The <filename>build/tmp/sysroots/</filename> directory + can still be populated using the + <filename>bitbake build-sysroots</filename> command and can + be used for compatibility in some cases. + However, in general it is not recommended to populate + this directory. + Individual recipe-specific sysroots should be used. + </note> + </para> + </section> + + <section id='structure-build-tmp-stamps'> + <title><filename>build/tmp/stamps/</filename></title> + + <para> + 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: + <literallayout class='monospaced'> + stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do + </literallayout> + Although the files in the directory are empty of data, + BitBake uses the filenames and timestamps for tracking purposes. + </para> + + <para> + For information on how BitBake uses stamp files to determine if + a task should be rerun, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" + section in the Yocto Project Overview and Concepts Manual. + </para> + </section> + + <section id='structure-build-tmp-log'> + <title><filename>build/tmp/log/</filename></title> + + <para> + This directory contains general logs that are not otherwise placed using the + package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. + Examples of logs are the output from the + <filename>do_check_pkg</filename> or + <filename>do_distro_check</filename> tasks. + Running a build does not necessarily mean this directory is created. + </para> + </section> + + <section id='structure-build-tmp-work'> + <title><filename>build/tmp/work/</filename></title> + + <para> + This directory contains architecture-specific work sub-directories + for packages built by BitBake. + All tasks execute from the appropriate work directory. + For example, the source for a particular package is unpacked, + patched, configured and compiled all within its own work directory. + Within the work directory, organization is based on the package group + and version for which the source is being compiled + as defined by the + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. + </para> + + <para> + It is worth considering the structure of a typical work directory. + As an example, consider <filename>linux-yocto-kernel-3.0</filename> + on the machine <filename>qemux86</filename> + built within the Yocto Project. + For this package, a work directory of + <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....></filename>, + referred to as the <filename>WORKDIR</filename>, is created. + Within this directory, the source is unpacked to + <filename>linux-qemux86-standard-build</filename> and then patched by Quilt. + (See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using Quilt in Your Workflow</ulink>" + section in the Yocto Project Development Tasks Manual for more + information.) + Within the <filename>linux-qemux86-standard-build</filename> directory, + standard Quilt directories <filename>linux-3.0/patches</filename> + and <filename>linux-3.0/.pc</filename> are created, + and standard Quilt commands can be used. + </para> + + <para> + There are other directories generated within <filename>WORKDIR</filename>. + The most important directory is <filename>WORKDIR/temp/</filename>, + which has log files for each task (<filename>log.do_*.pid</filename>) + and contains the scripts BitBake runs for each task + (<filename>run.do_*.pid</filename>). + The <filename>WORKDIR/image/</filename> directory is where "make + install" places its output that is then split into sub-packages + within <filename>WORKDIR/packages-split/</filename>. + </para> + </section> + + <section id='structure-build-tmp-work-tunearch-recipename-version'> + <title><filename>build/tmp/work/<replaceable>tunearch</replaceable>/<replaceable>recipename</replaceable>/<replaceable>version</replaceable>/</filename></title> + + <para> + The recipe work directory - <filename>${WORKDIR}</filename>. + </para> + + <para> + As described earlier in the + "<link linkend='structure-build-tmp-sysroots'><filename>build/tmp/sysroots/</filename></link>" + section, beginning with the &DISTRO; release of the Yocto + Project, the OpenEmbedded build system builds each recipe in its + own work directory (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + The path to the work directory is constructed using the + architecture of the given build (e.g. + <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>, + <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>, + or "allarch"), the recipe name, and the version of the recipe (i.e. + <link linkend='var-PE'><filename>PE</filename></link><filename>:</filename><link linkend='var-PV'><filename>PV</filename></link><filename>-</filename><link linkend='var-PR'><filename>PR</filename></link>). + </para> + + <para> + A number of key subdirectories exist within each recipe + work directory: + <itemizedlist> + <listitem><para> + <filename>${WORKDIR}/temp</filename>: + Contains the log files of each task executed for this + recipe, the "run" files for each executed task, which + contain the code run, and a + <filename>log.task_order</filename> file, which lists the + order in which tasks were executed. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/image</filename>: + Contains the output of the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task, which corresponds to the + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + variable in that task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/pseudo</filename>: + Contains the pseudo database and log for any tasks executed + under pseudo for the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/sysroot-destdir</filename>: + Contains the output of the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/package</filename>: + Contains the output of the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task before the output is split into individual packages. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/packages-split</filename>: + Contains the output of the <filename>do_package</filename> + task after the output has been split into individual + packages. + Subdirectories exist for each individual package created + by the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot</filename>: + A directory populated with the target dependencies of the + recipe. + This directory looks like the target filesystem and + contains libraries that the recipe might need to link + against (e.g. the C library). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot-native</filename>: + A directory populated with the native dependencies of the + recipe. + This directory contains the tools the recipe needs to build + (e.g. the compiler, Autoconf, libtool, and so forth). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/build</filename>: + This subdirectory applies only to recipes that support + builds where the source is separate from the + build artifacts. + The OpenEmbedded build system uses this directory as a + separate build directory (i.e. + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='structure-build-work-shared'> + <title><filename>build/tmp/work-shared/</filename></title> + + <para> + For efficiency, the OpenEmbedded build system creates and uses + this directory to hold recipes that share a work directory with + other recipes. + In practice, this is only used for <filename>gcc</filename> + and its variants (e.g. <filename>gcc-cross</filename>, + <filename>libgcc</filename>, <filename>gcc-runtime</filename>, + and so forth). + </para> + </section> +</section> + +<section id='structure-meta'> + <title>The Metadata - <filename>meta/</filename></title> + + <para> + As mentioned previously, + <link linkend='metadata'>Metadata</link> is the core + of the Yocto Project. + Metadata has several important subdivisions: + </para> + + <section id='structure-meta-classes'> + <title><filename>meta/classes/</filename></title> + + <para> + This directory contains the <filename>*.bbclass</filename> files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the <filename>base.bbclass</filename> file. + Examples of other important classes are <filename>autotools.bbclass</filename>, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is <filename>kernel.bbclass</filename> 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 <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and + <filename>package*.bbclass</filename>. + </para> + + <para> + For reference information on classes, see the + "<link linkend='ref-classes'>Classes</link>" chapter. + </para> + </section> + + <section id='structure-meta-conf'> + <title><filename>meta/conf/</filename></title> + + <para> + This directory contains the core set of configuration files that start from + <filename>bitbake.conf</filename> and from which all other configuration + files are included. + See the include statements at the end of the + <filename>bitbake.conf</filename> file and you will note that even + <filename>local.conf</filename> is loaded from there. + While <filename>bitbake.conf</filename> sets up the defaults, you can often override + these by using the (<filename>local.conf</filename>) file, machine file or + the distribution configuration file. + </para> + </section> + + <section id='structure-meta-conf-machine'> + <title><filename>meta/conf/machine/</filename></title> + + <para> + This directory contains all the machine configuration files. + If you set <filename>MACHINE = "qemux86"</filename>, + the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this + directory. + The <filename>include</filename> directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + </para> + </section> + + <section id='structure-meta-conf-distro'> + <title><filename>meta/conf/distro/</filename></title> + + <para> + The contents of this directory controls any distribution-specific + configurations. + For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here. + This directory includes the versions and the + <filename>SRCDATE</filename> definitions for applications that are configured here. + An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>. + Although this file mainly inherits its configuration from Poky. + </para> + </section> + + <section id='structure-meta-conf-machine-sdk'> + <title><filename>meta/conf/machine-sdk/</filename></title> + + <para> + The OpenEmbedded build system searches this directory for + configuration files that correspond to the value of + <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>. + By default, 32-bit and 64-bit x86 files ship with the Yocto + Project that support some SDK hosts. + However, it is possible to extend that support to other SDK hosts + by adding additional configuration files in this subdirectory + within another layer. + </para> + </section> + + <section id='structure-meta-files'> + <title><filename>meta/files/</filename></title> + + <para> + This directory contains common license files and several text files + used by the build system. + The text files contain minimal device information and + lists of files and directories with known permissions. + </para> + </section> + + <section id='structure-meta-lib'> + <title><filename>meta/lib/</filename></title> + + <para> + This directory contains OpenEmbedded Python library code + used during the build process. + </para> + </section> + + <section id='structure-meta-recipes-bsp'> + <title><filename>meta/recipes-bsp/</filename></title> + + <para> + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + </para> + </section> + + <section id='structure-meta-recipes-connectivity'> + <title><filename>meta/recipes-connectivity/</filename></title> + + <para> + This directory contains libraries and applications related to communication with other devices. + </para> + </section> + + <section id='structure-meta-recipes-core'> + <title><filename>meta/recipes-core/</filename></title> + + <para> + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + </para> + </section> + + <section id='structure-meta-recipes-devtools'> + <title><filename>meta/recipes-devtools/</filename></title> + + <para> + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + </para> + </section> + + <section id='structure-meta-recipes-extended'> + <title><filename>meta/recipes-extended/</filename></title> + + <para> + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + </para> + </section> + + <section id='structure-meta-recipes-gnome'> + <title><filename>meta/recipes-gnome/</filename></title> + + <para> + This directory contains all things related to the GTK+ application framework. + </para> + </section> + + <section id='structure-meta-recipes-graphics'> + <title><filename>meta/recipes-graphics/</filename></title> + + <para> + This directory contains X and other graphically related system libraries. + </para> + </section> + + <section id='structure-meta-recipes-kernel'> + <title><filename>meta/recipes-kernel/</filename></title> + + <para> + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + </para> + </section> + + <section id='structure-meta-recipes-lsb4'> + <title><filename>meta/recipes-lsb4/</filename></title> + + <para> + This directory contains recipes specifically added to support + the Linux Standard Base (LSB) version 4.x. + </para> + </section> + + <section id='structure-meta-recipes-multimedia'> + <title><filename>meta/recipes-multimedia/</filename></title> + + <para> + This directory contains codecs and support utilities for audio, images and video. + </para> + </section> + + <section id='structure-meta-recipes-rt'> + <title><filename>meta/recipes-rt/</filename></title> + + <para> + This directory contains package and image recipes for using and testing + the <filename>PREEMPT_RT</filename> kernel. + </para> + </section> + + <section id='structure-meta-recipes-sato'> + <title><filename>meta/recipes-sato/</filename></title> + + <para> + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + </para> + </section> + + <section id='structure-meta-recipes-support'> + <title><filename>meta/recipes-support/</filename></title> + + <para> + This directory contains recipes used by other recipes, but that are + not directly included in images (i.e. dependencies of other + recipes). + </para> + </section> + + <section id='structure-meta-site'> + <title><filename>meta/site/</filename></title> + + <para> + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + </para> + </section> + + <section id='structure-meta-recipes-txt'> + <title><filename>meta/recipes.txt</filename></title> + + <para> + This file is a description of the contents of <filename>recipes-*</filename>. + </para> + </section> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |