From c527fd1f14c27855a37f2e8ac5346ce8d940ced2 Mon Sep 17 00:00:00 2001 From: Tudor Florea Date: Thu, 16 Oct 2014 03:05:19 +0200 Subject: initial commit for Enea Linux 4.0-140929 Migrated from the internal git server on the daisy-enea-point-release branch Signed-off-by: Tudor Florea --- documentation/ref-manual/ref-structure.xml | 1039 ++++++++++++++++++++++++++++ 1 file changed, 1039 insertions(+) create mode 100644 documentation/ref-manual/ref-structure.xml (limited to 'documentation/ref-manual/ref-structure.xml') diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml new file mode 100644 index 0000000000..93cd45d456 --- /dev/null +++ b/documentation/ref-manual/ref-structure.xml @@ -0,0 +1,1039 @@ + %poky; ] > + + + +Source Directory Structure + + + The Source Directory 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. + + + + For information on how to establish a local Source Directory on your development system, see the + "Getting Set Up" + section in the Yocto Project Development Manual. + + + + 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. + + +
+ Top-Level Core Components + + + This section describes the top-level components of the + Source Directory. + + +
+ <filename>bitbake/</filename> + + + 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 + Metadata + 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. + + + + When you run the bitbake command, the + main BitBake executable, which resides in the + bitbake/bin/ directory, starts. + Sourcing an environment setup script (e.g. + &OE_INIT_FILE; + or + oe-init-build-env-memres) + places the scripts and + bitbake/bin directories (in that order) into + the shell's PATH environment variable. + + + + For more information on BitBake, see the BitBake documentation + included in the bitbake/doc/manual directory of the + Source Directory. + +
+ +
+ <filename>build/</filename> + + + 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 Build Directory + is created initially when you source + the OpenEmbedded build environment setup script + (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + It is also possible to place output and configuration + files in a directory separate from the + Source Directory + by providing a directory name when you source + the setup script. + For information on separating output from your local + Source Directory files, see the + "&OE_INIT_FILE; + and + "oe-init-build-env-memres" + sections. + +
+ +
+ <filename>documentation/</filename> + + + 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 ref-manual/ directory. + +
+ +
+ <filename>meta/</filename> + + + This directory contains the OpenEmbedded Core metadata. + The directory holds recipes, common classes, and machine + configuration for emulated targets (qemux86, + qemuarm, and so forth.) + +
+ +
+ <filename>meta-yocto/</filename> + + + This directory contains the configuration for the Poky + reference distribution. + +
+ +
+ <filename>meta-yocto-bsp/</filename> + + + This directory contains the Yocto Project reference + hardware Board Support Packages (BSPs). + For more information on BSPs, see the + Yocto Project Board Support + Package (BSP) Developer's Guide. + +
+ +
+ <filename>meta-selftest/</filename> + + + 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 + bblayers.conf file unless you want to run the + selftests. + +
+ +
+ <filename>meta-skeleton/</filename> + + + This directory contains template recipes for BSP and kernel development. + +
+ +
+ <filename>scripts/</filename> + + + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The &OE_INIT_FILE; + and + oe-init-build-env-memres + scripts append this directory to the shell's + PATH environment variable. + + + + The scripts directory has useful scripts that assist in contributing + back to the Yocto Project, such as create-pull-request and + send-pull-request. + +
+ +
+ <filename>&OE_INIT_FILE;</filename> + + + This script is one of two scripts that set up the OpenEmbedded build + environment. + For information on the other script, see the + "oe-init-build-env-memres" + section. + + + + Running this script with the source command in + a shell makes changes to PATH 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 + scripts directory to do the bulk of the work. + + + + By default, running this script without a + Build Directory + argument creates the build directory + in your current working directory. + If you provide a Build Directory argument when you + source the script, you direct the OpenEmbedded + build system to create a Build Directory of your choice. + For example, the following command creates a Build Directory named + mybuilds that is outside of the + Source Directory: + + $ source &OE_INIT_FILE; ~/mybuilds + + + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the &OE_INIT_FILE; 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. + + +
+ +
+ <filename>oe-init-build-env-memres</filename> + + + 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 + "&OE_INIT_FILE;" + section. + + + + Memory-resident BitBake resides in memory until you specifically + remove it using the following BitBake command: + + $ bitbake -m + + + + + Running this script with the source command in + a shell makes changes to PATH and sets other + core BitBake variables based on the current working directory. + One of these variables is the + BBSERVER + variable, which allows the OpenEmbedded build system to locate + the server that is running BitBake. + + + + You need to run an environment setup script before using BitBake + commands. + Following is the script syntax: + + $ source oe-init-build-env-memres <port_number> <build_dir> + + The script uses other scripts within the + scripts directory to do the bulk of the work. + + + + If you do not provide a port number with the script, the + BitBake server at port "12345" is started. + + + + By default, running this script without a + Build Directory + argument creates a build directory named + build. + If you provide a Build Directory argument when you + source the script, the Build Directory is + created using that name. + For example, the following command starts the BitBake server using + the default port "12345" and creates a Build Directory named + mybuilds that is outside of the + Source Directory: + + $ source oe-init-build-env-memres ~/mybuilds + + + The OpenEmbedded build system does not support file or + directory names that contain spaces. + If you attempt to run the + oe-init-build-env-memres 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. + + +
+ +
+ <filename>LICENSE, README, and README.hardware</filename> + + + These files are standard top-level files. + +
+
+ +
+ The Build Directory - <filename>build/</filename> + + + The OpenEmbedded build system creates the + Build Directory + when you run one of the build environment setup scripts (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + If you do not give the Build Directory a specific name when you run + a setup script, the name defaults to build. + + + + The + TOPDIR variable + points to the Build Directory. + + +
+ <filename>build/buildhistory</filename> + + + 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 + "Maintaining Build Output Quality" + section. + +
+ +
+ <filename>build/conf/local.conf</filename> + + + This configuration file contains all the local user configurations + for your build environment. + The local.conf 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. + + + + Edit this file to set the + MACHINE + for which you want to build, which package types you wish to use + (PACKAGE_CLASSES), + the location from which you want to access downloaded files + (DL_DIR), + and how you want your host machine to use resources + (BB_NUMBER_THREADS + and + PARALLEL_MAKE). + + + + If local.conf is not present when you + start the build, the OpenEmbedded build system creates it from + local.conf.sample when + you source the top-level build environment + setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + The source local.conf.sample file used + depends on the $TEMPLATECONF script variable, + which defaults to meta-yocto/conf + when you are building from the Yocto Project development + environment and defaults to meta/conf when + you are building from the OpenEmbedded Core environment. + Because the script variable points to the source of the + local.conf.sample file, this implies that + you can configure your build environment from any layer by setting + the variable in the top-level build environment setup script as + follows: + + TEMPLATECONF=<your_layer>/conf + + Once the build process gets the sample file, it uses + sed to substitute final + ${OEROOT} + values for all ##OEROOT## values. + + You can see how the TEMPLATECONF variable + is used by looking at the + scripts/oe-setup-builddir script in the + Source Directory. + You can find the Yocto Project version of the + local.conf.sample file in the + meta-yocto/conf directory. + + +
+ +
+ <filename>build/conf/bblayers.conf</filename> + + + This configuration file defines + layers, + which are directory trees, traversed (or walked) by BitBake. + The bblayers.conf file uses the + BBLAYERS + variable to list the layers BitBake tries to find, and uses the + BBLAYERS_NON_REMOVABLE + variable to list layers that must not be removed. + + + + If bblayers.conf is not present when you + start the build, the OpenEmbedded build system creates it from + bblayers.conf.sample when + you source the top-level build environment + setup script (i.e. + &OE_INIT_FILE; + or + oe-init-build-env-memres). + + + + The source bblayers.conf.sample file used + depends on the $TEMPLATECONF script variable, + which defaults to meta-yocto/conf + when you are building from the Yocto Project development + environment and defaults to meta/conf when + you are building from the OpenEmbedded Core environment. + Because the script variable points to the source of the + bblayers.conf.sample file, this implies that + you can base your build from any layer by setting the variable in + the top-level build environment setup script as follows: + + TEMPLATECONF=<your_layer>/conf + + Once the build process gets the sample file, it uses + sed to substitute final + ${OEROOT} + values for all ##OEROOT## values. + + You can see how the TEMPLATECONF variable + scripts/oe-setup-builddir script in the + Source Directory. + You can find the Yocto Project version of the + bblayers.conf.sample file in the + meta-yocto/conf directory. + + +
+ +
+ <filename>build/conf/sanity_info</filename> + + + This file indicates the state of the sanity checks and is created + during the build. + +
+ +
+ <filename>build/downloads/</filename> + + + This directory contains downloaded upstream source tarballs. + You can reuse the directory for multiple builds or move + the directory to another location. + You can control the location of this directory through the + DL_DIR variable. + +
+ +
+ <filename>build/sstate-cache/</filename> + + + This directory contains the shared state cache. + You can reuse the directory for multiple builds or move + the directory to another location. + You can control the location of this directory through the + SSTATE_DIR variable. + +
+ +
+ <filename>build/tmp/</filename> + + + The OpenEmbedded build system creates and uses this directory + for all the build system's output. + The + TMPDIR + variable points to this directory. + + + + 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 + tmp directory or get rid of the + directory completely. + If you do, you should also completely remove the + build/sstate-cache directory. + +
+ +
+ <filename>build/tmp/buildstats/</filename> + + + This directory stores the build statistics. + +
+ +
+ <filename>build/tmp/cache/</filename> + + + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + BitBake stores these results here on a per-machine basis. + +
+ +
+ <filename>build/tmp/deploy/</filename> + + + This directory contains any "end result" output from the + OpenEmbedded build process. + The DEPLOY_DIR + variable points to this directory. + For more detail on the contents of the deploy + directory, see the + "Images" and + "Application Development SDK" + sections. + +
+ +
+ <filename>build/tmp/deploy/deb/</filename> + + + This directory receives any .deb packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + +
+ +
+ <filename>build/tmp/deploy/rpm/</filename> + + + This directory receives any .rpm packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + +
+ +
+ <filename>build/tmp/deploy/ipk/</filename> + + + This directory receives .ipk packages produced by + the build process. + +
+ +
+ <filename>build/tmp/deploy/licenses/</filename> + + + This directory receives package licensing information. + For example, the directory contains sub-directories for bash, + busybox, and eglibc (among others) that in turn + contain appropriate COPYING license files with other licensing information. + For information on licensing, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section. + +
+ +
+ <filename>build/tmp/deploy/images/</filename> + + + 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. + + + + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + core-image-*, hob-image-*, + etc.). + However, the kernel (*zImage*, *uImage*, 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. + + + + 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: + + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + + +
+ +
+ <filename>build/tmp/deploy/sdk/</filename> + + + 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 + "Optionally Building a Toolchain Installer" + section in the Yocto Project Application Developer's Guide. + +
+ +
+ <filename>build/tmp/sstate-control/</filename> + + + 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. + +
+ +
+ <filename>build/tmp/sysroots/</filename> + + + 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. + +
+ +
+ <filename>build/tmp/stamps/</filename> + + + 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: + + stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do + + Although the files in the directory are empty of data, + BitBake uses the filenames and timestamps for tracking purposes. + +
+ +
+ <filename>build/tmp/log/</filename> + + + This directory contains general logs that are not otherwise placed using the + package's WORKDIR. + Examples of logs are the output from the check_pkg or + distro_check tasks. + Running a build does not necessarily mean this directory is created. + +
+ +
+ <filename>build/tmp/work/</filename> + + + 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 + WORKDIR. + + + + It is worth considering the structure of a typical work directory. + As an example, consider linux-yocto-kernel-3.0 + on the machine qemux86 + built within the Yocto Project. + For this package, a work directory of + tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>, + referred to as the + WORKDIR, is created. + Within this directory, the source is unpacked to + linux-qemux86-standard-build and then patched by Quilt. + (See the + "Using a Quilt Flow" + section in the Yocto Project Development Manual for more information.) + Within the linux-qemux86-standard-build directory, + standard Quilt directories linux-3.0/patches + and linux-3.0/.pc are created, + and standard Quilt commands can be used. + + + + There are other directories generated within WORKDIR. + The most important directory is WORKDIR/temp/, + which has log files for each task (log.do_*.pid) + and contains the scripts BitBake runs for each task + (run.do_*.pid). + The WORKDIR/image/ directory is where "make + install" places its output that is then split into sub-packages + within WORKDIR/packages-split/. + +
+ +
+ <filename>build/tmp/work-shared/</filename> + + + 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 gcc + and its variants (e.g. gcc-cross, + libgcc, gcc-runtime, + and so forth). + +
+
+ +
+ The Metadata - <filename>meta/</filename> + + + As mentioned previously, + Metadata is the core + of the Yocto Project. + Metadata has several important subdivisions: + + +
+ <filename>meta/classes/</filename> + + + This directory contains the *.bbclass files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the base.bbclass file. + Examples of other important classes are autotools.bbclass, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is kernel.bbclass that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as image.bbclass, rootfs_*.bbclass and + package*.bbclass. + + + + For reference information on classes, see the + "Classes" chapter. + +
+ +
+ <filename>meta/conf/</filename> + + + This directory contains the core set of configuration files that start from + bitbake.conf and from which all other configuration + files are included. + See the include statements at the end of the + bitbake.conf file and you will note that even + local.conf is loaded from there. + While bitbake.conf sets up the defaults, you can often override + these by using the (local.conf) file, machine file or + the distribution configuration file. + +
+ +
+ <filename>meta/conf/machine/</filename> + + + This directory contains all the machine configuration files. + If you set MACHINE = "qemux86", + the OpenEmbedded build system looks for a qemux86.conf file in this + directory. + The include 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. + +
+ +
+ <filename>meta/conf/distro/</filename> + + + The contents of this directory controls any distribution-specific + configurations. + For the Yocto Project, the defaultsetup.conf is the main file here. + This directory includes the versions and the + SRCDATE definitions for applications that are configured here. + An example of an alternative configuration might be poky-bleeding.conf. + Although this file mainly inherits its configuration from Poky. + +
+ +
+ <filename>meta/conf/machine-sdk/</filename> + + + The OpenEmbedded build system searches this directory for + configuration files that correspond to the value of + SDKMACHINE. + 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. + +
+ +
+ <filename>meta/files/</filename> + + + 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. + +
+ +
+ <filename>meta/lib/</filename> + + + This directory contains OpenEmbedded Python library code + used during the build process. + +
+ +
+ <filename>meta/recipes-bsp/</filename> + + + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + +
+ +
+ <filename>meta/recipes-connectivity/</filename> + + + This directory contains libraries and applications related to communication with other devices. + +
+ +
+ <filename>meta/recipes-core/</filename> + + + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + +
+ +
+ <filename>meta/recipes-devtools/</filename> + + + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + +
+ +
+ <filename>meta/recipes-extended/</filename> + + + 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. + +
+ +
+ <filename>meta/recipes-gnome/</filename> + + + This directory contains all things related to the GTK+ application framework. + +
+ +
+ <filename>meta/recipes-graphics/</filename> + + + This directory contains X and other graphically related system libraries + +
+ +
+ <filename>meta/recipes-kernel/</filename> + + + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + +
+ +
+ <filename>meta/recipes-lsb4/</filename> + + + This directory contains recipes specifically added to support + the Linux Standard Base (LSB) version 4.x. + +
+ +
+ <filename>meta/recipes-multimedia/</filename> + + + This directory contains codecs and support utilities for audio, images and video. + +
+ +
+ <filename>meta/recipes-qt/</filename> + + + This directory contains all things related to the Qt application framework. + +
+ +
+ <filename>meta/recipes-rt/</filename> + + + This directory contains package and image recipes for using and testing + the PREEMPT_RT kernel. + +
+ +
+ <filename>meta/recipes-sato/</filename> + + + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + +
+ +
+ <filename>meta/recipes-support/</filename> + + + This directory contains recipes used by other recipes, but that are + not directly included in images (i.e. dependencies of other + recipes). + +
+ +
+ <filename>meta/site/</filename> + + + 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. + +
+ +
+ <filename>meta/recipes.txt</filename> + + + This file is a description of the contents of recipes-*. + +
+
+ + + -- cgit v1.2.3-54-g00ecf