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