Re: [docs] [PATCH 11/53] dev-manual/layers.rst: remove obsolete poky repo references

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 12/24/25 5:31 PM, Antonin Godard via lists.yoctoproject.org wrote:
> 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(-)
> 
> diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
> index 84eb63c937..903dc242eb 100644
> --- a/documentation/brief-yoctoprojectqs/index.rst
> +++ b/documentation/brief-yoctoprojectqs/index.rst
> @@ -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
> diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
> index 2a451b2139..8e332aec07 100644
> --- a/documentation/bsp-guide/bsp.rst
> +++ b/documentation/bsp-guide/bsp.rst
> @@ -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
> diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst
> index 0bc386d606..55854f00ea 100644
> --- a/documentation/dev-manual/custom-distribution.rst
> +++ b/documentation/dev-manual/custom-distribution.rst
> @@ -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
> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
> index 667708e32b..15d54cc021 100644
> --- a/documentation/dev-manual/layers.rst
> +++ b/documentation/dev-manual/layers.rst
> @@ -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:
> +

suggestion:

"""
In its simplest form, you can use the following command to create a 
layer named "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

:term:`OpenEmbedded Build System`

> +   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.
> +

Maybe hint at bitbake-layers add-layer meta-scottrif as returned by the 
command just above?

> +   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:

"of the typical content 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,

Please use cross-references for include and require statements (also, 
include_all applies here as well).

> +         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.
> +

Please point at the bitbake documentation for this where we have nice 
examples of how to locate an include'd/require'd/include_all'd file.

> +      -  :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

:term:`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".
> +

Should we specify that this name is then used by other layers when 
specifying their dependencies via :term:`LAYERDEPENDS`?

> +      -  :term:`BBFILE_PATTERN`: Expands immediately during parsing to provide
> +         the directory of the layer.
> +

I think we need to explain this better (not necessarily in this patch) 
as it's the first time I pay attention to it. Is this why we can use 
${LAYERDIR} in BBFILES and it points to the proper absolute paths in the 
variable afterwards?

> +      -  :term:`BBFILE_PRIORITY`: Establishes a priority to use for recipes in
> +         the layer when the OpenEmbedded build finds recipes of the same name in

:term:`OpenEmbedded Build System` (missing "system" if you don't want to 
be using the cross-reference).

> +         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).
> +

Please specify this will try to find a layer whose BBFILE_COLLECTIONS 
contains this string (I believe that is the logic, but I'm not sure). 
E.g. you would depend on yoctobsp and not meta-yocto-bsp if you wanted 
to depend on meta-yocto-bsp?

> +      -  :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.
> +

Specify that this is the release *names* (all lowercase) and not the 
release version?

> +   -  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``.
>   

``bitbake-layers create-layer --help`` rather no?

Cheers,
Quentin