From 1adebc081d898ee14963b20276efc15acb1589c3 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 11 Jul 2013 16:16:05 +0300 Subject: ref-manual: Added new section for layer input detail. (From yocto-docs rev: ff952a9681df798cde34b50d1046233a47ca0ce5) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/technical-details.xml | 404 +++++++++++++++++-------- 1 file changed, 283 insertions(+), 121 deletions(-) (limited to 'documentation/ref-manual/technical-details.xml') diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 79d16549c3..664c4f7986 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -222,147 +222,309 @@ environment: - - - - - + - - BitBake needs some basic configuration files in order to complete - a build. - These files are *.conf files. - The minimally necessary ones reside as example files in the - Source Directory. - For simplicity, this section refers to the Source Directory as - the "Poky Directory." - - Poky is primarily an aggregation of existing repositories and - is not actual canonical upstream source for anything. - - When you clone the poky Git repository or you - download and unpack a Yocto Project release, you can set up the - Source Directory to be named anything you want. - Here, though, we will assume that you have a cloned repository that - has the default name poky. - + + BitBake needs some basic configuration files in order to complete + a build. + These files are *.conf files. + The minimally necessary ones reside as example files in the + Source Directory. + For simplicity, this section refers to the Source Directory as + the "Poky Directory." + + Poky is primarily an aggregation of existing repositories and + is not actual canonical upstream source for anything. + + When you clone the poky Git repository or you + download and unpack a Yocto Project release, you can set up the + Source Directory to be named anything you want. + For this discussion, the cloned repository uses the default + name poky. + - - The meta-yocto layer inside Poky contains - a conf directory that has example - configuration files. - These example files are used as a basis for creating actual - configuration files when you source the build environment - script oe-init-build-env. - - The oe-init-build-env script also exists - in the meta directory of the OE-Core - root directory. - Both scripts look for sample configuration files through - a $TEMPLATECONF variable. - When using the Yocto Project Development Environment, - that location resolves to the samples found in the - poky/meta-yocto/conf directory. - - + + The meta-yocto layer inside Poky contains + a conf directory that has example + configuration files. + These example files are used as a basis for creating actual + configuration files when you source the build environment + script oe-init-build-env. + + The oe-init-build-env script also exists + in the meta directory of the OE-Core + root directory. + Both scripts look for sample configuration files through + a $TEMPLATECONF variable. + When using the Yocto Project Development Environment, + that location resolves to the samples found in the + poky/meta-yocto/conf directory. + + - - When you source the build environment script, it creates a - Build Directory - that BitBake uses as the area in which it does all its work - during builds. - The Build Directory has a conf directory that - contains default versions of your local.conf - and bblayers.conf configuration files. - These default configuration files are created by - oe-init-build-env only if versions of these - files do not already exist in the Build Directory you specify - when you run the script. - + + When you source the build environment script, it creates a + Build Directory + if one does not already exist. + BitBake uses the Build Directory for all its work during builds. + The Build Directory has a conf directory that + contains default versions of your local.conf + and bblayers.conf configuration files. + These default configuration files are created by + oe-init-build-env only if versions of these + files do not already exist in the Build Directory you specify + when you run the script. + + + + The local.conf file provides many + basic variables that define your build. + Here is a list of a few. + To see the default configurations in a local.conf + file created by the build environment script, see the + local.conf.sample in the + meta-yocto layer: + + Parallelism Options: + Controlled by the + BB_NUMBER_THREADS + and + PARALLEL_MAKE + variables. + Target Machine Selection: + Controlled by the + MACHINE + variable. + Download Directory: + Controlled by the + DL_DIR + variable. + Shared State Directory: + Controlled by the + SSTATE_DIR + variable. + Build Output: + Controlled by the + TMPDIR + variable. + + + + + The bblayers.conf file tells BitBake what + layers you want it to consider during the build. + The list of layers includes default layers needed by the build + system. + You have to manually add any custom layers that you have created. + You can find more information on working with the + bblayers.conf file in the + "Enabling Your Layer" + section in the Yocto Project Development Manual. + + + + The files site.conf and + auto.conf are not created by the environment + initialization script. + If you want these configuration files, you must create them + yourself: + + site.conf: + I don't really know what this does. + All I know is that if you want it, you need to hand-create + it. + I need some information on it. + auto.conf: + This file is not hand-created. + Rather, the file is usually created and written to by + an autobuilder. + The settings put into the file are typically the same as + you would find in the local.conf + or site.conf files. + + + + + + You can edit all configuration files to further define + the build. + This process is represented by the "User Configuration Edits" + box in the figure. + + + + When you launch your build with the + bitbake <target> command, BitBake + draws on the user configurations you have provided in your + Build Directory. + + + +
+ Metadata, Machine Configuration, and Policy Configuration + + + The previous section described the user configurations that + define the BitBake's global behavior. + This section takes a closer look at the layers the build system + uses to further control the build. + These layers provide Metadata for the software, machine, and + policy. + - The local.conf file provides many - basic variables that define your build. - Here is a list of a few. - To see the default configurations in a local.conf - file created by the build environment script, see the - local.conf.sample in the - meta-yocto layer: + In general, three types of layer input exist: - Parallelism Options: - Controlled by the - BB_NUMBER_THREADS - and - PARALLEL_MAKE - variables. - Target Machine Selection: - Controlled by the - MACHINE - variable. - Download Directory: - Controlled by the - DL_DIR - variable. - Shared State Directory: - Controlled by the - SSTATE_DIR - variable. - Build Output: - Controlled by the - TMPDIR - variable. + Metadata: + Software layers contain user-supplied recipe files, + patches, and append files. + + Machine Configuration: + Board Support Package (BSP) layers provide machine + configurations. + This type of information is specific to a particular + target architecture. + Policy Configuration: + Distribution Layers provide top-level or general + policies for the image or SDK being built. + For example, this layer would dictate whether BitBake + produces RPM or IPK packages. - The bblayers.conf file tells BitBake what - layers you want it to consider during the build. - The list of layers includes default layers needed by the build - system. - You have to manually add any custom layers that you have created. - You can find more information on working with the - bblayers.conf file in the - "Enabling Your Layer" - section in the Yocto Project Development Manual. + The following figure shows an expanded representation of the + Metadata, Machine Configuration, and Policy Configuration input + boxes of the Yocto Project development environment: + + - The files site.conf and - auto.conf are not created by the environment - initialization script. - If you want these configuration files, you must create them - yourself: - - site.conf: - I don't really know what this does. - All I know is that if you want it, you need to hand-create - it. - I need some information on it. - auto.conf: - This file is not hand-created. - Rather, the file is usually created and written to by - an autobuilder. - The settings put into the file are typically the same as - you would find in the local.conf - or site.conf files. - - + The Yocto Project has many layers that can be used. + You can see a web-interface listing of them on the + Source Repositories + page. + The layers are shown at the bottom categorized under + "Yocto Metadata Layers." + These layers are fundamentally a subset of the + OpenEmbedded Metadata Index, + which shows all layers supported by OpenEmbedded. + + Layers exist in the Yocto Project Source Repositories that cannot + be found in the OpenEmbedded Metadata Index. + These layers are either deprecated or experimental in nature. + + - You can edit all configuration files to further define - the build. - This process is represented by the "User Configuration Edits" - box in the figure. + BitBake uses the bblayers.conf file that is + part of the user configuration to find what layers it should be + using as part of the build. - When you launch your build with the - bitbake <target> command, BitBake - draws on the user configurations you have provided in your - Build Directory. + For more information on layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Manual. + +
+ Software Layer + + + The software layer provides the Metadata for your source + code used during the build. + This general layer minimally contains license + information; a README file; a layer + configuration file named layer.conf; + and recipe files (.bb), append files + (.bbappend), and patches + (.patch). + + + + You provide any new recipes that your project needs in the + form of recipe files. + If you are modifying any existing recipes from other layers, + rather than duplicate them here with the modifcations, you can + provide a recipe append file that just has the modifications. + Patch files are stored in the files + directory. + +
+ +
+ Distro Layer + + + The distribution layer provides policy configurations for your + distribution. + Best practices dictate that you isolate these types of + configurations into their own layer. + Metadata you provide in this layer overrides similar settings + that BitBake finds in your local.conf + file in the Build Directory. + + + + The following list provides some explanation and references + for what you typically find in the distribution layer: + + classes: + Class files (.bbclass) hold + common functionality that can be shared among + recipes in the distribution. + When your recipes inherit a class, they take on the + settings and functions for that class. + You can read more about class files in the + "Classes" section. + + conf: + This area holds configuration information for the + distribution. + Any distribution-wide include files and, of course, the + layer.conf configuration + file that every layer must have. + recipes-core: + Recipes and append files that affect common + functionality across the distribution. + This area also can hold common distribution headers, + initialization files, and + defconfig files for the + distribution. + + +
+ +
+ BSP Layer + + + The BSP Layer provides machine configurations. + Everything in this layer is specific to the machine for which + you are building the image or the SDK. + BSP Layer's have a structure that is followed if they are + considered to be compatible with the Yocto Project. + For information on the structure, see the + Yocto Project Board Support Package (BSP) Developer's Guide. + + + + The BSP Layer contains a configuration directory that has + configuration files for the machine + (<machine>.conf) and, of course, + the layer (layer.conf). + + + + The remainder of the layer is dedicated to specific recipes + by function: bsp, core, graphics, and kernel. + Metadata can exist for multiple formfactors, graphics + support systems, and so forth. + +
-- cgit v1.2.3-54-g00ecf