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
+ $ recipetool -h
+ NOTE: Starting bitbake server...
+ usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ...
- -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:
+ OpenEmbedded recipe tool
- -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.
+ 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