From ae647f6032f6f637829adb2eba896ec924eacb29 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 6 Mar 2012 10:37:59 -0600 Subject: documentation/dev-manual/dev-manual-common-tasks.xml: Review comments Applied the review comments from Paul Eggleton for the new section on "Understanding and Using Layers." (From yocto-docs rev: 6bf5854dd355afdbc01c4c4fb94a4062bd9eae20) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 90 ++++++++++++---------- 1 file changed, 48 insertions(+), 42 deletions(-) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 9f7d04244a..4702ae94e3 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -77,7 +77,8 @@ you need. You can see the LayerIndex - to determine what types of layers already exist in the Yocto Project. + for a list of layers from the OpenEmbedded community that can be used in the + Yocto Project. Create a Directory: Create the directory for your layer. Traditionally, prepend the name of the folder with the string @@ -113,12 +114,14 @@ variable is then appended with the layer name. The BBFILE_PATTERN - variable immediately expands with a regular expression used to match files from - BBFILES into a particular layer, in this case by using - the base pathname. + variable is set to a regular expression and is used to match files + from BBFILES into a particular layer. + In this case, immediate expansion of + LAYERDIR + sets BBFILES_PATTERN to the layer's path. The BBFILE_PRIORITY - variable then assigns different priorities to the files in different layers. + variable then assigns a priority to the layer. Applying priorities is useful in situations where the same package might appear in multiple layers and allows you to choose what layer should take precedence. Note the use of the @@ -127,8 +130,9 @@ The LAYERDIR variable expands to the directory of the current layer and requires the immediate expansion operator so that BitBake does not wait to expand the variable when it's parsing a different directory. - BitBake can locate where other .bbclass and configuration files - are applied through the BBPATH environment variable. + BitBake locates included .bbclass, configuration, + and other files using the include and require + statements by way of the BBPATH environment variable. For these cases, BitBake uses the first file with the matching name found in BBPATH. This is similar to the way the PATH variable is used for binaries. @@ -218,9 +222,6 @@ During the processing of each conf/layer.conf file, BitBake adds the recipes, classes and configurations contained within the particular layer to the Yocto Project. - To create your own layer, independent of the Yocto Project files, - simply create a directory with a conf/layer.conf file and - add the directory to your bblayers.conf file. @@ -242,9 +243,9 @@ This means the original recipe and append file names are version number specific. If the underlying recipe is renamed to update to a newer version, the corresponding .bbappend file must be renamed as well. - During the build process, BitBake displays warnings on starting if it detects a + During the build process, BitBake displays an error on starting if it detects a .bbappend file that does not have an underlying recipe - with the proper name. + with a matching name. @@ -299,8 +300,10 @@ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - Using the immediate expansion assignment operator := and the trailing colon - are important so that the resulting list of pathnames is syntactically correct. + Using the immediate expansion assignment operator := is important because + of the reference to THISDIR. + The trailing colon character is important as it ensures that items in the list remain + colon-separated. BitBake automatically defines the THISDIR variable. You should never set this variable yourself. Using _prepend ensures your path will be searched prior to other @@ -358,37 +361,40 @@ Use the following form when running the layer management tool. $ bitbake-layers <command> [arguments] - - Available commands: - flatten - flattens layer configuration into a separate output directory. - help - display general help or help on a specified command - show_appends - list bbappend files and recipe files they apply to - show_layers - show current configured layers - show_overlayed - list overlayed recipes (where there is a recipe in another layer that has a higher layer priority) - help - display general help or help on a specified command - - - - Flattening your layer configuration builds a "flattened" directory that contains - the contents of all layers, with any overlayed recipes removed and any - recipe append files (.bbappend) appended to the corresponding recipes. - You might have to perform some manual cleanup of the flattened layer as follows: + The following list describes the available commands: - Non-recipe files (such as patches) are overwritten. - The flatten command shows a warning for these files. - Anything beyond the normal layer setup has been added to - the layer.conf file. - Only the lowest priority layer's layer.conf is used. + flatten: + Flattens the layer configuration into a separate output directory. + Flattening your layer configuration builds a "flattened" directory that contains + the contents of all layers, with any overlayed recipes removed and any + recipe append files (.bbappend) appended to the corresponding recipes. + You might have to perform some manual cleanup of the flattened layer as follows: + + Non-recipe files (such as patches) are overwritten. + The flatten command shows a warning for these files. + Anything beyond the normal layer setup has been added to + the layer.conf file. + Only the lowest priority layer's layer.conf is used. + + Overridden and appended items from .bbappend + files need to be cleaned up. + For example, the contents of each .bbappend end up in the + flattened recipe. + However, if there are appended or changed variable values, you need to tidy + these up yourself. + + help: + Displays general help or help on a specified command. + show_appends: + Lists .bbappend files and the recipe files to which + they apply. + show_layers: + Show the current configured layers. + show_overlayed: + Lists overlayed recipes. + Overlayed recipes appear in another layer that has a higher layer priority. - Overridden and appended items from .bbappend - files never need to be cleaned up. -- cgit v1.2.3-54-g00ecf