From 89ca97371d07f8516308597fbb21094389de3cb9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 11 Sep 2013 14:44:00 -0700 Subject: ref-manual: Added information for OEROOT and build environment Fixes [YOCTO #4980] Added a new glossary entry for OEROOT. Added significant information to the local.conf and bblayers.conf reference sections to describe how the root build directory is derived. Also, some unrelated formatting to the DL_DIR variable description was mixed in here because I forgot to commit that separatey and it lives in the same variables.xml file. (From yocto-docs rev: c397a31f5b0d3f6257657119a4e81b4fbdc3800c) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-structure.xml | 116 ++++++++++++++++++++++++----- documentation/ref-manual/ref-variables.xml | 53 +++++++++---- 2 files changed, 135 insertions(+), 34 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml index 3133e8dc6d..13803f5a41 100644 --- a/documentation/ref-manual/ref-structure.xml +++ b/documentation/ref-manual/ref-structure.xml @@ -334,48 +334,124 @@ <filename>build/conf/local.conf</filename> - This file contains all the local user configuration for your build environment. - If there is no local.conf present, it is created from - local.conf.sample. - 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. + 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 + 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 downloaded files (DL_DIR), and how you want your host machine to use resources - (BB_NUMBER_THREADS and + (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 file defines + This configuration file defines layers, which are directory trees, traversed (or walked) by BitBake. - If bblayers.conf - is not present, it is created from bblayers.conf.sample when - you source the environment setup script. - - - The bblayers.conf file uses the - BBLAYERS variable to - list the layers BitBake tries to find. - The 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. + +
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index b3562db578..764c8072da 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -1230,37 +1230,40 @@ Core layer for images cannot be removed DL_DIR - The central download directory used by the build process to store downloads. - You can set this directory by defining the DL_DIR - variable in the /conf/local.conf file. + The central download directory used by the build process to + store downloads. + You can set this directory by defining the + DL_DIR variable in the + /conf/local.conf file. This directory is self-maintaining and you should not have to touch it. - By default, the directory is downloads in the + By default, the directory is downloads + in the Build Directory. #DL_DIR ?= "${TOPDIR}/downloads" - To specify a different download directory, simply uncomment the line - and provide your directory. + To specify a different download directory, simply remove + the comment from the line and provide your directory. - During a first build, the system downloads many different source code - tarballs from various upstream projects. + During a first build, the system downloads many different + source code tarballs from various upstream projects. Downloading can take a while, particularly if your network connection is slow. Tarballs are all stored in the directory defined by - DL_DIR and the build system looks there first - to find source tarballs. + DL_DIR and the build system looks there + first to find source tarballs. - When wiping and rebuilding, you can preserve this directory to speed - up this part of subsequent builds. + When wiping and rebuilding, you can preserve this + directory to speed up this part of subsequent builds. - You can safely share this directory between multiple builds on the - same development machine. + You can safely share this directory between multiple builds + on the same development machine. For additional information on how the build process gets source files when working behind a firewall or proxy server, see this specific question in the @@ -3353,6 +3356,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + OEROOT + + + The directory from which the top-level build environment + setup script is sourced. + The Yocto Project makes two top-level build environment + setup scripts available: + &OE_INIT_FILE; + and + oe-init-build-env-memres. + When you run one of these scripts, the + OEROOT variable resolves to the + directory that holds the script. + + + + For additional information on how this variable is used, + see the initialization scripts. + + + + OLDEST_KERNEL -- cgit v1.2.3-54-g00ecf