| <!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; ] > |
| |
| <chapter id='ref-structure'> |
| |
| <title>Source Directory Structure</title> |
| |
| <para> |
| The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. |
| Understanding them and knowing where they are located is key to using the Yocto Project well. |
| This chapter describes the Source Directory and gives information about the various |
| 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;#getting-setup'>Getting Set Up</ulink>" |
| section in the Yocto Project Development 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| </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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> |
| interpreter, reads the Yocto Project Metadata and runs the tasks |
| defined by that data. |
| Failures are usually from the 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 an environment setup script (e.g. |
| <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link> |
| or |
| <link linkend="structure-memres-core-script"><filename>oe-init-build-env-memres</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 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 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> |
| or |
| <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). |
| </para> |
| |
| <para> |
| It is also possible to place output and configuration |
| files in a directory separate from the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| by providing a directory name when you <filename>source</filename> |
| the setup script. |
| For information on separating output from your local |
| Source Directory files, see the |
| "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> |
| and |
| "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>" |
| sections. |
| </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 a sub-folder. |
| For example, the files for this 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 OpenEmbedded Core metadata. |
| The directory holds recipes, common classes, and machine |
| configuration for 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> |
| This directory contains the configuration for 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. |
| </para> |
| |
| <para> |
| 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> |
| and |
| <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link> |
| scripts append 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 is one of two scripts that set up the OpenEmbedded build |
| environment. |
| For information on the other script, see the |
| "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>" |
| section. |
| </para> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| is created, your working directory becomes the Build Directory, |
| and you are presented with a list of common BitBake targets. |
| 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' |
| </literallayout> |
| The script gets its default list of common targets from the |
| <filename>conf-notes.txt</filename> file, which is found in the |
| <filename>meta-poky</filename> directory within the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| Should you have custom distributions, it is very easy to modify |
| this configuration file to include your targets for 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 Manual for more |
| information. |
| </para> |
| |
| <para> |
| By default, running this script without a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: |
| <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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 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 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-memres-core-script'> |
| <title><filename>oe-init-build-env-memres</filename></title> |
| |
| <para> |
| This script is one of two scripts that set up the OpenEmbedded |
| build environment. |
| Aside from setting up the environment, this script starts a |
| memory-resident BitBake server. |
| For information on the other setup script, see the |
| "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>" |
| section. |
| </para> |
| |
| <para> |
| Memory-resident BitBake resides in memory until you specifically |
| remove it using the following BitBake command: |
| <literallayout class='monospaced'> |
| $ bitbake -m |
| </literallayout> |
| </para> |
| |
| <para> |
| 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. |
| One of these variables is the |
| <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link> |
| variable, which allows the OpenEmbedded build system to locate |
| the server that is running BitBake. |
| </para> |
| |
| <para> |
| You need to run an environment setup script before using BitBake |
| commands. |
| Following is the script syntax: |
| <literallayout class='monospaced'> |
| $ source oe-init-build-env-memres <replaceable>port_number</replaceable> <replaceable>build_dir</replaceable> |
| </literallayout> |
| Following are some considerations when sourcing this script: |
| <itemizedlist> |
| <listitem><para> |
| The script uses other scripts within the |
| <filename>scripts</filename> directory to do the bulk of |
| the work. |
| </para></listitem> |
| <listitem><para> |
| If you do not provide a port number with the script, the |
| BitBake server starts at a randomly selected port. |
| </para></listitem> |
| <listitem><para> |
| The script's parameters are positionally dependent. |
| Consequently, you cannot run the script and provide a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| name without also providing a port number. |
| In other words, the following syntax is illegal: |
| <literallayout class='monospaced'> |
| $ source oe-initbuild-env-memres <replaceable>build_dir</replaceable> |
| </literallayout> |
| <note> |
| The previous restriction might be resolved in the |
| future. |
| See |
| <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=7555'>Bug 7555</ulink> |
| for more information. |
| </note> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| When you run this script, your Yocto Project environment is set |
| up, a Build Directory is created, your working directory becomes |
| the Build Directory, and you are presented with a list of common |
| BitBake targets. |
| Here is an example: |
| <literallayout class='monospaced'> |
| $ source oe-init-build-env-memres |
| No port specified, using dynamically selected port |
| |
| ### 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' |
| Bitbake server address: 127.0.0.1, server port: 53995 |
| Bitbake server started on demand as needed, use bitbake -m to shut it down |
| </literallayout> |
| The script gets its default list of common targets from the |
| <filename>conf-notes.txt</filename> file, which is found in the |
| <filename>meta-poky</filename> directory within the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| Should you have custom distributions, it is very easy to modify |
| this configuration file to include your targets for 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 Manual for more |
| information. |
| </para> |
| |
| <para> |
| By default, running this script without a |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| argument creates a build directory named |
| <filename>build</filename>. |
| If you provide a Build Directory argument and port number when you |
| <filename>source</filename> the script, the Build Directory is |
| created using that name. |
| For example, the following command starts the BitBake server using |
| port 53995 and creates a Build Directory named |
| <filename>mybuilds</filename> that is outside of the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: |
| <literallayout class='monospaced'> |
| $ source oe-init-build-env-memres 53995 ~/mybuilds |
| </literallayout> |
| The <filename>oe-init-build-env-memres</filename> script starts a |
| memory resident BitBake server. |
| This BitBake instance uses the |
| <filename>bitbake-cookerdaemon.log</filename> file, which is |
| located in the Build Directory. |
| </para> |
| |
| <para> |
| The OpenEmbedded build system uses the template configuration |
| files, which are found by default in the |
| <filename>meta-poky/conf</filename> directory in the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 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 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-build-env-memres</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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> |
| when you run one of the build environment setup scripts (i.e. |
| <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> |
| or |
| <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). |
| </para> |
| |
| <para> |
| If you do not give the Build Directory a specific name when you run |
| a setup script, the name defaults to <filename>build</filename>. |
| </para> |
| |
| <para> |
| The |
| <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable |
| points to the Build Directory. |
| </para> |
| |
| <section id='structure-build-buildhistory'> |
| <title><filename>build/buildhistory</filename></title> |
| |
| <para> |
| The OpenEmbedded build system creates this directory when you |
| enable the build history feature. |
| The directory tracks build information into image, packages, and |
| SDK subdirectories. |
| For information on the build history feature, see the |
| "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" |
| section. |
| </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 these |
| variables are relatively rare. |
| </para> |
| |
| <para> |
| Edit this file to set the |
| <filename><link linkend='var-MACHINE'>MACHINE</link></filename> |
| for which you want to build, 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 (i.e. |
| <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> |
| or |
| <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</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 defaults 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 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> |
| or |
| <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). |
| </para> |
| |
| <para> |
| 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 defaults 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 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/conf/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 |
| "<link linkend='images-dev-environment'>Images</link>" and |
| "<link linkend='sdk-dev-environment'>Application Development SDK</link>" |
| sections. |
| </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. |
| </para> |
| </section> |
| |
| <section id='structure-build-tmp-deploy-images'> |
| <title><filename>build/tmp/deploy/images/</filename></title> |
| |
| <para> |
| This directory receives complete filesystem images. |
| If you want to flash the resulting image from a build onto a device, look here for the image. |
| </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 Software Development Kit (SDK) Developer's Guide. |
| </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'> |
| <title><filename>build/tmp/sysroots/</filename></title> |
| |
| <para> |
| This directory contains shared header files and libraries as well as other shared |
| data. |
| Packages that need to share output with other packages do so within this directory. |
| The directory is subdivided by architecture so multiple builds can run within |
| the one Build Directory. |
| </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 |
| "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" |
| section. |
| </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><link linkend='var-WORKDIR'>WORKDIR</link></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 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-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, |
| <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> 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 |
| --> |