[PATCH v2 0/3] Update Isar documentation

[PATCH v2 0/3] Update Isar documentation

[Anton Mikanovich]

Update Isar documentation files.

Anton Mikanovich (3):
  doc: Add imager dependencies section
  doc: Update tasks description
  doc: Update available image types

 doc/technical_overview.md | 56 +++++++++++++++++++++++----------------
 doc/user_manual.md        | 30 +++++++++++++++++++--
 2 files changed, 61 insertions(+), 25 deletions(-)

-- 
2.25.1

[PATCH v2 1/3] doc: Add imager dependencies section

[Anton Mikanovich]

Include into user_manual.md explanation of imager dependencies should
be added if using wic image type with bootloader-related plugins.

Inspired by issue #69

Signed-off-by: Anton Mikanovich <amikan@ilbers.de>
---
 doc/user_manual.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 01fe701..1b00a47 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -586,6 +586,22 @@ Isar contains additional image type classes that can be used as reference:
  - `ubi-img`
  - `wic-img`
 
+### Imager dependencies and bootloaders
+
+External tools used for final image prepare inside image type classes should be declared as `IMAGER_INSTALL`.
+It will make Isar to install following packages into buildchroot before proceeding.
+
+If using `wic-img` image type correct bootloader dependecy should be added to target machine config based on selected wic plugin.
+
+When using legacy BIOS bootloader (amd64/i386 only) dependency on syslinux should be used:
+```
+IMAGER_INSTALL += "${SYSLINUX_BOOTLOADER_INSTALL}"
+```
+When using EFI bootloader dependency on GRUB should be added:
+```
+IMAGER_INSTALL += "${GRUB_BOOTLOADER_INSTALL}"
+```
+
 ---
 
 ## Customize and configure image
-- 
2.25.1

[PATCH v2 2/3] doc: Update tasks description

[Anton Mikanovich]

Update task list and description for `dpkg.bbclass` and
`dpkg-raw.bbclass` to correspond with the latest state.

Signed-off-by: Anton Mikanovich <amikan@ilbers.de>
---
 doc/technical_overview.md | 56 +++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 23 deletions(-)

diff --git a/doc/technical_overview.md b/doc/technical_overview.md
index bbd22b6..225475e 100644
--- a/doc/technical_overview.md
+++ b/doc/technical_overview.md
@@ -214,41 +214,51 @@ Both consist of the following steps:
 
 2. Task `do_unpack`: unpack those files to `${WORKDIR}`
 
-3. Task `do_install` _only_ for `dpkg-raw`: copy all you want in your
+3. Task `do_transform_template`: process `${TEMPLATE_FILES}` to substitute
+   variables listed in `${TEMPLATE_VARS}` in template files
+
+4. Task `do_apt_fetch`: fetch source files from apt repos
+
+5. Task `do_apt_unpack`: unpack those files to `${WORKDIR}`
+
+6. Task `do_patch`: process .patch files in the `${SRC_URI}`
+
+7. Task `do_install` _only_ for `dpkg-raw`: copy all you want in your
    debian package to `${D}`, install hooks in `${D}/DEBIAN`
 
-4. Task `do_prepare': perform any preparation steps to the unpacked/patched
-   sources before the build. This task calls the dpkg_prepare shell function
-   with the buildchroot mounts in place (`dpkg_do_mounts')
+8. Task `do_adjust_git`: adjust alternates links inside git repos in the
+   package workdir to make them valid inside chroot
+
+9. Task `do_prepare_build`: perform any preparation steps to the unpacked and
+   patched sources before the build.
 
-   4.1. the `dpkg_prepare` function of `dpkg.bbclass` runs `/isar/deps.sh` in
-        the buildchroot. That performs the following:
+   For `dpkg-raw` it perform `deb_debianize` call to translate the recipe
+   meta-data into a debian/* files suitable for building with dpkg-buildpackage
 
-        1. Go to `/home/build/${PN}`
+10. Task `do_install_builddeps`: install build dependencies of the package.
+    This task calls the `builddeps_install` shell function with the buildchroot
+    mounts in place (surrounded by `dpkg_do_mounts` and `dpkg_undo_mounts`).
 
-        2. Get list of dependencies from debian/control and install them
+    The `builddeps_install` function of `dpkg.bbclass` runs `/isar/deps.sh` in
+    the buildchroot. That performs the following:
 
-   4.2. the `dpkg_prepare` function of `dpkg-raw.bbclass` translate the
-        recipe meta-data into a debian/control file suitable for packaging
-        with dpkg-deb
+    10.1. Go to `/home/build/${PN}`
 
-5. Task `do_build`: mount folder (`dpkg_do_mounts') with unpacked files to buildchroot,
-   execute the actual build function `dpkg_runbuild`, and finally umount again
-   (`dpkg_undo_mounts')
+    10.2. Get list of dependencies from debian/control and install them
 
-   5.1. the `dpkg_runbuild` function of `dpkg.bbclass` runs `build.sh` in the
-        buildchroot. That performs the following:
+11. Task `do_dpkg_build`: mount folder (`dpkg_do_mounts`) with unpacked files
+    to buildchroot, execute the actual build function `dpkg_runbuild`, and
+    finally umount again (`dpkg_undo_mounts`)
 
-        1. Go to `/home/build/${PN}`
+    The `dpkg_runbuild` function of `dpkg.bbclass` runs `/isar/build.sh` in
+    the buildchroot. That performs the following:
 
-        2. Run dpkg-buildpackage
+    11.1. Go to `/home/build/${PN}`
 
-   5.2. the `dpkg_runbuild` function of `dpkg-raw.bbclass` basically runs
-        `dpkg-deb` to construct a Debian package from a folder of files,
-	without compiling anything
+    11.2. Run dpkg-buildpackage
 
-6. Task `do_deploy_deb`: install successfully built packages
-   `${WORKDIR}/*.deb` to deploy directory `${DEPLOY_DIR_DEB}`
+12. Task `do_deploy_deb`: install successfully built packages
+    `${WORKDIR}/*.deb` to deploy directory `${DEPLOY_DIR_DEB}`
 
 ## 3.6 Populate Target Filesystem
 
-- 
2.25.1

[PATCH v2 3/3] doc: Update available image types

[Anton Mikanovich]

Update the list of image types can be used for targets.

Signed-off-by: Anton Mikanovich <amikan@ilbers.de>
---
 doc/user_manual.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 1b00a47..b4dbe85 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -450,10 +450,16 @@ Please refer to `Add a Custom Application` section for more information about wr
 
 Isar can generate various images types for specific machine. The type of the image to be generated may be specified through the `IMAGE_TYPE` variable. Currently, the following image types are provided:
 
- - `ext4` - Raw ext4 filesystem image (default option for `qemuarm` machine).
+ - `ext4-img` - Raw ext4 filesystem image (default option for `qemuarm` machine).
  - `rpi-sdimg` - A complete, partitioned Raspberry Pi SD card image (default option for the `rpi` machine).
  - `wic-img` - A full disk image with user-specified partitions created and populated using the wic tool.
- - `ubi-img` - A image for use on mtd nand partitions employing UBI
+ - `targz-img` - Compressed Tar archive with filesystem.
+ - `fit-img` - Flattened Image Tree filesystem image with user-specified binaries included.
+ - `ubifs-img` - UBIFS filesystem image to be used with ubiupdatevol.
+ - `ubi-img` - An image for use on mtd nand partitions employing UBI.
+ - `ubi-ubifs-img` - An image encapsulates FIT and UBI image types.
+ - `container-img` - Container image specified by `CONTAINER_FORMAT` value.
+ - `cpiogz-img` - An initramfs like filesystem.
  - `vm-img` - A image for use on VirtualBox or VMware
 
 ---
@@ -582,9 +588,13 @@ Isar contains additional image type classes that can be used as reference:
  - `ext4-img`
  - `rpi-sdimg`
  - `targz-img`
+ - `fit-img`
  - `ubifs-img`
  - `ubi-img`
  - `wic-img`
+ - `container-img`
+ - `cpiogz-img`
+ - `vm-img`
 
 ### Imager dependencies and bootloaders
 
-- 
2.25.1

Re: [PATCH v2 1/3] doc: Add imager dependencies section

[Henning Schild]

Am Thu, 28 Oct 2021 20:17:25 +0300
schrieb Anton Mikanovich <amikan@ilbers.de>:

> Include into user_manual.md explanation of imager dependencies should
> be added if using wic image type with bootloader-related plugins.
> 
> Inspired by issue #69
> 
> Signed-off-by: Anton Mikanovich <amikan@ilbers.de>
> ---
>  doc/user_manual.md | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/doc/user_manual.md b/doc/user_manual.md
> index 01fe701..1b00a47 100644
> --- a/doc/user_manual.md
> +++ b/doc/user_manual.md
> @@ -586,6 +586,22 @@ Isar contains additional image type classes that
> can be used as reference:
>   - `ubi-img`
>   - `wic-img`
>  
> +### Imager dependencies and bootloaders
> +
> +External tools used for final image prepare inside image type
> classes should be declared as `IMAGER_INSTALL`. +It will make Isar to
> install following packages into buildchroot before proceeding. +
> +If using `wic-img` image type correct bootloader dependecy should be
> added to target machine config based on selected wic plugin. +

I would make that more generic and explain what IMAGER_INSTALL is in
general. Maybe even refer to "native" from OE.

The tools are not "external", they are build tools (coming from
upstream or maybe a layer) that are not part of the image but needed to
construct it. In fact we use that variable in many of our imager
classes, not just wic.

> +When using legacy BIOS bootloader (amd64/i386 only) dependency on
> syslinux should be used: +```
> +IMAGER_INSTALL += "${SYSLINUX_BOOTLOADER_INSTALL}"
> +```
> +When using EFI bootloader dependency on GRUB should be added:
> +```
> +IMAGER_INSTALL += "${GRUB_BOOTLOADER_INSTALL}"

wic makes a good example to explain the concept. Note that EFI does not
mean grub and having to set IMAGER_INSTALL. It can also mean
systemd-boot and no IMAGER_INSTALL.

Henning

> +```
> +
>  ---
>  
>  ## Customize and configure image