Re: [docs] [PATCH] ref-manual: add documentation for the barebox class

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Enrico,

On Thu Jan 16, 2025 at 12:14 PM CET, Enrico Jörns wrote:
> From: Enrico Joerns <ejo@pengutronix.de>
>
> This adds the initial documentation for the newly added barebox.bbclass
> to the Reference Manual's class list.
> It also adds the two most notable variables to the variable list.
>
> Signed-off-by: Enrico Joerns <ejo@pengutronix.de>
> ---
>  documentation/ref-manual/classes.rst   | 36 ++++++++++++++++++++++++++
>  documentation/ref-manual/variables.rst | 13 ++++++++++
>  2 files changed, 49 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 22c4301a4..c11c0a529 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -128,6 +128,42 @@ It's useful to have some idea of how the tasks defined by the
>  -  :ref:`ref-tasks-install` --- runs ``make install`` and
>     passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
>  
> +.. _ref-classes-barebox:
> +
> +``barebox``
> +===========
> +
> +The :ref:`ref-classes-barebox` class manages building the barebox bootloader.

s/barebox/BareBox/? or Barebox
We try to capitalize project names.

> +
> +If a file named ``defconfig`` is included in the :term:`SRC_URI`, it will be
> +copied to ``.config`` in the build directory and used as the barebox
> +configuration.
> +Instead of providing a ``defconfig`` file, you can set :term:`BAREBOX_CONFIG`
> +to a defconfig provided by the barebox source tree.
> +If neither ``defconfig`` nor :term:`BAREBOX_CONFIG` is specified, the class
> +will raise an error.
> +
> +The :ref:`ref-classes-barebox` class supports config fragments and internally
> +includes the :ref:`ref-classes-cml1` class to provide kconfig support for

Maybe link to https://docs.kernel.org/kbuild/kconfig-language.html here? Some
people might not know what this is referring to. This would be done like so:

  ...provide `Kconfig <https://docs.kernel.org/kbuild/kconfig-language.html>`__
  support...

> +barebox, enabling tasks such as :ref:`ref-tasks-menuconfig` and
> +:ref:`ref-tasks-diffconfig`.
> +
> +The generated barebox binaries are deployed to
> +:term:`DEPLOY_DIR_IMAGE` as well as installed to ``BAREBOX_INSTALL_PATH``
> +(``/boot`` by default) making them part of the recipe’s base package.
> +This setup supports both using the barebox binaries as independent artifacts
> +and installing them into a rootfs.
> +:term:`BAREBOX_BINARY` can be used to select a distinct binary to deploy and
> +install.
> +If ``barebox`` is set as the :term:`EFI_PROVIDER`, the class will leverage
> +``conf/image-uefi.conf`` to define the default installation paths and naming

:oe_git:`conf/image-uefi.conf </openembedded-core/tree/meta/conf/image-uefi.conf>`
instead of
``conf/image-uefi.conf``

> +conventions.
> +
> +The compiled-in barebox environment can be extended by adding environment files
> +to the ``BAREBOX_ENV_DIR``.

:term:`BAREBOX_ENV_DIR` and some documentation for it in variables.rst? Since
it's defined with ??=. But not sure it would be frequently overriden.

Same remark for BAREBOX_FIRMWARE_DIR.

> +The ``BAREBOX_FIRMWARE_DIR`` variable allows you to specify the firmware blob
> +search directory, enabling loading of additional firmware like TF-A or OP-TEE.
> +
>  .. _ref-classes-base:
>  
>  ``base``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 702a6caf8..f29f38588 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -293,6 +293,19 @@ system and gives an overview of their function and contents.
>        :term:`PACKAGE_EXCLUDE` variables for related
>        information.
>  
> +   :term:`BAREBOX_BINARY`
> +      The barebox build system can build multiple barebox binaries at once.
> +      By default, all built binaries will be deployed and installed under their
> +      original name.
> +      If only a specific binary should be deployed/installed, its name can
> +      be specified in :term:`BAREBOX_BINARY`.

Maybe specify the default value, or give an example of what this variable can
contain?

> +
> +   :term:`BAREBOX_CONFIG`
> +      Specifies the name of the barebox defconfig to build.
> +      The name must be a defconfig file known to the barebox build environment.
> +      For more information on how to provide a barebox configuration, see the
> +      :ref:`ref-classes-barebox` class.

At least specify that it's empty by default?

> +
>     :term:`BASE_LIB`
>        The library directory name for the CPU or Application Binary
>        Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib


Thank you for taking time to document this,

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com