diff mbox series

[master-next] bitbake-user-manual-environment-setup: Document "{THISDIR}" in bb-layers

Message ID 20251105232718.2801446-1-yoann.congal@smile.fr
State New
Headers show
Series [master-next] bitbake-user-manual-environment-setup: Document "{THISDIR}" in bb-layers | expand

Commit Message

Yoann Congal Nov. 5, 2025, 11:27 p.m. UTC 
From: Yoann Congal <yoann.congal@smile.fr>

A "bb-layers" element can either:
* start with "{THISDIR}/meta-xxx", then "meta-xxx" is found relative to
  the configuration file,
* or not, the layer is found where bitbake-setup has cloned
  the layer from the "sources" list (usually a layers/ directory)

Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
Cc: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-environment-setup.rst                  | 3 +++
 1 file changed, 3 insertions(+)

Comments

Antonin Godard Nov. 6, 2025, 7:58 a.m. UTC | #1 
Hi,

On Thu Nov 6, 2025 at 12:27 AM CET, Yoann Congal wrote:
> From: Yoann Congal <yoann.congal@smile.fr>
>
> A "bb-layers" element can either:
> * start with "{THISDIR}/meta-xxx", then "meta-xxx" is found relative to
>   the configuration file,
> * or not, the layer is found where bitbake-setup has cloned
>   the layer from the "sources" list (usually a layers/ directory)
>
> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
> Cc: Antonin Godard <antonin.godard@bootlin.com>
> ---
>  .../bitbake-user-manual-environment-setup.rst                  | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index ad8143711..d9b7492b9 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -593,6 +593,9 @@ These files are written in the JSON file format and are stored in a
>        variables to include in :term:`BB_ENV_PASSTHROUGH_ADDITIONS`.
>  
>     -  ``bb-layers`` (*optional*): Layers to add to the ``bblayers.conf`` file.
> +      If the path starts by ``{THISDIR}/``, it will be relative to the directory
> +      containing the configuration file. If not, it will be relative to the
> +      directory used by ``bitbake-setup`` to store the sources.
>        This cannot be used in conjunction with the ``oe-template`` option.
>  
>     -  ``oe-template`` (*optional*, OpenEmbedded specific): OpenEmbedded template

I actually did write something about it yesterday (not sent yet). I extended it
a bit more, namely to show the common use-case. Your patch helped me clarify it
further, thanks. Let me know if making what follows part of my patch if ok to
you:

   -  ``bb-layers`` (*optional*): Layers to add to the ``bblayers.conf`` file
      (paths are relative to the ``layers/`` directory of a :term:`Setup`,
      unless ``{THISDIR}`` is used, see below).

      The ``bb-layers`` option cannot be used in conjunction with the
      ``oe-template`` option where the ``bblayers.conf`` files comes from the
      template itself.

      Local layers (layers not part of the ``sources``) can be added to
      ``bb-layers`` by specifying their path with the ``{THISDIR}`` special
      keyword. For example::

         {
            ...
            "bb-layers": [
               "{THISDIR}/meta-myproject"
            ],
            ...
         }

      ``{THISDIR}`` translates to the parent directory of the current
      :term:`Generic Configuration` file.

      This useful for a project that holds a single :term:`generic
      configuration` file next to a local layer::

         ├── meta-myproject/
         └── myproject.conf.json

Antonin
Alexander Kanavin Nov. 6, 2025, 8:28 a.m. UTC | #2 
On Thu, 6 Nov 2025 at 08:59, Antonin Godard via lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
>       This useful for a project that holds a single :term:`generic
>       configuration` file next to a local layer::
>
>          ├── meta-myproject/
>          └── myproject.conf.json

I thought the use case should be described along these lines:

This is useful when (one or more) configuration files and (one or
more) layers are hosted in the same git repository, which is cloned
and managed independently from bitbake-setup workflows.

Alex
Yoann Congal Nov. 6, 2025, 8:43 a.m. UTC | #3 
Le jeu. 6 nov. 2025 à 08:58, Antonin Godard <antonin.godard@bootlin.com> a
écrit :

> Hi,
>
> On Thu Nov 6, 2025 at 12:27 AM CET, Yoann Congal wrote:
> > From: Yoann Congal <yoann.congal@smile.fr>
> >
> > A "bb-layers" element can either:
> > * start with "{THISDIR}/meta-xxx", then "meta-xxx" is found relative to
> >   the configuration file,
> > * or not, the layer is found where bitbake-setup has cloned
> >   the layer from the "sources" list (usually a layers/ directory)
> >
> > Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
> > Cc: Antonin Godard <antonin.godard@bootlin.com>
> > ---
> >  .../bitbake-user-manual-environment-setup.rst                  | 3 +++
> >  1 file changed, 3 insertions(+)
> >
> > diff --git
> a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > index ad8143711..d9b7492b9 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > @@ -593,6 +593,9 @@ These files are written in the JSON file format and
> are stored in a
> >        variables to include in :term:`BB_ENV_PASSTHROUGH_ADDITIONS`.
> >
> >     -  ``bb-layers`` (*optional*): Layers to add to the
> ``bblayers.conf`` file.
> > +      If the path starts by ``{THISDIR}/``, it will be relative to the
> directory
> > +      containing the configuration file. If not, it will be relative to
> the
> > +      directory used by ``bitbake-setup`` to store the sources.
> >        This cannot be used in conjunction with the ``oe-template``
> option.
> >
> >     -  ``oe-template`` (*optional*, OpenEmbedded specific): OpenEmbedded
> template
>
> I actually did write something about it yesterday (not sent yet). I
> extended it
> a bit more, namely to show the common use-case. Your patch helped me
> clarify it
> further, thanks. Let me know if making what follows part of my patch if ok
> to
> you:
>

That is very good. Definitively OK to me.


>
>    -  ``bb-layers`` (*optional*): Layers to add to the ``bblayers.conf``
> file
>       (paths are relative to the ``layers/`` directory of a :term:`Setup`,
>       unless ``{THISDIR}`` is used, see below).
>
>       The ``bb-layers`` option cannot be used in conjunction with the
>       ``oe-template`` option where the ``bblayers.conf`` files comes from
> the
>       template itself.
>
>       Local layers (layers not part of the ``sources``) can be added to
>       ``bb-layers`` by specifying their path with the ``{THISDIR}`` special
>       keyword. For example::
>
>          {
>             ...
>             "bb-layers": [
>                "{THISDIR}/meta-myproject"
>             ],
>             ...
>          }
>
>       ``{THISDIR}`` translates to the parent directory of the current
>       :term:`Generic Configuration` file.
>
>       This useful for a project that holds a single :term:`generic
>       configuration` file next to a local layer::
>
>          ├── meta-myproject/
>          └── myproject.conf.json
>
> Antonin
>
> --
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>
>
Antonin Godard Nov. 6, 2025, 9:12 a.m. UTC | #4 
Hi,

On Thu Nov 6, 2025 at 9:28 AM CET, Alexander Kanavin via lists.yoctoproject.org wrote:
> On Thu, 6 Nov 2025 at 08:59, Antonin Godard via lists.yoctoproject.org
> <antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
>>       This useful for a project that holds a single :term:`generic
>>       configuration` file next to a local layer::
>>
>>          ├── meta-myproject/
>>          └── myproject.conf.json
>
> I thought the use case should be described along these lines:
>
> This is useful when (one or more) configuration files and (one or
> more) layers are hosted in the same git repository, which is cloned
> and managed independently from bitbake-setup workflows.

Rephrased, thanks. I'm about to send the v2.

Antonin
Alexander Kanavin Nov. 6, 2025, 11:50 a.m. UTC | #5 
On Thu, 6 Nov 2025 at 10:12, Antonin Godard <antonin.godard@bootlin.com> wrote:
> >>       This useful for a project that holds a single :term:`generic
> >>       configuration` file next to a local layer::
> >>
> >>          ├── meta-myproject/
> >>          └── myproject.conf.json
> >
> > I thought the use case should be described along these lines:
> >
> > This is useful when (one or more) configuration files and (one or
> > more) layers are hosted in the same git repository, which is cloned
> > and managed independently from bitbake-setup workflows.
>
> Rephrased, thanks. I'm about to send the v2.

Note I just sent
https://lists.openembedded.org/g/bitbake-devel/message/18285

I do apologize for shifting the configuration format like this at the
last moment, but I do believe avoiding tokens and not doing
post-prosessing on values is beneficial for clarity and validation.

Alex
diff mbox series

Patch

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index ad8143711..d9b7492b9 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -593,6 +593,9 @@  These files are written in the JSON file format and are stored in a
       variables to include in :term:`BB_ENV_PASSTHROUGH_ADDITIONS`.
 
    -  ``bb-layers`` (*optional*): Layers to add to the ``bblayers.conf`` file.
+      If the path starts by ``{THISDIR}/``, it will be relative to the directory
+      containing the configuration file. If not, it will be relative to the
+      directory used by ``bitbake-setup`` to store the sources.
       This cannot be used in conjunction with the ``oe-template`` option.
 
    -  ``oe-template`` (*optional*, OpenEmbedded specific): OpenEmbedded template