[PATCH 2/2] doc/user_manual: Update after images per machine separation

["Maxim Yu. Osipov" <mosipov@ilbers.de>]

Signed-off-by: Maxim Yu. Osipov <mosipov@ilbers.de>
---
 RECIPE-API-CHANGELOG.md | 23 +++++++++++++---
 doc/user_manual.md      | 72 +++++++++++++++++++++++++------------------------
 2 files changed, 57 insertions(+), 38 deletions(-)

diff --git a/RECIPE-API-CHANGELOG.md b/RECIPE-API-CHANGELOG.md
index 197ce99..92f5dce 100644
--- a/RECIPE-API-CHANGELOG.md
+++ b/RECIPE-API-CHANGELOG.md
@@ -96,14 +96,14 @@ layer version higher than existing release corename, use the value 'next'.
 
 ### location of image artifacts
 
-Align with OpenEmbedded and place image artifacts in a per-machine folder placed
+Align with OpenEmbedded and place image artifacts in a per-machine directory placed
 in tmp/deploy (to avoid collisions among other things).
 
 ### more consistent artifact names
 
 multiconfig image artifacts are all placed in tmp/deploy/images. They include
 kernel, initrd and ext4/wic images. A consistent naming scheme is now used:
-`IMAGE-DISTRO-MACHINE.TYPE`. This scheme was already used for ext4/wic images
+`IMAGE-MACHINE-DISTRO-MACHINE.TYPE`. This scheme was already used for ext4/wic images
 so no visible changes there. Kernel and initrd images are however affected; for
 instance:
 
@@ -114,7 +114,7 @@ vmlinuz-4.9.0-8-armmp_debian-stretch-qemuarm
 is now
 
 ```
-isar-image-base-debian-stretch-qemuarm.vmlinuz-4.9.0-8-armmp
+isar-image-base-qemuarm-debian-stretch-qemuarm.vmlinuz-4.9.0-8-armmp
 ```
 
 It should be noted that the `KERNEL_IMAGE` and `INITRD_IMAGE` variables were
@@ -145,3 +145,20 @@ a root password, leak that password via its script in /var/lib/dpkg/info.
 Instead set the CFG_ROOT_PW variable to the encrypted password and use the
 transient 'isar-cfg-rootpw' package (now installed as transient package per
 default).
+
+### Change syntax of bitbake multiconfig target
+
+Image directory gets overwritten when running for two targets
+with the same pair `DISTRO` and `DISTRO_ARCH`, so images are separated
+per `MACHINE` now. This leads to change of bitbake multiconfig target calling syntax
+from
+
+```
+multiconfig:$MACHINE-$DISTRO:isar-image-base
+```
+
+to
+
+```
+multiconfig:$MACHINE-$DISTRO:isar-image-base-$MACHINE
+```
diff --git a/doc/user_manual.md b/doc/user_manual.md
index 6fe4d83..92fc871 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -130,15 +130,15 @@ DISTRO_ARCH ??= "armhf"
 Then, call `bitbake` with image names, e.g.:
 
 ```
-bitbake multiconfig:qemuarm-stretch:isar-image-base \
-        multiconfig:qemuarm-stretch:isar-image-debug
+bitbake multiconfig:qemuarm-stretch:isar-image-base-qemuarm \
+        multiconfig:qemuarm-stretch:isar-image-debug-qemuarm
 ```
 
 The following images are created:
 
 ```
-tmp/deploy/images/isar-image-base-qemuarm-debian-stretch.ext4.img
-tmp/deploy/images/isar-image-debug-qemuarm-debian-stretch.ext4.img
+tmp/deploy/images/isar-image-base-qemuarm-debian-stretch-qemuarm.ext4.img
+tmp/deploy/images/isar-image-debug-qemuarm-debian-stretch-qemuarm.ext4.img
 ```
 
 ### Building Target Images for Multiple Configurations
@@ -168,33 +168,34 @@ The following command will produce `isar-image-base` images for all targets:
 
 ```
 $ bitbake \
-    multiconfig:qemuarm-jessie:isar-image-base \
-    multiconfig:qemuarm-stretch:isar-image-base \
-    multiconfig:qemuarm-buster:isar-image-base \
-    multiconfig:qemuarm64-stretch:isar-image-base \
-    multiconfig:qemui386-jessie:isar-image-base \
-    multiconfig:qemui386-stretch:isar-image-base \
-    multiconfig:qemui386-buster:isar-image-base \
-    multiconfig:qemuamd64-jessie:isar-image-base \
-    multiconfig:qemuamd64-stretch:isar-image-base \
-    multiconfig:qemuamd64-buster:isar-image-base \
-    multiconfig:rpi-jessie:isar-image-base \
-    multiconfig:bananapi-stretch:isar-image-base
+    multiconfig:qemuarm-jessie:isar-image-base-qemuarm \
+    multiconfig:qemuarm-stretch:isar-image-base-qemuarm \
+    multiconfig:qemuarm-buster:isar-image-base-qeruarm \
+    multiconfig:qemuarm64-stretch:isar-image-base-qemuarm64 \
+    multiconfig:qemui386-jessie:isar-image-base-qemui386 \
+    multiconfig:qemui386-stretch:isar-image-base-qemui386 \
+    multiconfig:qemui386-buster:isar-image-base-qemui386 \
+    multiconfig:qemuamd64-jessie:isar-image-base-qemuamd64 \
+    multiconfig:qemuamd64-stretch:isar-image-base-qemuamd64 \
+    multiconfig:qemuamd64-buster:isar-image-base-qemuamd64 \
+    multiconfig:qemuamd64-buster-tgz:isar-image-base-qemuamd64 \
+    multiconfig:nand-ubi-demo-buster:isar-image-ubi-nand-ubi-demo \
+    multiconfig:rpi-jessie:isar-image-base-rpi
 ```
 
 Created images are:
 
 ```
-tmp/deploy/images/isar-image-base-debian-jessie-qemuarm.ext4.img
-tmp/deploy/images/isar-image-base-debian-stretch-qemuarm.ext4.img
-tmp/deploy/images/isar-image-base-debian-stretch-qemuarm.ext4.img
-tmp/deploy/images/isar-image-base-debian-stretch-qemuarm64.ext4.img
-tmp/deploy/images/isar-image-base-debian-jessie-qemui386.ext4.img
-tmp/deploy/images/isar-image-base-debian-stretch-qemui386.ext4.img
-tmp/deploy/images/isar-image-base-debian-jessie-qemuamd64.ext4.img
-tmp/deploy/images/isar-image-base-debian-stretch-qemuamd64.ext4.img
-tmp/deploy/images/isar-image-base.rpi-sdimg
-tmp/deploy/images/isar-image-base-debian-stretch-bananapi.wic.img
+tmp/deploy/images/qemuarm/isar-image-base-qemuarm-debian-jessie-qemuarm.ext4.img
+tmp/deploy/images/qemuarm/isar-image-base-qemuarm-debian-stretch-qemuarm.ext4.img
+tmp/deploy/images/qemuarm/isar-image-base-qemuarm-debian-stretch-qemuarm.ext4.img
+tmp/deploy/images/qemuarm64/isar-image-base-qemuarm64-debian-stretch-qemuarm64.ext4.img
+tmp/deploy/images/qemui386/isar-image-base-qemui386-debian-jessie-qemui386.ext4.img
+tmp/deploy/images/qemui386/isar-image-base-qemui386-debian-stretch-qemui386.ext4.img
+tmp/deploy/images/qemuamd64/isar-image-base-qemuamd64-debian-jessie-qemuamd64.ext4.img
+tmp/deploy/images/qemuamd64/isar-image-base-qemuamd64-debian-stretch-qemuamd64.ext4.img
+tmp/deploy/images/nand-ubi-demo/isar-image-ubi-nand-ubi-demo-debian-buster-nand-ubi-demo.ubi.img
+tmp/deploy/images/rpi/isar-image-base-rpi.rpi-sdimg
 ```
 
 ### Generate full disk image
@@ -202,9 +203,9 @@ tmp/deploy/images/isar-image-base-debian-stretch-bananapi.wic.img
 A bootable disk image is generated if you set IMAGE_TYPE to 'wic-img'. Behind the scenes a tool called `wic` is used to assemble the images. It is controlled by a `.wks` file which you can choose with changing WKS_FILE. Some examples in the tree use that feature already.
 ```
  # Generate an image for the `i386` target architecture
- $ bitbake multiconfig:qemui386-stretch:isar-image-base
+ $ bitbake multiconfig:qemui386-stretch:isar-image-base-qemui386
  # Similarly, for the `amd64` target architecture, in this case EFI
- $ bitbake multiconfig:qemuamd64-stretch:isar-image-base
+ $ bitbake multiconfig:qemuamd64-stretch:isar-image-base-qemuamd64
 ```
 
 Variables may be used in `.wks.in` files; Isar will expand them and generate a regular `.wks` file before generating the disk image using `wic`.
@@ -217,9 +218,9 @@ enough to allow images to be testable under `qemu`.
 
 ```
 # AMD64 image, EFI
-qemu-system-x86_64 -m 256M -nographic -bios edk2/Build/OvmfX64/RELEASE_*/FV/OVMF.fd -hda tmp/deploy/images/isar-image-base-debian-stretch-qemuamd64.wic.img
+qemu-system-x86_64 -m 256M -nographic -bios edk2/Build/OvmfX64/RELEASE_*/FV/OVMF.fd -hda tmp/deploy/images/qemuamd64/isar-image-base-qemuamd64-debian-stretch-qemuamd64.wic.img
 # i386 image
-qemu-system-i386 -m 256M -nographic -hda tmp/deploy/images/isar-image-base-debian-stretch-qemui386.wic.img
+qemu-system-i386 -m 256M -nographic -hda tmp/deploy/images/qemui386/isar-image-base-qemui386-debian-stretch-qemui386.wic.img
 ```
 
 ---
@@ -308,7 +309,7 @@ following variables define the default configuration to build for:
  - `DISTRO_ARCH` - The Debian architecture to build for (e.g., `armhf`).
 
 If BitBake is called with multiconfig targets (e.g.,
-`multiconfig:qemuarm-jessie:isar-image-base`), the following variable defines
+`multiconfig:qemuarm-stretch:isar-image-base-qemuarm`), the following variable defines
 all supported configurations:
 
  - `BBMULTICONFIG` - The list of the complete configuration definition files.
@@ -536,6 +537,7 @@ IMAGE_PREINSTALL = " \
 
 inherit isar-image
 
+PN .= "-${MACHINE}"
 ```
 
 ### Additional Notes
@@ -668,7 +670,7 @@ target binary artifacts. Developer chroots to sdk rootfs and develops applicatio
 ### Solution
 
 User manually triggers creation of SDK root filesystem for his target platform by launching the task `do_populate_sdk` for target image, f.e.
-`bitbake -c do_populate_sdk multiconfig:${MACHINE}-${DISTRO}:isar-image-base`.
+`bitbake -c do_populate_sdk multiconfig:${MACHINE}-${DISTRO}:isar-image-base-${MACHINE}`.
 
 The resulting SDK rootfs is archived into `tmp/deploy/images/sdk-${DISTRO}-${DISTRO_ARCH}.tar.xz`.
 It is additionally available for direct use under `tmp/deploy/images/sdk-${DISTRO}-${DISTRO_ARCH}/`.
@@ -680,7 +682,7 @@ One may chroot into the SDK and install required target packages with the help o
  - Trigger creation of SDK root filesystem
 
 ```
-bitbake -c do_populate_sdk multiconfig:qemuarm-stretch:isar-image-base
+bitbake -c do_populate_sdk multiconfig:qemuarm-stretch:isar-image-base-qemuarm
 ```
 
  - Mount the following directories in chroot by passing resulting rootfs as an argument to the script `mount_chroot.sh`:
@@ -760,7 +762,7 @@ BASE_REPO_KEY = "file://<absolute_path_to_your_pub_key_file>"'
  - Trigger creation of local apt caching Debian packages during image generation.
 
 ```
-bitbake -c cache_base_repo multiconfig:qemuarm-stretch:isar-image-base
+bitbake -c cache_base_repo multiconfig:qemuarm-stretch:isar-image-base-qemuarm
 ```
 
  - Set `ISAR_USE_CACHED_BASE_REPO` in `conf/local.conf`:
@@ -779,7 +781,7 @@ sudo rm -rf tmp
  - Trigger again generation of image (now using local caching repo):
 
 ```
-bitbake multiconfig:qemuarm-stretch:isar-image-base
+bitbake multiconfig:qemuarm-stretch:isar-image-base-qemuarm
 ```
 
 ### Limitation
-- 
2.11.0