| Message ID | 20220130013135.231200-1-alhe@linux.microsoft.com |
|---|---|
| State | New |
| Headers | show |
| Series | documentation: Add multiconfig initramfs configuration: | expand |
Hi Alejandro Many thanks for this very nice contribution to our documentation! On 1/30/22 02:31, 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 ed6b1446f..f19b55395 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 > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Actually, a rule in English seems to capitalize important words in a title. According to https://titlecaseconverter.com/, this should be: "BundlinganInitramfsImageFromaSeparateMulticonfig" > + > +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 us being able > +to override it. "without allowing us to override it"? Just proposing something that sounds more natural to me. > + > +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 lets s/lets/let's/ I'd also suggest to break the sentence in two: "... multiconfig. For the sake..." > + 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}" Would it be possible to replace "${TOPDIR}/tmp-initramfscfg" by "${TMPDIR}"? > + > + 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 task ``do_bundle_initramfs`` will grab the "but the ``do_bundle_initramfs`` task"? > + 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 build a different :term:`DISTRO` for it such as ``poky-tiny``. "or to build" > + > + > Building a Tiny System > ---------------------- > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index b0621168a..9c1da3b5e 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -3556,6 +3556,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 its only meant to be changed s/its/is/ > + 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 > @@ -3675,6 +3682,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 by the :ref:`kernel <ref-classes-kernel>` class. s/to by the/to be used by the/ ? > + > + 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 ":ref:`dev-manual/common-tasks:bundling an initramfs image from a separate multiconfig`" > + section in the Yocto Project Development Tasks Manual. Add "the" before ":ref:" and capitalize the section title there too. Thanks again, and thanks in advance for these updates! Cheers Michael.
Hey Michael, Sorry I never saw your reply, I'll send a v2 soon. Thanks Alejandro On 2/2/22 03:12, Michael Opdenacker wrote: > Hi Alejandro > > Many thanks for this very nice contribution to our documentation! > > On 1/30/22 02:31, 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 ed6b1446f..f19b55395 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 >> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Actually, a rule in English seems to capitalize important words in a > title. According to https://titlecaseconverter.com/, this should be: > "BundlinganInitramfsImageFromaSeparateMulticonfig" > >> + >> +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 us being able >> +to override it. > > "without allowing us to override it"? > Just proposing something that sounds more natural to me. > >> + >> +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 lets > s/lets/let's/ > > I'd also suggest to break the sentence in two: "... multiconfig. For the > sake..." > >> + 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}" > > Would it be possible to replace "${TOPDIR}/tmp-initramfscfg" by "${TMPDIR}"? In this case no, since that would point to the TMPDIR for the other multiconfig and we want to specifically point it to the one for mc:initramfs > >> + >> + 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 task ``do_bundle_initramfs`` will grab the > > "but the ``do_bundle_initramfs`` task"? >> + 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 build a different :term:`DISTRO` for it such as ``poky-tiny``. > > "or to build" > >> + >> + >> Building a Tiny System >> ---------------------- >> >> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst >> index b0621168a..9c1da3b5e 100644 >> --- a/documentation/ref-manual/variables.rst >> +++ b/documentation/ref-manual/variables.rst >> @@ -3556,6 +3556,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 its only meant to be changed > > s/its/is/ > >> + 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 >> @@ -3675,6 +3682,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 by the :ref:`kernel <ref-classes-kernel>` class. > s/to by the/to be used by the/ ? Can't believe I missed this, thanks! >> + >> + 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 ":ref:`dev-manual/common-tasks:bundling an initramfs image from a separate multiconfig`" >> + section in the Yocto Project Development Tasks Manual. > > Add "the" before ":ref:" and capitalize the section title there too. > > Thanks again, and thanks in advance for these updates! > Cheers > Michael. >
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index ed6b1446f..f19b55395 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 us being able +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 lets + 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 task ``do_bundle_initramfs`` 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 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 b0621168a..9c1da3b5e 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -3556,6 +3556,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 its 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 @@ -3675,6 +3682,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 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 ":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
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(+)