Re: [docs] [PATCH v2] bitbake: doc: bitbake-user-manual: Add more explanations to OVERRIDES

* Re: [docs] [PATCH v2] bitbake: doc: bitbake-user-manual: Add more explanations to OVERRIDES
       [not found] ` <09f9337d978b9d0727de2a937eb417e8185ca0b3.camel@linuxfoundation.org>
@ 2021-11-15 13:15   ` Simon Eugster
       [not found]   ` <16B7BA9296511776.16692@lists.yoctoproject.org>
  1 sibling, 0 replies; 10+ messages in thread
From: Simon Eugster @ 2021-11-15 13:15 UTC (permalink / raw)
  To: Richard Purdie; +Cc: docs


[-- Attachment #1.1: Type: text/plain, Size: 5921 bytes --]

Hi Richard,

I found it confusing to have arm mentioned but not present in the example,
and wondered if machine would first be resolved to arm and then used as
override. But I also liked the good practice hint.

Will remove the DEPENDS:append and add a space, you are right. I did not
test it and only believed what I understood from a youtube video :)

Simon

Am Mo., 15. Nov. 2021 um 13:51 Uhr schrieb Richard Purdie <
richard.purdie@linuxfoundation.org>:

> On Mon, 2021-11-15 at 13:45 +0100, Simon A. Eugster wrote:
> > Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
> > ---
> >  bitbake/doc/README                            |  3 +-
> >  .../bitbake-user-manual-metadata.rst          | 35 +++++++++++++------
> >  2 files changed, 25 insertions(+), 13 deletions(-)
> >
> > diff --git a/bitbake/doc/README b/bitbake/doc/README
> > index 16e6cdf990..84e7cb702d 100644
> > --- a/bitbake/doc/README
> > +++ b/bitbake/doc/README
> > @@ -47,8 +47,7 @@ To install all required packages run:
> >
> >  To build the documentation locally, run:
> >
> > - $ cd documentation
> > - $ make -f Makefile.sphinx html
> > + $ make html
> >
> >  The resulting HTML index page will be _build/html/index.html, and you
> >  can browse your own copy of the locally generated documentation with
> > diff --git
> a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > index 119720d527..3449bc1f68 100644
> > --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> > @@ -268,7 +268,7 @@ examples::
> >     C = "cval"
> >     C =. "test"
> >
> > -The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains
> > +The variable ``B`` contains "bvaladditionaldata" and ``C`` contains
> >  "testcval".
> >
> >  Appending and Prepending (Override Style Syntax)
> > @@ -300,6 +300,12 @@ It is also possible to append and prepend to shell
> functions and
> >  BitBake-style Python functions. See the
> ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`"
> and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style
> python functions`"
> >  sections for examples.
> >
> > +.. note::
> > +
> > +   Before Honister (3.4), override style used ``_`` instead of ``:``,
> so you will
> > +   still find a lot of documentation using “_append”, “_prepend”, and
> > +   “_remove”.
> > +
> >  .. _removing-override-style-syntax:
> >
> >  Removal (Override Style Syntax)
> > @@ -517,20 +523,21 @@ variable.
> >  -  *Selecting a Variable:* The :term:`OVERRIDES` variable is a
> >     colon-character-separated list that contains items for which you want
> >     to satisfy conditions. Thus, if you have a variable that is
> > -   conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the
> > +   conditional on "arm", and "arm" is listed in :term:`OVERRIDES`, then
> the
> >     "arm"-specific version of the variable is used rather than the
> >     non-conditional version. Here is an example::
> >
> > -      OVERRIDES = "architecture:os:machine"
> > +      OVERRIDES = "foo:linux:arm"
> >        TEST = "default"
> > -      TEST_os = "osspecific"
> > -      TEST_nooverride = "othercondvalue"
> > +      TEST:arm = "armspecific"
> > +      TEST:nooverride = "othercondvalue"
> >
> > -   In this example, the :term:`OVERRIDES`
> > -   variable lists three overrides: "architecture", "os", and "machine".
> > -   The variable ``TEST`` by itself has a default value of "default". You
> > -   select the os-specific version of the ``TEST`` variable by appending
> > -   the "os" override to the variable (i.e. ``TEST_os``).
> > +   In this example, the :term:`OVERRIDES` variable lists three
> > +   overrides: "foo", "linux", and "arm". The variable ``TEST`` by itself
> > +   has a default value of "default", and the value of the “arm” specific
> > +   version “armspecific” is used because :term:`OVERRIDES` contains
> > +   “arm”. The “nooverride” specific version is not used because
> > +   :term:`OVERRIDES` does not contain “nooverride”.
>
> Why are you removing the mentions of architecture and machine here? It is
> in
> some ways a hint as to how the overrides are used in OE and elsewhere so
> I'm not
> sure that is a good thing to make it generic...
>
> >
> >     To better understand this, consider a practical example that assumes
> >     an OpenEmbedded metadata-based Linux kernel recipe file. The
> > @@ -546,15 +553,21 @@ variable.
> >        KBRANCH:qemux86-64 = "standard/common-pc-64/base"
> >        KBRANCH:qemumips64 = "standard/mti-malta64"
> >
> > +   This works because in poky the :term:`OVERRIDES` variable by default
> > +   includes the ``MACHINE`` variable, which is set to e.g. “qemux86”.
> > +
> >  -  *Appending and Prepending:* BitBake also supports append and prepend
> >     operations to variable values based on whether a specific item is
> >     listed in :term:`OVERRIDES`. Here is an example::
> >
> >        DEPENDS = "glibc ncurses"
> >        OVERRIDES = "machine:local"
> > +      DEPENDS:append = "defaultappend"
> >        DEPENDS:append:machine = "libmad"
> >
> > -   In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
> > +   In this example, :term:`DEPENDS` becomes "glibc ncurses libmad". The
> > +   default append is ``DEPENDS:append`` is not used because the override
> > +   mechanism choses the specific ``:append``.
>
> This example looks incorrect to me, I think it would become:
>
> "glibc ncursesdefaultappendlibmad"
>
> although the example should say DEPENDS:append:machine = " libmad" as
> there is a
> missing space there too.
>
> Cheers,
>
> Richard
>
>
>
>
>

[-- Attachment #1.2: Type: text/html, Size: 7452 bytes --]

[-- Attachment #2: 0001-bitbake-doc-bitbake-user-manual-Add-more-explanation.patch --]
[-- Type: text/x-patch, Size: 4548 bytes --]

From 432a7e4a5bbf2c16a2f2182e1dc77f2e5f16ebb5 Mon Sep 17 00:00:00 2001
From: "Simon A. Eugster" <simon.eu@gmail.com>
Date: Mon, 15 Nov 2021 13:30:10 +0100
Subject: [PATCH] bitbake: doc: bitbake-user-manual: Add more explanations to
 OVERRIDES

Signed-off-by: Simon A. Eugster <simon.eu@gmail.com>
---
 bitbake/doc/README                            |  3 +-
 .../bitbake-user-manual-metadata.rst          | 33 ++++++++++++-------
 2 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/bitbake/doc/README b/bitbake/doc/README
index 16e6cdf990..84e7cb702d 100644
--- a/bitbake/doc/README
+++ b/bitbake/doc/README
@@ -47,8 +47,7 @@ To install all required packages run:
 
 To build the documentation locally, run:
 
- $ cd documentation
- $ make -f Makefile.sphinx html
+ $ make html
 
 The resulting HTML index page will be _build/html/index.html, and you
 can browse your own copy of the locally generated documentation with
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 119720d527..cea0ce6da8 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -268,7 +268,7 @@ examples::
    C = "cval"
    C =. "test"
 
-The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains
+The variable ``B`` contains "bvaladditionaldata" and ``C`` contains
 "testcval".
 
 Appending and Prepending (Override Style Syntax)
@@ -300,6 +300,12 @@ It is also possible to append and prepend to shell functions and
 BitBake-style Python functions. See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`" and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions`"
 sections for examples.
 
+.. note::
+
+   Before Honister (3.4), override style used ``_`` instead of ``:``, so you will
+   still find a lot of documentation using “_append”, “_prepend”, and
+   “_remove”.
+
 .. _removing-override-style-syntax:
 
 Removal (Override Style Syntax)
@@ -517,20 +523,22 @@ variable.
 -  *Selecting a Variable:* The :term:`OVERRIDES` variable is a
    colon-character-separated list that contains items for which you want
    to satisfy conditions. Thus, if you have a variable that is
-   conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the
+   conditional on "arm", and "arm" is listed in :term:`OVERRIDES`, then the
    "arm"-specific version of the variable is used rather than the
    non-conditional version. Here is an example::
 
-      OVERRIDES = "architecture:os:machine"
+      # Typically, OVERRIDES contains something like architecture:os:machine
+      OVERRIDES = "linux:arm"
       TEST = "default"
-      TEST_os = "osspecific"
-      TEST_nooverride = "othercondvalue"
+      TEST:arm = "armspecific"
+      TEST:nooverride = "othercondvalue"
 
-   In this example, the :term:`OVERRIDES`
-   variable lists three overrides: "architecture", "os", and "machine".
-   The variable ``TEST`` by itself has a default value of "default". You
-   select the os-specific version of the ``TEST`` variable by appending
-   the "os" override to the variable (i.e. ``TEST_os``).
+   In this example, the :term:`OVERRIDES` variable lists three
+   overrides: "foo", "linux", and "arm". The variable ``TEST`` by itself
+   has a default value of "default", and the value of the “arm” specific
+   version “armspecific” is used because :term:`OVERRIDES` contains
+   “arm”. The “nooverride” specific version is not used because
+   :term:`OVERRIDES` does not contain “nooverride”.
 
    To better understand this, consider a practical example that assumes
    an OpenEmbedded metadata-based Linux kernel recipe file. The
@@ -546,13 +554,16 @@ variable.
       KBRANCH:qemux86-64 = "standard/common-pc-64/base"
       KBRANCH:qemumips64 = "standard/mti-malta64"
 
+   This works because in poky the :term:`OVERRIDES` variable by default
+   includes the ``MACHINE`` variable, which is set to e.g. “qemux86”.
+
 -  *Appending and Prepending:* BitBake also supports append and prepend
    operations to variable values based on whether a specific item is
    listed in :term:`OVERRIDES`. Here is an example::
 
       DEPENDS = "glibc ncurses"
       OVERRIDES = "machine:local"
-      DEPENDS:append:machine = "libmad"
+      DEPENDS:append:machine = " libmad"
 
    In this example, :term:`DEPENDS` becomes "glibc ncurses libmad".
 
-- 
2.30.2


^ permalink raw reply related	[flat|nested] 10+ messages in thread