diff options
Diffstat (limited to 'documentation/poky-ref-manual/ref-structure.xml')
| -rw-r--r-- | documentation/poky-ref-manual/ref-structure.xml | 621 |
1 files changed, 0 insertions, 621 deletions
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml deleted file mode 100644 index 4cfd08fae6..0000000000 --- a/documentation/poky-ref-manual/ref-structure.xml +++ /dev/null @@ -1,621 +0,0 @@ -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<appendix id='ref-structure'> - -<title>Reference: Directory Structure</title> - -<para> - Poky consists of several components. - Understanding them and knowing where they are located is key to using Poky well. - This appendix describes the Poky directory structure and gives information about the various - files and directories. -</para> - -<section id='structure-core'> - <title>Top level core components</title> - - <section id='structure-core-bitbake'> - <title><filename class="directory">bitbake/</filename></title> - - <para> - Poky includes a copy of BitBake for ease of use. - The copy usually matches the current stable BitBake release from the BitBake project. - BitBake, a metadata interpreter, reads the Poky 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. - The <filename class="directory">bitbake/bin/</filename> directory is placed - into the PATH environment variable by the - <link linkend="structure-core-script">poky-init-build-env</link> script. - </para> - - <para> - For more information on BitBake, see the BitBake on-line manual at - <ulink url="http://bitbake.berlios.de/manual/"/>. - </para> - </section> - - <section id='structure-core-build'> - <title><filename class="directory">build/</filename></title> - - <para> - This directory contains user configuration files and the output - generated by Poky in its standard configuration where the source tree is - combined with the output. - It is also possible to place output and configuration - files in a directory separate from the Poky source. - For information on separating output from the Poky source, see <link - linkend='structure-core-script'>poky-init-build-env</link>. - </para> - </section> - - <section id='structure-core-meta'> - <title><filename class="directory">meta/</filename></title> - - <para> - This directory contains the core metadata, which is a key part of Poky. - This directory contains the machine definitions, the Poky distribution, - and the packages that make up a given system. - </para> - </section> - -<!-- <section id='structure-core-meta-extras'> - <title><filename class="directory">meta-extras/</filename></title> - - <para> - This directory is similar to <filename class="directory">meta/</filename>. - The directory contains extra metadata not included in standard Poky. - This metadata is disabled by default and is not supported as part of Poky. - </para> - </section> ---> - - <section id='structure-core-meta-demoapps'> - <title><filename class="directory">meta-demoapps/</filename></title> - - <para> - This directory contains recipes for applications and demos that are not core. - </para> - </section> - - <section id='structure-core-meta-rt'> - <title><filename class="directory">meta-rt/</filename></title> - - <para> - This directory contains recipes for RealTime. - </para> - </section> - -<!-- <section id='structure-core-meta-***'> - <title><filename class="directory">meta-***/</filename></title> - - <para> - These directories are optional layers that are added to core metadata. - The layers are enabled by adding them to the <filename>conf/bblayers.conf</filename> file. - </para> - </section> ---> - - <section id='structure-core-scripts'> - <title><filename class="directory">scripts/</filename></title> - - <para> - This directory contains various integration scripts that implement - extra functionality in the Poky environment (e.g. QEMU scripts). - The <link linkend="structure-core-script">poky-init-build-env</link> script appends this - directory to the PATH environment variable. - </para> - </section> - -<!-- <section id='structure-core-sources'> - <title><filename class="directory">sources/</filename></title> - - <para> - This directory receives downloads as specified by the - <glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm> variable. - Even though the directory is not part of a checkout, Poky creates it during a build. - You can use this directory to share downloading files between Poky builds. - This practice can save you from downloading files multiple times. - <note><para> - You can override the location for this directory by setting - the DL_DIR variable in <filename>local.conf</filename>. - </para></note> - </para> - - <para> - This directory also contains SCM checkouts (e.g. <filename class="directory">sources/svn/ - </filename>, <filename class="directory">sources/cvs/</filename> or - <filename class="directory">sources/git/</filename>). - The <filename class="directory">sources</filename> directory can contain archives of - checkouts for various revisions or dates. - </para> - - <para> - It's worth noting that BitBake creates <filename class="extension">.md5 - </filename> stamp files for downloads. - BitBake uses these files to mark downloads as - complete as well as for checksum and access accounting purposes. - If you manually add a file to the directory, you need to touch the corresponding - <filename class="extension">.md5</filename> file as well. - </para> - </section> ---> - - <section id='handbook'> - <title><filename class="directory">documentation</filename></title> - - <para> - This directory holds the source for the documentation. Each manual is contained in - a sub-folder. For example, the files for this manual reside in - <filename class="directory">poky-ref-manual</filename>. - </para> - </section> - - <section id='structure-core-script'> - <title><filename>poky-init-build-env</filename></title> - - <para> - This script sets up the Poky build environment. - Sourcing this file in - a shell makes changes to PATH and sets other core BitBake variables based on the - current working directory. - You need to run this script before running Poky commands. - The script uses other scripts within the <filename class="directory">scripts/ - </filename> directory to do the bulk of the work. - You can use this script to specify any directory for the build's output by doing the following: - </para> - - <literallayout class='monospaced'> - $ source POKY_SRC/poky-init-build-env [BUILDDIR] - </literallayout> - - <para> - You can enter the above command from any directory, as long as POKY_SRC points to - the desired Poky source tree. - The optional BUILDDIR can be any directory into which you would - like Poky to generate the build output. - </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 class="directory">build/</filename></title> - - <section id='structure-build-pseudodone'> - <title><filename>build/pseudodone</filename></title> - - <para> - This tag file indicates that the intitial pseudo binar was created. - The first time BitBake is invoked this file is built. - </para> - </section> - - <section id='structure-build-conf-local.conf'> - <title><filename>build/conf/local.conf</filename></title> - - <para> - This file contains all the local user configuration of Poky. - If there is no <filename>local.conf</filename> present, it is created from - <filename>local.conf.sample</filename>. - The <filename>local.conf</filename> file contains documentation on the various configuration options. - Any variable set here overrides any variable set elsewhere within Poky unless - that variable is hard-coded within Poky (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 <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> - for which you want to build, which package types you - wish to use (PACKAGE_CLASSES) or where you want to downloaded files - (<glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm>). - </para> - </section> - - <section id='structure-build-conf-bblayers.conf'> - <title><filename>build/conf/bblayers.conf</filename></title> - - <para> - This file defines layers, which is a directory tree, traversed (or walked) by BitBake. - If <filename>bblayers.conf</filename> - is not present, it is created from <filename>bblayers.conf.sample</filename> when the environment - setup script is sourced. - </para> - </section> - - <section id='structure-build-conf-sanity_info'> - <title><filename>build/conf/sanity_info</filename></title> - - <para> - This file is created during the build to indicate the state of the sanity checks. - </para> - </section> - - <section id='structure-build-downloads'> - <title><filename>build/downloads/</filename></title> - - <para> - This directory is used for the upstream source tarballs. - The directory can be reused by multiple builds or moved to another location. - You can control the location of this directory through the - <glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm> variable. - </para> - </section> - - <section id='structure-build-sstate-cache'> - <title><filename>build/sstate-cache/</filename></title> - - <para> - This directory is used for the shared state cache. - The directory can be reused by multiple builds or moved to another location. - You can control the location of this directory through the - <glossterm><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></glossterm> variable. - </para> - </section> - - <section id='structure-build-tmp'> - <title><filename class="directory">build/tmp/</filename></title> - - <para> - This directory receives all the Poky output. - BitBake creates this directory if it does not exist. - To clean Poky and start a build from scratch (other than downloads), - you can remove everything in this directory or get rid of the directory completely. - The <filename class="directory">tmp/</filename> directory has some important - sub-components detailed below. - </para> - </section> - - <section id='structure-build-tmp-buildstats'> - <title><filename class="directory">build/tmp/buildstats/</filename></title> - - <para> - This directory stores the build statistics. - </para> - </section> - - <section id='structure-build-tmp-cache'> - <title><filename class="directory">build/tmp/cache/</filename></title> - - <para> - When BitBake parses the metadata it creates a cache file of the result that can - be used when subsequently running commands. - These results are stored here on a per-machine basis. - </para> - </section> - - <section id='structure-build-tmp-deploy'> - <title><filename class="directory">build/tmp/deploy/</filename></title> - - <para>This directory contains any 'end result' output from Poky.</para> - </section> - - <section id='structure-build-tmp-deploy-deb'> - <title><filename class="directory">build/tmp/deploy/deb/</filename></title> - - <para> - This directory receives any <filename>.deb</filename> packages produced by Poky. - The packages are sorted into feeds for different architecture types. - </para> - </section> - - <section id='structure-build-tmp-deploy-rpm'> - <title><filename class="directory">build/tmp/deploy/rpm/</filename></title> - - <para> - This directory receives any <filename>.rpm</filename> packages produced by Poky. - The packages re sorted into feeds for different architecture types. - </para> - </section> - - <section id='structure-build-tmp-deploy-images'> - <title><filename class="directory">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> - </section> - - <section id='structure-build-tmp-deploy-ipk'> - <title><filename class="directory">build/tmp/deploy/ipk/</filename></title> - - <para>This directory receives <filename>.ipk</filename> packages produced by Poky.</para> - </section> - - <section id='structure-build-tmp-sysroots'> - <title><filename class="directory">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 class="directory">build/tmp/stamps/</filename></title> - - <para> - This directory holds information that that BitBake uses for accounting purposes - to track what tasks have run and when they have run. - The directory is sub-divided by architecture. - The files in the directory are empty of data. - However, BitBake uses the filenames and timestamps for tracking purposes. - </para> - </section> - - <section id='structure-build-tmp-log'> - <title><filename class="directory">build/tmp/log/</filename></title> - - <para> - This directory contains general logs that are not otherwise placed using the - package's <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>. - Examples of logs are the output from the "check_pkg" or "distro_check" tasks. - </para> - </section> - - <section id='structure-build-tmp-pkgdata'> - <title><filename class="directory">build/tmp/pkgdata/</filename></title> - - <para> - This directory contains intermediate packaging data that is used later in the packaging process. - For more information, see <link linkend='ref-classes-package'>package.bbclass</link>. - </para> - </section> - - <section id='structure-build-tmp-pstagelogs'> - <title><filename class="directory">build/tmp/pstagelogs/</filename></title> - - <para> - This directory contains manifest for task-based pre-built. - Each manifest is basically a file list for installed files from a given task. - Manifests are useful for later packaging or cleanup processes. - </para> - </section> - - <section id='structure-build-tmp-work'> - <title><filename class="directory">build/tmp/work/</filename></title> - - <para> - This directory contains architecture-specific work sub-directories for packages built by BitBake. - All tasks execute from a work directory. - For example, the source for a particular package is unpacked, patched, configured and compiled all - within its own work directory. - </para> - - <para> - It is worth considering the structure of a typical work directory. - As an example consider the linux-rp kernel, version 2.6.20 r7 on the machine spitz - built within Poky. - For this package a work directory of - <filename class="directory">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/</filename>, - referred to as <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, is created. - Within this directory, the source is unpacked to linux-2.6.20 and then patched by quilt - (see <link linkend="usingpoky-modifying-packages-quilt">Section 3.5.1</link>). - Within the <filename class="directory">linux-2.6.20</filename> directory, - standard quilt directories <filename class="directory">linux-2.6.20/patches</filename> - and <filename class="directory">linux-2.6.20/.pc</filename> are created, - and standard quilt commands can be used. - </para> - - <para> - There are other directories generated within WORKDIR. - The most important directory is WORKDIR - <filename class="directory">/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 WORKDIR<filename class="directory">/image/</filename> directory is where "make - install" places its output that is then split into sub-packages - within WORKDIR<filename class="directory">/packages-split/</filename>. - </para> - </section> -</section> - -<section id='structure-meta'> - <title>The Metadata - <filename class="directory">meta/</filename></title> - - <para> - As mentioned previously, metadata is the core of Poky. - Metadata has several important subdivisions: - </para> - - <section id='structure-meta-classes'> - <title><filename class="directory">meta/classes/</filename></title> - - <para> - This directory contains the <filename class="extension">*.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 Poky 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> - </section> - - <section id='structure-meta-conf'> - <title><filename class="directory">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 includes at the end of the 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 class="directory">meta/conf/machine/</filename></title> - - <para> - This directory contains all the machine configuration files. - If you set MACHINE="spitz", Poky looks for a <filename>spitz.conf</filename> file in this - directory. - The includes directory contains various data common to multiple machines. - If you want to add support for a new machine to Poky, look in this directory. - </para> - </section> - - <section id='structure-meta-conf-distro'> - <title><filename class="directory">meta/conf/distro/</filename></title> - - <para> - Any distribution-specific configuration is controlled from this directory. - Poky only contains the Poky distribution so <filename>poky.conf</filename> - is the main file here. - This directory includes the versions and SRCDATES for applications that are configured here. - An example of an alternative configuration is <filename>poky-bleeding.conf</filename> - although this file mainly inherits its configuration from Poky itself. - </para> - </section> - - <section id='structure-meta-recipes-bsp'> - <title><filename class="directory">meta/recipes-bsp/</filename></title> - - <para> - This directory contains anything linking to specific hardware or hardware configuration information - such as "uboot" and "grub". - </para> - </section> - - <section id='structure-meta-recipes-connectivity'> - <title><filename class="directory">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 class="directory">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 class="directory">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 class="directory">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 class="directory">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 class="directory">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 class="directory">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-multimedia'> - <title><filename class="directory">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-qt'> - <title><filename class="directory">meta/recipes-qt/</filename></title> - - <para> - This directory contains all things related to the QT application framework. - </para> - </section> - - <section id='structure-meta-recipes-sato'> - <title><filename class="directory">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 class="directory">meta/recipes-support/</filename></title> - - <para> - This directory contains recipes that used by other recipes, but that are not directly - included in images (i.e. depenendies of other recipes). - </para> - </section> - - <section id='structure-meta-site'> - <title><filename class="directory">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 class="directory">meta/recipes.txt/</filename></title> - - <para> - This file is a description of the contents of <filename>recipes-*</filename>. - </para> - </section> -</section> - -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> |