@@ -452,7 +452,7 @@ The following commands run the tool to create a layer named
For more information
on layers and how to create them, see the
-:ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`
+:ref:`dev-manual/layers:Creating Your Own Layer`
section in the Yocto Project Development Tasks Manual.
Where To Go Next
@@ -1154,7 +1154,7 @@ Use these steps to create a BSP layer:
``create-layer`` subcommand to create a new general layer. For
instructions on how to create a general layer using the
``bitbake-layers`` script, see the
- ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
+ ":ref:`dev-manual/layers:Creating Your Own Layer`"
section in the Yocto Project Development Tasks Manual.
- *Create a Layer Configuration File:* Every layer needs a layer
@@ -27,7 +27,7 @@ layer. The following steps provide some more detail:
just placing configurations in a ``local.conf`` configuration file
makes it easier to reproduce the same build configuration when using
multiple build machines. See the
- ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
+ ":ref:`dev-manual/layers:Creating Your Own Layer`"
section for information on how to quickly set up a layer.
- *Create the distribution configuration file:* The distribution
@@ -14,18 +14,6 @@ section in the Yocto Project Overview and Concepts Manual.
Creating Your Own Layer
=======================
-.. note::
-
- It is very easy to create your own layers to use with the OpenEmbedded
- build system, as the Yocto Project ships with tools that speed up creating
- layers. This section describes the steps you perform by hand to create
- layers so that you can better understand them. For information about the
- layer-creation tools, see the
- ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`"
- section in the Yocto Project Board Support Package (BSP) Developer's
- Guide and the ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
- section further down in this manual.
-
Follow these general steps to create your layer without using tools:
#. *Check Existing Layers:* Before creating a new layer, you should be
@@ -35,10 +23,23 @@ Follow these general steps to create your layer without using tools:
the Yocto Project. You could find a layer that is identical or close
to what you need.
-#. *Create a Directory:* Create the directory for your layer. When you
- create the layer, be sure to create the directory in an area not
- associated with the Yocto Project :term:`Source Directory`
- (e.g. the cloned ``poky`` repository).
+ .. note::
+
+ For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`"
+ section in the Yocto Project Board Specific (BSP) Developer's Guide.
+
+#. *Create a new Layer:* Create the directory for your layer. The
+ ``bitbake-layers`` script with the ``create-layer`` subcommand simplifies
+ creating a new general layer. Place it next to the other layers in your
+ :term:`Source Directory`.
+
+ In its simplest form, you can use the following command form to create a
+ layer. The command creates a layer whose name corresponds to
+ "your_layer_name" in the current directory:
+
+ .. code-block:: console
+
+ $ bitbake-layers create-layer your_layer_name
While not strictly required, prepend the name of the directory with
the string "meta-". For example::
@@ -58,88 +59,84 @@ Follow these general steps to create your layer without using tools:
"meta-" string are appended to several variables used in the
configuration.
-#. *Create a Layer Configuration File:* Inside your new layer folder,
- you need to create a ``conf/layer.conf`` file. It is easiest to take
- an existing layer configuration file and copy that to your layer's
- ``conf`` directory and then modify the file as needed.
-
- The ``meta-yocto-bsp/conf/layer.conf`` file in the Yocto Project
- :yocto_git:`Source Repositories </poky/tree/meta-yocto-bsp/conf>`
- demonstrates the required syntax. For your layer, you need to replace
- "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz"
- for a layer named "meta-machinexyz")::
-
- # We have a conf and classes directory, add to BBPATH
- BBPATH .= ":${LAYERDIR}"
-
- # We have recipes-* directories, add to BBFILES
- BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
- ${LAYERDIR}/recipes-*/*/*.bbappend"
-
- BBFILE_COLLECTIONS += "yoctobsp"
- BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
- BBFILE_PRIORITY_yoctobsp = "5"
- LAYERVERSION_yoctobsp = "4"
- LAYERSERIES_COMPAT_yoctobsp = "walnascar"
-
- Here is an explanation of the layer configuration file:
-
- - :term:`BBPATH`: Adds the layer's
- root directory to BitBake's search path. Through the use of the
- :term:`BBPATH` variable, BitBake locates class files (``.bbclass``),
- configuration files, and files that are included with ``include``
- and ``require`` statements. For these cases, BitBake uses the
- first file that matches the name found in :term:`BBPATH`. This is
- similar to the way the ``PATH`` variable is used for binaries. It
- is recommended, therefore, that you use unique class and
- configuration filenames in your custom layer.
-
- - :term:`BBFILES`: Defines the
- location for all recipes in the layer.
-
- - :term:`BBFILE_COLLECTIONS`:
- Establishes the current layer through a unique identifier that is
- used throughout the OpenEmbedded build system to refer to the
- layer. In this example, the identifier "yoctobsp" is the
- representation for the container layer named "meta-yocto-bsp".
-
- - :term:`BBFILE_PATTERN`:
- Expands immediately during parsing to provide the directory of the
- layer.
-
- - :term:`BBFILE_PRIORITY`:
- Establishes a priority to use for recipes in the layer when the
- OpenEmbedded build finds recipes of the same name in different
- layers.
-
- - :term:`LAYERVERSION`:
- Establishes a version number for the layer. You can use this
- version number to specify this exact version of the layer as a
- dependency when using the
- :term:`LAYERDEPENDS`
- variable.
-
- - :term:`LAYERDEPENDS`:
- Lists all layers on which this layer depends (if any).
-
- - :term:`LAYERSERIES_COMPAT`:
- Lists the :yocto_home:`Yocto Project releases </development/releases/>`
- for which the current version is compatible. This variable is a good
- way to indicate if your particular layer is current.
+ As an example, the following command creates a layer named ``meta-scottrif``
+ in your home directory:
+ .. code-block:: console
+
+ $ bitbake-layers create-layer meta-scottrif
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer meta-scottrif'
+
+ In order to use a layer with the OpenEmbedded build system, you
+ need to add the layer to your ``bblayers.conf`` configuration
+ file. See the ":ref:`dev-manual/layers:adding a layer using the
+ \`\`bitbake-layers\`\` script`" section for more information.
+
+ The default mode of the script's operation with this subcommand is to
+ create a layer with the following:
+
+ - A ``conf/layer.conf`` configuration file with default definitions.
+
+ Here is an explanation of the layer configuration file:
+
+ - :term:`BBPATH`: Adds the layer's root directory to BitBake's search
+ path. Through the use of the :term:`BBPATH` variable, BitBake locates
+ class files (``.bbclass``), configuration files, and files that are
+ included with ``include`` and ``require`` statements. For these cases,
+ BitBake uses the first file that matches the name found in
+ :term:`BBPATH`. This is similar to the way the ``PATH`` variable is
+ used for binaries. It is recommended, therefore, that you use unique
+ class and configuration filenames in your custom layer.
+
+ - :term:`BBFILES`: Defines the location for all recipes in the layer.
+
+ - :term:`BBFILE_COLLECTIONS`: Establishes the current layer through a
+ unique identifier that is used throughout the OpenEmbedded build system
+ to refer to the layer. In this example, the identifier "yoctobsp" is
+ the representation for the container layer named "meta-yocto-bsp".
+
+ - :term:`BBFILE_PATTERN`: Expands immediately during parsing to provide
+ the directory of the layer.
+
+ - :term:`BBFILE_PRIORITY`: Establishes a priority to use for recipes in
+ the layer when the OpenEmbedded build finds recipes of the same name in
+ different layers.
+
+ - :term:`LAYERVERSION`: Establishes a version number for the layer. You
+ can use this version number to specify this exact version of the layer
+ as a dependency when using the :term:`LAYERDEPENDS` variable.
+
+ - :term:`LAYERDEPENDS`: Lists all layers on which this layer depends (if
+ any).
+
+ - :term:`LAYERSERIES_COMPAT`: Lists the :yocto_home:`Yocto Project
+ releases </development/releases/>` for which the current version is
+ compatible. This variable is a good way to indicate if your particular
+ layer is current.
+
+ - A ``recipes-example`` subdirectory that contains a further
+ subdirectory named ``example``, which contains an ``example.bb``
+ recipe file.
+
+ - A ``COPYING.MIT``, which is the license statement for the layer. The
+ script assumes you want to use the MIT license, which is typical for
+ most layers, for the contents of the layer itself.
+
+ - A ``README`` file, which is a file describing the contents of your
+ new layer.
- .. note::
- A layer does not have to contain only recipes ``.bb`` or append files
- ``.bbappend``. Generally, developers create layers using
- ``bitbake-layers create-layer``.
- See ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`",
- explaining how the ``layer.conf`` file is created from a template located in
- ``meta/lib/bblayers/templates/layer.conf``.
- In fact, none of the variables set in ``layer.conf`` are mandatory,
- except when :term:`BBFILE_COLLECTIONS` is present. In this case
- :term:`LAYERSERIES_COMPAT` and :term:`BBFILE_PATTERN` have to be
- defined too.
+ If you want to set the priority of the layer to other than the default value
+ of "6", you can either use the ``--priority`` option or you can edit the
+ :term:`BBFILE_PRIORITY` value in the ``conf/layer.conf`` after the script
+ creates it. Furthermore, if you want to give the example recipe file some
+ name other than the default, you can use the ``--example-recipe-name``
+ option.
+
+ The easiest way to see how the ``bitbake-layers create-layer`` command
+ works is to experiment with the script. You can also read the usage
+ information by running ``bitbake-layers --help``.
#. *Add Content:* Depending on the type of layer, add the content. If
the layer adds support for a machine, add the machine configuration
@@ -874,85 +871,6 @@ The following list describes the available commands:
- ``show-machines``: Lists the machines available in the currently configured layers.
-Creating a General Layer Using the ``bitbake-layers`` Script
-============================================================
-
-The ``bitbake-layers`` script with the ``create-layer`` subcommand
-simplifies creating a new general layer.
-
-.. note::
-
- - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`"
- section in the Yocto
- Project Board Specific (BSP) Developer's Guide.
-
- - In order to use a layer with the OpenEmbedded build system, you
- need to add the layer to your ``bblayers.conf`` configuration
- file. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`"
- section for more information.
-
-The default mode of the script's operation with this subcommand is to
-create a layer with the following:
-
-- A layer priority of 6.
-
-- A ``conf`` subdirectory that contains a ``layer.conf`` file.
-
-- A ``recipes-example`` subdirectory that contains a further
- subdirectory named ``example``, which contains an ``example.bb``
- recipe file.
-
-- A ``COPYING.MIT``, which is the license statement for the layer. The
- script assumes you want to use the MIT license, which is typical for
- most layers, for the contents of the layer itself.
-
-- A ``README`` file, which is a file describing the contents of your
- new layer.
-
-In its simplest form, you can use the following command form to create a
-layer. The command creates a layer whose name corresponds to
-"your_layer_name" in the current directory::
-
- $ bitbake-layers create-layer your_layer_name
-
-As an example, the following command creates a layer named ``meta-scottrif``
-in your home directory::
-
- $ cd /usr/home
- $ bitbake-layers create-layer meta-scottrif
- NOTE: Starting bitbake server...
- Add your new layer with 'bitbake-layers add-layer meta-scottrif'
-
-If you want to set the priority of the layer to other than the default
-value of "6", you can either use the ``--priority`` option or you
-can edit the
-:term:`BBFILE_PRIORITY` value
-in the ``conf/layer.conf`` after the script creates it. Furthermore, if
-you want to give the example recipe file some name other than the
-default, you can use the ``--example-recipe-name`` option.
-
-The easiest way to see how the ``bitbake-layers create-layer`` command
-works is to experiment with the script. You can also read the usage
-information by entering the following::
-
- $ bitbake-layers create-layer --help
- NOTE: Starting bitbake server...
- usage: bitbake-layers create-layer [-h] [--priority PRIORITY]
- [--example-recipe-name EXAMPLERECIPE]
- layerdir
-
- Create a basic layer
-
- positional arguments:
- layerdir Layer directory to create
-
- optional arguments:
- -h, --help show this help message and exit
- --priority PRIORITY, -p PRIORITY
- Layer directory to create
- --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE
- Filename of the example recipe
-
Adding a Layer Using the ``bitbake-layers`` Script
==================================================
@@ -95,7 +95,7 @@ section:
Support (BSP) Developer's Guide, respectively. For information on how to
use the ``bitbake-layers create-layer`` command to quickly set up a layer,
see the
- ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
+ ":ref:`dev-manual/layers:Creating Your Own Layer`"
section in the Yocto Project Development Tasks Manual.
#. *Inform the BitBake Build Environment About Your Layer:* As directed
@@ -190,7 +190,7 @@ section:
Support (BSP) Developer's Guide, respectively. For information on how to
use the ``bitbake-layers create-layer`` command to quickly set up a layer,
see the
- ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
+ ":ref:`dev-manual/layers:Creating Your Own Layer`"
section in the Yocto Project Development Tasks Manual.
#. *Inform the BitBake Build Environment About Your Layer:* As directed
@@ -276,7 +276,7 @@ section in the Yocto Project Development Tasks Manual.
The Yocto Project comes with many tools that simplify tasks you need
to perform. One such tool is the ``bitbake-layers create-layer``
command, which simplifies creating a new layer. See the
- ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`"
+ ":ref:`dev-manual/layers:Creating Your Own Layer`"
section in the Yocto Project Development Tasks Manual for
information on how to use this script to quick set up a new layer.
@@ -56,8 +56,7 @@ Transitioning to a custom environment for systems development
#. **Add a new layer for any custom recipes and metadata you create**.
Use the ``bitbake-layers create-layer`` command. The ``bitbake-layers`` tool
also provides a number of other useful layer-related commands. See
- :ref:`dev-manual/layers:creating a general layer using the
- \`\`bitbake-layers\`\` script` section.
+ :ref:`dev-manual/layers:Creating Your Own Layer` section.
#. **Create your own layer for the BSP you're going to use**.
It is not common that you would need to create an entire BSP from scratch
The first section of the layers document shows how to manually create a layer step-by-step, and references bitbake-layers create-layer at the end. Change the approach of this section to show how to use the bitbake-layers create-layer command to create a layer, and then explain how a layer is organized and configured. This avoids repetition, and we should encourage users to use pre-built tools when they can do things in a less error-prone way. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/brief-yoctoprojectqs/index.rst | 2 +- documentation/bsp-guide/bsp.rst | 2 +- documentation/dev-manual/custom-distribution.rst | 2 +- documentation/dev-manual/layers.rst | 266 +++++++-------------- documentation/kernel-dev/common.rst | 6 +- .../transitioning-to-a-custom-environment.rst | 3 +- 6 files changed, 99 insertions(+), 182 deletions(-)