[RFC PATCH 6/6] doc: Add description of ISAR SDK root filesystem creation

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

Signed-off-by: Maxim Yu. Osipov <mosipov@ilbers.de>
---
 doc/user_manual.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 9921f3a..746708d 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -17,6 +17,7 @@ Copyright (C) 2016-2017, ilbers GmbH
  - [Add a New Image](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#add-a-new-image)
  - [Add a New Image Type](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#add-a-new-image-type)
  - [Add a Custom Application](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#add-a-custom-application)
+ - [Create an ISAR SDK root filesystem](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#create-an-isar-sdk-root-filesystem)
 
 ## Introduction
 
@@ -320,6 +321,8 @@ Some other variables include:
  - `BB_NUMBER_THREADS` - The number of `bitbake` jobs that can be run in parallel. Please set this option according your host CPU cores number.
  - `LOCALE_GEN` - A `\n` seperated list of `/etc/locale.gen` entries desired on the target.
  - `LOCALE_DEFAULT` - The default locale used for the `LANG` and `LANGUAGE` variable in `/etc/locale`.
+ - `DISTRO_HOST` - The distro to use for SDK root filesystem (so far limited only to `debian-stretch`). This variable is optional.
+ - `DISTRO_HOST_ARCH` - The Debian architecture of SDK root filesystem (e.g., `amd64`). By default set to current Debian host architecture. This variable is optional.
 
 ---
 
@@ -574,3 +577,90 @@ For the variables please have a look at the previous example, the following new
  - `DEBIAN_DEPENDS` - Debian packages that the package depends on
 
 Have a look at the `example-raw` recipe to get an idea how the `dpkg-raw` class can be used to customize your image.
+
+## Create an ISAR SDK root filesystem
+
+### Motivation
+
+Building applications for targets in ISAR takes a lot of time as they are built under QEMU.
+SDK providing crossbuild environment will help to solve this problem.
+
+### Approach
+
+Create SDK root file system for host with installed cross-toolchain for target architecture and ability to install already prebuilt
+target binary artifacts. Developer chroots to sdk rootfs and develops applications for target platform.
+
+### Solution
+
+User manually triggers creation of SDK root filesystem for his target platform by launching the task `do_isar_sdk` for target image, f.e.
+`bitbake -c do_isar_sdk multiconfig:${MACHINE}-${DISTRO}:isar-image-base`.
+
+The resulting SDK rootfs is located under `tmp/work/${DITSRO}-${DISTRO_ARCH}/sdkchroot/rootfs`.
+SDK rootfs directory `/isar-apt` contains the copy of isar-apt repo with locally prebuilt target debian packages.
+One may chroot to SDK and install required target packages with the help of `apt-get install <package_name>:<DISTRO_ARCH>` command.
+
+### Limitation
+
+Only Debian Stretch for SDK root filesystem is supported as only Stretch provides crossbuild environment by default.
+(Debian Jessie requires some additional preconfiguration steps see https://wiki.debian.org/CrossToolchains#Installation for details).
+
+### Example
+
+ - Trigger creation of SDK root filesystem
+
+```
+bitbake -c do_isar_sdk multiconfig:qemuarm-stretch:isar-image-base
+```
+
+ - Mount the following directories in chroot by passing resulting rootfs as an argument to the script `mount_chroot.sh`:
+
+```
+$ cat mount_chroot.sh
+#!/bin/bash
+sudo mount /tmp     $1/tmp                 -o bind
+sudo mount proc     $1/proc    -t proc     -o nosuid,noexec,nodev
+sudo mount sysfs    $1/sys     -t sysfs    -o nosuid,noexec,nodev
+sudo mount devtmpfs $1/dev     -t devtmpfs -o mode=0755,nosuid
+sudo mount devpts   $1/dev/pts -t devpts   -o gid=5,mode=620
+sudo mount tmpfs    $1/dev/shm -t tmpfs    -o rw,seclabel,nosuid,nodev
+
+$ ./mount_chroot.sh ./build/tmp/work/debian-stretch-armhf/sdkchroot/rootfs
+```
+
+ - chroot to isar SDK rootfs:
+
+```
+$ sudo chroot ./build/tmp/work/debian-stretch-armhf/sdkchroot/rootfs
+```
+ - 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
+```
+
+ - Install needed prebuilt target packages.
+
+```
+:~# apt-get install libhello-dev:armhf
+```
+
+ - Check the contents of the installed target package
+
+```
+:~# dpkg -L libhello-dev
+/.
+/usr
+/usr/include
+/usr/include/hello.h
+/usr/lib
+/usr/lib/arm-linux-gnueabihf
+/usr/lib/arm-linux-gnueabihf/libhello.a
+/usr/lib/arm-linux-gnueabihf/libhello.la
+/usr/share
+/usr/share/doc
+/usr/share/doc/libhello-dev
+/usr/share/doc/libhello-dev/changelog.gz
+/usr/share/doc/libhello-dev/copyright
+~#
+```
-- 
2.11.0