doc: bitbake ch 2: use example of nginx to explain DEFAULT_PREFERENCE

At the moment, the section on explaining DEFAULT_PREFERENCE uses an
example of busybox, which does not even use this feature anymore.
Replace this with an example using "nginx", which does.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

Hi,

On Thu Jan 8, 2026 at 11:08 PM CET, Robert P. J. Day wrote:
>
> At the moment, the section on explaining DEFAULT_PREFERENCE uses an
> example of busybox, which does not even use this feature anymore.
> Replace this with an example using "nginx", which does.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> index d407f59c0..1638a8f5c 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> @@ -337,21 +337,22 @@ file that BitBake parses, you can change that preference::
>
>  .. note::
>
> -   It is common for a recipe to provide two versions -- a stable,
> -   numbered (and preferred) version, and a version that is automatically
> -   checked out from a source code repository that is considered more
> -   "bleeding edge" but can be selected only explicitly.
> -
> -   For example, in the OpenEmbedded codebase, there is a standard,
> -   versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
> -   is also a Git-based version, ``busybox_git.bb``, which explicitly
> -   contains the line ::
> -
> -     DEFAULT_PREFERENCE = "-1"
> -
> -   to ensure that the
> -   numbered, stable version is always preferred unless the developer
> -   selects otherwise.
> +   It is not uncommon for a given recipe to provide more than one
> +   version -- a stable (and preferred) version that should be selected
> +   by default, and a newer, development or "bleeding edge" version that
> +   will be selected only explicitly by the developer.
> +
> +   For example, at the moment, in the OpenEmbedded codebase, there are
> +   two versions of the ``nginx`` webserver: a stable "1.28.0" version
> +   that would be selected by default, and a newer "1.29.1" development
> +   version that a developer would need to choose explicitly.
> +
> +   This can be seen based on this snippet from the ``nginx`` 1.29.1
> +   recipe file::
> +
> +      # 1.28.x branch is the current stable branch, the recommended default
> +      # 1.29.x is the current mainline branches containing all new features
> +      DEFAULT_PREFERENCE = "-1"

We should consider dropping these kinds of phrasings in favor of generic
examples inspired from real life, e.g. "Consider the following example
recipe...". That way, no maintenance burden like this one.

Anyway, the updated example is fine to me as it is.

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks,
Antonin

On Fri, 9 Jan 2026, Antonin Godard via lists.openembedded.org wrote:

> Hi,
>
> On Thu Jan 8, 2026 at 11:08 PM CET, Robert P. J. Day wrote:
> >
> > At the moment, the section on explaining DEFAULT_PREFERENCE uses an
> > example of busybox, which does not even use this feature anymore.
> > Replace this with an example using "nginx", which does.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> > index d407f59c0..1638a8f5c 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> > @@ -337,21 +337,22 @@ file that BitBake parses, you can change that preference::
> >
> >  .. note::
> >
> > -   It is common for a recipe to provide two versions -- a stable,
> > -   numbered (and preferred) version, and a version that is automatically
> > -   checked out from a source code repository that is considered more
> > -   "bleeding edge" but can be selected only explicitly.
> > -
> > -   For example, in the OpenEmbedded codebase, there is a standard,
> > -   versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
> > -   is also a Git-based version, ``busybox_git.bb``, which explicitly
> > -   contains the line ::
> > -
> > -     DEFAULT_PREFERENCE = "-1"
> > -
> > -   to ensure that the
> > -   numbered, stable version is always preferred unless the developer
> > -   selects otherwise.
> > +   It is not uncommon for a given recipe to provide more than one
> > +   version -- a stable (and preferred) version that should be selected
> > +   by default, and a newer, development or "bleeding edge" version that
> > +   will be selected only explicitly by the developer.
> > +
> > +   For example, at the moment, in the OpenEmbedded codebase, there are
> > +   two versions of the ``nginx`` webserver: a stable "1.28.0" version
> > +   that would be selected by default, and a newer "1.29.1" development
> > +   version that a developer would need to choose explicitly.
> > +
> > +   This can be seen based on this snippet from the ``nginx`` 1.29.1
> > +   recipe file::
> > +
> > +      # 1.28.x branch is the current stable branch, the recommended default
> > +      # 1.29.x is the current mainline branches containing all new features
> > +      DEFAULT_PREFERENCE = "-1"
>
> We should consider dropping these kinds of phrasings in favor of generic
> examples inspired from real life, e.g. "Consider the following example
> recipe...". That way, no maintenance burden like this one.

  to *some* extent, i agree with you, but i also feel that it's
valuable to demonstrate some explanations with examples ripped
straight from the source code so that beginning developers can see
those things in action. i agree that this is not the *best* example to
use for this, though, but it will do for now.

rday

Hi Robert,

On 1/8/26 11:08 PM, Robert P. J. Day via lists.openembedded.org wrote:
> 
> At the moment, the section on explaining DEFAULT_PREFERENCE uses an
> example of busybox, which does not even use this feature anymore.
> Replace this with an example using "nginx", which does.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> 
> ---
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> index d407f59c0..1638a8f5c 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst
> @@ -337,21 +337,22 @@ file that BitBake parses, you can change that preference::
> 
>   .. note::
> 
> -   It is common for a recipe to provide two versions -- a stable,
> -   numbered (and preferred) version, and a version that is automatically
> -   checked out from a source code repository that is considered more
> -   "bleeding edge" but can be selected only explicitly.
> -
> -   For example, in the OpenEmbedded codebase, there is a standard,
> -   versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
> -   is also a Git-based version, ``busybox_git.bb``, which explicitly
> -   contains the line ::
> -
> -     DEFAULT_PREFERENCE = "-1"
> -
> -   to ensure that the
> -   numbered, stable version is always preferred unless the developer
> -   selects otherwise.
> +   It is not uncommon for a given recipe to provide more than one
> +   version -- a stable (and preferred) version that should be selected
> +   by default, and a newer, development or "bleeding edge" version that
> +   will be selected only explicitly by the developer.
> +
> +   For example, at the moment, in the OpenEmbedded codebase, there are

While reading this, I thought you meant oe-core. It is actually 
meta-openembedded, please make this more specific (and maybe consider 
adding a link to the layer?).

> +   two versions of the ``nginx`` webserver: a stable "1.28.0" version
> +   that would be selected by default, and a newer "1.29.1" development
> +   version that a developer would need to choose explicitly.
> +
> +   This can be seen based on this snippet from the ``nginx`` 1.29.1
> +   recipe file::
> +

I would like to start making all code-blocks specify a language (I had 
the thought yesterday so to be taken with a grain of salt :) ). Here it 
is BitBake but there's no lexer, so I was thinking about using "none" 
(instead of "text" which I would prefer to keep for actual quote text or 
command line output without the prompt), so that the day we have a 
BitBake lexer (anyone volunteering :) ?) we can look through the docs 
for none and replace easily the ones that are BitBake code blocks.

.. code-block:: none

As for this section (not modified in this patch), I'm not entirely sure 
"BitBake defaults to selecting the most recent version" is actually 
true. I'm wondering whether the layer's priority plays a role or not 
here? Something to investigate.

Cheers,
Quentin