[RFC PATCH 2/2] docs: document usage of sdk container images

[Silvano Cirujano Cuesta <silvano.cirujano-cuesta@siemens.com>]

Signed-off-by: Silvano Cirujano Cuesta <silvano.cirujano-cuesta@siemens.com>
---
 doc/user_manual.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index a4f3d1d..ff779b1 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -834,6 +834,76 @@ ii  crossbuild-essential-armhf           12.3                   all          Inf
 ~#
 ```
 
+## Create a "containerized" ISAR SDK root filesystem
+
+### Motivation
+
+Distributing and using the SDK root filesystem created following the instructions in "[Create an ISAR SDK root filesystem](#create-an-isar-sdk-root-filesystem)" becomes easier using container images (at least for those using containers anyway)
+A "containerized" SDK adds to those advantages of a normal SDK root filesystem the comfort of container images.
+
+### Approach
+
+Create container image with SDK root filesystem with installed cross-toolchain for target architecture and ability to install already prebuilt target binary artifacts.
+Developer:
+ - runs a container based on the resulting container image mounting the source code to be built,
+ - develops applications for target platform on the container and
+ - leaves the container getting the results on the mounted directory.
+
+### Solution
+
+User specifies the variable `SDK_FORMAT` providing a space-separated list of SDK formats to generate.
+Supported formats are:
+ - `tar`: is the default, is the non-containerized format that results from following the instructions in "[Create an ISAR SDK root filesystem](#create-an-isar-sdk-root-filesystem)"
+ - `docker-archive`: an archive containing a Docker image that can be imported with [`docker import`](https://docs.docker.com/engine/reference/commandline/import/)
+ - `docker-daemon`: (not supported from inside of a container) resulting container image is made available on the local Docker Daemon
+ - `containers-storage`: (not supported from inside of a container) resulting container image is made available to tools using containers/storage back-end (e.g. Podman, CRIO, buildah,...)
+ - `oci-archive`: an archive containing an OCI image, mostly for archiving as seed for any of the above formats
+
+User manually triggers creation of SDK formats for his target platform by launching the task `do_populate_sdk` for target image, f.e.
+`bitbake -c do_populate_sdk mc:${MACHINE}-${DISTRO}:isar-image-base`.
+Packages that should be additionally installed into the SDK can be appended to `SDK_PREINSTALL` (external repositories) and `SDK_INSTALL` (self-built).
+
+The resulting SDK formats are archived into `tmp/deploy/images/${MACHINE}/sdk-${DISTRO}-${DISTRO_ARCH}-${sdk_format}.tar.xz` (being `sdk_format` each one of the formats specified in `SDK_FORMATS`).
+The SDK container directory `/isar-apt` contains a copy of isar-apt repo with locally prebuilt target debian packages (for <HOST_DISTRO>).
+One may get into an SDK container and install required target packages with the help of `apt-get install <package_name>:<DISTRO_ARCH>` command.
+The directory with the source code to develop on should be mounted on the container (with `--volume <host-directory>:<container-directory>`) to be able to edit files in the host with an IDE and build in the container.
+
+### Example
+
+ - Make the SDK formats to generate available to the task
+
+For one-shot builds (use `local.conf` otherwise):
+
+```
+export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE SDK_FORMATS"
+export SDK_FORMATS="docker-archive"
+```
+
+ - Trigger creation of SDK root filesystem
+
+```
+bitbake -c do_populate_sdk mc:qemuarm-buster:isar-image-base
+```
+
+ - Load the SDK container image into the Docker Daemon
+
+```
+xzcat build/tmp/deploy/images/qemuarm/sdk-debian-buster-armhf-docker-archive.tar.xz | docker load
+```
+
+ - Run a container using the SDK container image (following commands starting with `#~:` are to be run in the container)
+
+```
+docker run --rm -ti --volume "$(pwd):/build" isar-sdk-buster-armhf:latest
+```
+
+ - Check that cross toolchains are installed
+
+```
+:~# dpkg -l | grep crossbuild-essential-armhf
+ii  crossbuild-essential-armhf           12.3                   all          Informational list of cross-build-essential packages
+```
+
 ## Creation of local apt repo caching upstream Debian packages
 
 ### Motivation
-- 
2.29.2