[PATCH v2] sphinx: ref-variables: Added entry for IMAGE_EFI_BOOT_FILES

[PATCH v2] sphinx: ref-variables: Added entry for IMAGE_EFI_BOOT_FILES

[Jamaluddin, Khairul Rohaizzat]

From: Khairul Rohaizzat Jamaluddin <khairul.rohaizzat.jamaluddin@intel.com>

IMAGE_EFI_BOOT_FILES created to help differentiate files needed between
bootimg-efi and bootimg-partition when creating the installer/.wic file.

Signed-off-by: Khairul Rohaizzat Jamaluddin <khairul.rohaizzat.jamaluddin@intel.com>
---
 documentation/ref-manual/ref-variables.rst | 37 +++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
index 625a37c..8483e08 100644
--- a/documentation/ref-manual/ref-variables.rst
+++ b/documentation/ref-manual/ref-variables.rst
@@ -2902,10 +2902,45 @@ system and gives an overview of their function and contents.
       The base name of image output files. This variable defaults to the
       recipe name (``${``\ :term:`PN`\ ``}``).
 
+   IMAGE_EFI_BOOT_FILES
+      A space-separated list of files installed into the boot partition
+      when preparing an image using the Wic tool with the
+      ``bootimg-efi`` source plugin. By default,
+      the files are
+      installed under the same name as the source files. To change the
+      installed name, separate it from the original name with a semi-colon
+      (;). Source files need to be located in
+      :term:`DEPLOY_DIR_IMAGE`. Here are two
+      examples:
+      ::
+
+         IMAGE_EFI_BOOT_FILES = ${IMGDEPLOYDIR}/${IMAGE_BASENAME}-${MACHINE}.ext4;rootfs.img
+
+      Alternatively, source files can be picked up using a glob pattern. In
+      this case, the destination file must have the same name as the base
+      name of the source file path. To install files into a directory
+      within the target location, pass its name after a semi-colon (;).
+      Here are two examples:
+      ::
+
+         IMAGE_EFI_BOOT_FILES = "boot/loader/*"
+         IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
+
+      The first example
+      installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
+      into the root of the target partition. The second example installs
+      the same files into a ``boot`` directory within the target partition.
+
+      You can find information on how to use the Wic tool in the
+      ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`"
+      section of the Yocto Project Development Tasks Manual. Reference
+      material for Wic is located in the
+      ":doc:`../ref-manual/ref-kickstart`" chapter.
+
    IMAGE_BOOT_FILES
       A space-separated list of files installed into the boot partition
       when preparing an image using the Wic tool with the
-      ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default,
+      ``bootimg-partition`` source plugin. By default,
       the files are
       installed under the same name as the source files. To change the
       installed name, separate it from the original name with a semi-colon
-- 
2.7.4

Re: [docs] [PATCH v2] sphinx: ref-variables: Added entry for IMAGE_EFI_BOOT_FILES

[Quentin Schulz]

Hi,

On Fri, Sep 18, 2020 at 05:06:47PM +0800, Jamaluddin, Khairul Rohaizzat wrote:
> From: Khairul Rohaizzat Jamaluddin <khairul.rohaizzat.jamaluddin@intel.com>
> 
> IMAGE_EFI_BOOT_FILES created to help differentiate files needed between
> bootimg-efi and bootimg-partition when creating the installer/.wic file.
> 
> Signed-off-by: Khairul Rohaizzat Jamaluddin <khairul.rohaizzat.jamaluddin@intel.com>
> ---
>  documentation/ref-manual/ref-variables.rst | 37 +++++++++++++++++++++++++++++-
>  1 file changed, 36 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
> index 625a37c..8483e08 100644
> --- a/documentation/ref-manual/ref-variables.rst
> +++ b/documentation/ref-manual/ref-variables.rst
> @@ -2902,10 +2902,45 @@ system and gives an overview of their function and contents.
>        The base name of image output files. This variable defaults to the
>        recipe name (``${``\ :term:`PN`\ ``}``).
>  
> +   IMAGE_EFI_BOOT_FILES
> +      A space-separated list of files installed into the boot partition
> +      when preparing an image using the Wic tool with the
> +      ``bootimg-efi`` source plugin. By default,
> +      the files are
> +      installed under the same name as the source files. To change the
> +      installed name, separate it from the original name with a semi-colon
> +      (;). Source files need to be located in
> +      :term:`DEPLOY_DIR_IMAGE`. Here are two

Yet you have an example using IMGDEPLOYDIR?

(and there is only one example :) )

> +      examples:
> +      ::
> +
> +         IMAGE_EFI_BOOT_FILES = ${IMGDEPLOYDIR}/${IMAGE_BASENAME}-${MACHINE}.ext4;rootfs.img
> +

Probably missing surrounding double quotes?

Also, it is quite confusing to say it's a space-separated list of files
but the only example is with a semi-colon in it. I'd just add one more
example before explaining how to change the installed name with multiple
files in it (space-separated of course :) ).

Cheers,
Quentin

Re: [docs] [PATCH v2] sphinx: ref-variables: Added entry for IMAGE_EFI_BOOT_FILES

[Jamaluddin, Khairul Rohaizzat]

Hi Quentin,

Thanks for notifying and the advice!
I totally overlooked these mistakes when I submitted it..
I'm sending out the update now.


Thank you & Kind regards,
Khairul

-----Original Message-----
From: Quentin Schulz <quentin.schulz@streamunlimited.com> 
Sent: Friday, September 18, 2020 5:17 PM
To: Jamaluddin, Khairul Rohaizzat <khairul.rohaizzat.jamaluddin@intel.com>
Cc: docs@lists.yoctoproject.org
Subject: Re: [docs] [PATCH v2] sphinx: ref-variables: Added entry for IMAGE_EFI_BOOT_FILES

Hi,

On Fri, Sep 18, 2020 at 05:06:47PM +0800, Jamaluddin, Khairul Rohaizzat wrote:
> From: Khairul Rohaizzat Jamaluddin 
> <khairul.rohaizzat.jamaluddin@intel.com>
> 
> IMAGE_EFI_BOOT_FILES created to help differentiate files needed 
> between bootimg-efi and bootimg-partition when creating the installer/.wic file.
> 
> Signed-off-by: Khairul Rohaizzat Jamaluddin 
> <khairul.rohaizzat.jamaluddin@intel.com>
> ---
>  documentation/ref-manual/ref-variables.rst | 37 
> +++++++++++++++++++++++++++++-
>  1 file changed, 36 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/ref-manual/ref-variables.rst 
> b/documentation/ref-manual/ref-variables.rst
> index 625a37c..8483e08 100644
> --- a/documentation/ref-manual/ref-variables.rst
> +++ b/documentation/ref-manual/ref-variables.rst
> @@ -2902,10 +2902,45 @@ system and gives an overview of their function and contents.
>        The base name of image output files. This variable defaults to the
>        recipe name (``${``\ :term:`PN`\ ``}``).
>  
> +   IMAGE_EFI_BOOT_FILES
> +      A space-separated list of files installed into the boot partition
> +      when preparing an image using the Wic tool with the
> +      ``bootimg-efi`` source plugin. By default,
> +      the files are
> +      installed under the same name as the source files. To change the
> +      installed name, separate it from the original name with a semi-colon
> +      (;). Source files need to be located in
> +      :term:`DEPLOY_DIR_IMAGE`. Here are two

Yet you have an example using IMGDEPLOYDIR?

(and there is only one example :) )

> +      examples:
> +      ::
> +
> +         IMAGE_EFI_BOOT_FILES = 
> + ${IMGDEPLOYDIR}/${IMAGE_BASENAME}-${MACHINE}.ext4;rootfs.img
> +

Probably missing surrounding double quotes?

Also, it is quite confusing to say it's a space-separated list of files but the only example is with a semi-colon in it. I'd just add one more example before explaining how to change the installed name with multiple files in it (space-separated of course :) ).

Cheers,
Quentin