From b3732ab1aa9d03ae0bc8afa21c25dedc8653831c Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 21 Mar 2018 07:30:14 -0700 Subject: dev-manual: Cleaned up layer naming terminology Reality dictates that the YP does not treat layer naming consistently. Layers are talked about as the "meta-whatever" layer and never the "whatever" layer. However, the tooling sometimes appends or uses just the "whatever" part of the layer name. A good example is the meta-yocto-bsp configuration file. All the variables in there use just the root name of a layer's name. In the manuals, I had been distinguishing the layer name as just the "whatever" part sans "meta-". I talked about the convention of using "meta-" in front of layer names, etc. Well, this is confusing in light of how everyone says a layer's name is "meta-whatever". So, I fixed all this up. (From yocto-docs rev: 79e52f6ccf4246fc69a460ce9d3a4a18720a9442) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 171 +++++++++++++-------- 1 file changed, 111 insertions(+), 60 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 11b53ac116..11a7065c4e 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -73,14 +73,18 @@ meta-GUI_xyz meta-mymachine - Realize that the name of your layer does not include - the "meta-" string. - For example, the names of the previous three layers - are "mylayer", "GUI_xyz", and "mymachine". - Following this layer directory naming convention can - save you trouble later when tools or components - "assume" your layer resides in a directory whose name - starts with "meta-". + With rare exceptions, a layer's name follows this + form: + + meta-root_name + + Following this layer naming convention can + save you trouble later when tools, components, or + variables "assume" your layer name begins with "meta-". + A notable example is in configuration files as + shown in the following step where layer names without + the "meta-" string are appended + to several variables used in the configuration. Create a Layer Configuration @@ -141,7 +145,7 @@ The BBFILE_COLLECTIONS - variable is appended with the layer name, + variable is appended with the layer's root name, which is "yoctobsp" in this example. @@ -637,7 +641,8 @@ BitBake parses each conf/layer.conf file - as specified in the BBLAYERS variable + from the top down as specified in the + BBLAYERS variable within the conf/bblayers.conf file. During the processing of each conf/layer.conf file, BitBake adds the @@ -815,8 +820,7 @@ To specify the layer's priority manually, use the BBFILE_PRIORITY - variable. - For example: + variable and append the layer's root name: BBFILE_PRIORITY_mylayer = "1" @@ -837,7 +841,8 @@ Managing Layers - You can use the BitBake layer management tool to provide a view + You can use the BitBake layer management tool + bitbake-layers to provide a view into the structure of recipes across a multi-layer project. Being able to generate output that reports on configured layers with their paths and priorities and on @@ -846,42 +851,88 @@ - Use the following form when running the layer management tool. + For help on the BitBake layer management tool, use the + following command: - $ bitbake-layers command [arguments] + $ bitbake-layers --help + NOTE: Starting bitbake server... + usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ... + + BitBake layers utility + + optional arguments: + -d, --debug Enable debug output + -q, --quiet Print only errors + -F, --force Force add without recipe parse verification + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + <subcommand> + show-layers show current configured layers. + show-overlayed list overlayed recipes (where the same recipe exists + in another layer) + show-recipes list available recipes, showing the layer they are + provided by + show-appends list bbappend files and recipe files they apply to + show-cross-depends Show dependencies between recipes that cross layer + boundaries. + add-layer Add one or more layers to bblayers.conf. + remove-layer Remove one or more layers from bblayers.conf. + flatten flatten layer configuration into a separate output + directory. + layerindex-fetch Fetches a layer from a layer index along with its + dependent layers, and adds them to conf/bblayers.conf. + layerindex-show-depends + Find layer dependencies from layer index. + create-layer Create a basic layer + + Use bitbake-layers <subcommand> --help to get help on a specific command + + + The following list describes the available commands: - help: + + help: Displays general help or help on a specified command. - show-layers: + + show-layers: Shows the current configured layers. - show-recipes: - Lists available recipes and the layers that provide them. - - show-overlayed: + + show-overlayed: Lists overlayed recipes. A recipe is overlayed when a recipe with the same name exists in another layer that has a higher layer priority. - show-appends: + + show-recipes: + Lists available recipes and the layers that provide them. + + + show-appends: Lists .bbappend files and the recipe files to which they apply. - show-cross-depends: + + show-cross-depends: Lists dependency relationships between recipes that cross layer boundaries. - add-layer: + + add-layer: Adds a layer to bblayers.conf. - remove-layer: + + remove-layer: Removes a layer from bblayers.conf - flatten: + + flatten: Flattens the layer configuration into a separate output directory. Flattening your layer configuration builds a "flattened" @@ -892,18 +943,21 @@ You might have to perform some manual cleanup of the flattened layer as follows: - Non-recipe files (such as patches) + + Non-recipe files (such as patches) are overwritten. The flatten command shows a warning for these files. - Anything beyond the normal layer + + 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 + + Overridden and appended items from .bbappend files need to be cleaned up. The contents of each @@ -1568,47 +1622,43 @@ and have sourced the build environment setup script (i.e. oe-init-build-env). - Here is the basic recipetool syntax: - - Running recipetool -h or - recipetool create -h produces the - Python-generated help, which presented differently - than what follows here. - + To get help on the tool, use the following command: - recipetool -h - recipetool create [-h] - recipetool [-d] [-q] [--color auto | always | never ] create -o OUTFILE [-m] [-x EXTERNALSRC] source - - -d Enables debug output. - -q Outputs only errors (quiet mode). - --color Colorizes the output automatically, always, or never. - -h Displays Python generated syntax for recipetool. - create Causes recipetool to create a base recipe. The create - command is further defined with these options: - - -o OUTFILE Specifies the full path and filename for the generated - recipe. - -m Causes the recipe to be machine-specific rather than - architecture-specific (default). - -x EXTERNALSRC Fetches and extracts source files from source - and places them in EXTERNALSRC. - source must be a URL. - -h Displays Python-generated syntax for create. - source Specifies the source code on which to base the - recipe. + $ recipetool -h + NOTE: Starting bitbake server... + usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ... + + OpenEmbedded recipe tool + + options: + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + create Create a new recipe + newappend Create a bbappend for the specified target in the specified + layer + setvar Set a variable within a recipe + appendfile Create/update a bbappend to replace a target file + appendsrcfiles Create/update a bbappend to add or replace source files + appendsrcfile Create/update a bbappend to add or replace a source file + Use recipetool <subcommand> --help to get help on a specific command - Running recipetool create -o OUTFILE + Running + recipetool create -o OUTFILE creates the base recipe and locates it properly in the layer that contains your source files. Following are some syntax examples: - Use this syntax to generate a recipe based on source. + Use this syntax to generate a recipe based on + source. Once generated, the recipe resides in the existing source code layer: @@ -1621,7 +1671,8 @@ recipetool create -o OUTFILE -x EXTERNALSRC source - Use this syntax to generate a recipe based on source. + Use this syntax to generate a recipe based on + source. The options direct recipetool to generate debugging information. Once generated, the recipe resides in the existing source -- cgit v1.2.3-54-g00ecf