[v2] documentation: Add multiconfig initramfs configuration:

dev-manual/common-tasks.rst: Add section to create an initramfs
image from a separate multiconfig.

ref-manual/variables.rst: Add new variable definitions for
INITRAMFS_DEPLOY_DIR_IMAGE and INITRAMFS_MULTICONFIG

Signed-off-by: Alejandro Enedino Hernandez Samaniego <alhe@linux.microsoft.com>
---
 documentation/dev-manual/common-tasks.rst | 42 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 17 +++++++++
 2 files changed, 59 insertions(+)

Hi Alejandro,

On 2/16/22 21:17, Alejandro Hernandez Samaniego wrote:
> dev-manual/common-tasks.rst: Add section to create an initramfs
> image from a separate multiconfig.
>
> ref-manual/variables.rst: Add new variable definitions for
> INITRAMFS_DEPLOY_DIR_IMAGE and INITRAMFS_MULTICONFIG
>
> Signed-off-by: Alejandro Enedino Hernandez Samaniego <alhe@linux.microsoft.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 42 +++++++++++++++++++++++
>  documentation/ref-manual/variables.rst    | 17 +++++++++
>  2 files changed, 59 insertions(+)
>
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index d35b590ee..dec44d378 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -3919,6 +3919,48 @@ Follow these steps to create an initramfs image:
>     :term:`INITRAMFS_IMAGE_BUNDLE`
>     variable described earlier.
>  
> +Bundling an Initramfs Image From a Separate Multiconfig
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +There may be a case where we want to build an initramfs image which does not
> +inherit the same distro policy as our main image, for example, we may want
> +our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our initramfs
> +image to keep a smaller footprint. However, by performing the steps mentioned
> +above the initramfs image will inherit ``TCLIBC="glibc"`` without allowing us
> +to override it.
> +
> +To achieve this, you need to perform some additional steps:
> +
> +1. *Create a multiconfig for your initramfs image:* You can perform the steps
> +   on ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" to create a separate multiconfig.
> +   For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and
> +   contains the variables::
> +
> +      TMPDIR="${TOPDIR}/tmp-initramfscfg"
> +      TCLIBC="musl"
> +
> +2. *Set additional initramfs variables on your main configuration:*
> +   Additionally, on your main configuration (``local.conf``) you need to set the
> +   variables::
> +
> +     INITRAMFS_MULTICONFIG = "initramfscfg"
> +     INITRAMFS_DEPLOY_DIR_IMAGE = "${TOPDIR}/tmp-initramfscfg/deploy/images/${MACHINE}"
> +
> +   The variables :term:`INITRAMFS_MULTICONFIG` and :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
> +   are used to create a multiconfig dependency from the kernel to the :term:`INITRAMFS_IMAGE`
> +   to be built coming from the ``initramfscfg`` multiconfig, and to let the
> +   buildsystem know where the :term:`INITRAMFS_IMAGE` will be located.
> +
> +   Building a system with such configuration will build the kernel using the
> +   main configuration but the ``do_bundle_initramfs`` task will grab the
> +   selected :term:`INITRAMFS_IMAGE` from :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
> +   instead, resulting in a musl based initramfs image bundled in the kernel
> +   but a glibc based main image.
> +
> +   The same is applicable to avoid inheriting :term:`DISTRO_FEATURES` on :term:`INITRAMFS_IMAGE`
> +   or to build a different :term:`DISTRO` for it such as ``poky-tiny``.
> +
> +
>  Building a Tiny System
>  ----------------------
>  
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d4f40b692..caa971393 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3554,6 +3554,13 @@ system and gives an overview of their function and contents.
>           even if the toolchain's binaries are strippable, there are other files
>           needed for the build that are not strippable.
>  
> +   :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
> +      Indicates the deploy directory used by ``do_bundle_initramfs`` where the
> +      :term:`INITRAMFS_IMAGE` will be fetched from.
> +      This variable is set by default to ``${DEPLOY_DIR_IMAGE}`` in the
> +      :ref:`kernel <ref-classes-kernel>` class and it's only meant to be changed
> +      when building an initramfs image from a separate multiconfig via :term:`INITRAMFS_MULTICONFIG`.
> +
>     :term:`INITRAMFS_FSTYPES`
>        Defines the format for the output image of an initial RAM filesystem
>        (initramfs), which is used during boot. Supported formats are the
> @@ -3673,6 +3680,16 @@ system and gives an overview of their function and contents.
>        See the :term:`MACHINE` variable for additional
>        information.
>  
> +   :term:`INITRAMFS_MULTICONFIG`
> +      Defines the multiconfig to create a multiconfig dependency to be used by the :ref:`kernel <ref-classes-kernel>` class.
> +
> +      This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from
> +      a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`.
> +
> +      For more information on how to bundle an initramfs image from a separate
> +      multiconfig see the ":ref:`dev-manual/common-tasks:Bundling an Initramfs Image From a Separate Multiconfig`"
> +      section in the Yocto Project Development Tasks Manual.
> +
>     :term:`INITRAMFS_NAME`
>        The base name of the initial RAM filesystem image. This variable is
>        set in the ``meta/classes/kernel-artifact-names.bbclass`` file as

Thanks for the update!
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

... and merged into the "master-next" branch of yocto-docs.


Cheers
Michael.