[PATCH v5 11/12] doc: Provide some notes about cross-compilation

[Alexander Smirnov <asmirnov@ilbers.de>]

Provide general overview and steps how to enable cross-compilation in
Isar.

Signed-off-by: Alexander Smirnov <asmirnov@ilbers.de>
---
 doc/technical_overview.md | 49 ++++++++++++++++++++++++++++++++++-------------
 doc/user_manual.md        | 27 ++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 13 deletions(-)

diff --git a/doc/technical_overview.md b/doc/technical_overview.md
index ab62de9..ddd2c79 100644
--- a/doc/technical_overview.md
+++ b/doc/technical_overview.md
@@ -57,24 +57,29 @@ Typical example, when Isar builds the following configurations:
 
  - Debian Stretch, i386
 
-In this case there will be 3 different buildchroots, so standard hello demo
-application should be processed 3 times for each environment. Three different
-sets of stamps should be used for correct bitbake operating.
+In this case there will be 3 different build subtrees. So the standard
+example-hello demo application will be processed 3 times for each
+environment. Three different sets of stamps will be used to distinguish
+build progress between different bitbake configurations.
 
 ## 2.3 Buildchroot
 
 One of the key aspect of Debian philosophy claims the fact, that everything in
-Debian should be built within Debian environment. Moreover native compilation
-is more preferable than cross-compilation. To follow this rules, Isar
+Debian should be built within Debian environment. To follow this rule, Isar
 introduces the new component - buildchroot. Bulidchroot is typical Debian
 filesystem that is created using standard Debian tools: debootstrap, apt. The
 source of packages can be either official Debian repositories or custom
-repositories created by user.
+repositories created by user. Buildchroot could be one of the following type:
+
+ - `buildchroot-host` with the host architecture for cross-compilation.
+
+ - `buildchroot-target` with the target architecture for target native
+   compilation.
 
 Buildchroot lifecycle can be described as following:
 
  - Buildchroot starts out with a minimal base system that was generated by the
-   isar-bootstrap recipe that uses debootstrap and apt.
+   isar-bootstrap-[host,target] recipe that uses debootstrap and apt.
 
  - During building custom Debian package, list of its build dependencies is
    installed to buildchroot.
@@ -85,7 +90,8 @@ Buildchroot lifecycle can be described as following:
 ## 2.4 Target Root Filesystem
 
 Target filesystem is quite similar to buildchroot. The only difference is that
-it doesn't have development packages installed.
+it doesn't have development packages installed and always has target
+architecture.
 
 Target filesystem lifecycle can be described as following:
 
@@ -93,7 +99,8 @@ Target filesystem lifecycle can be described as following:
    system generated by the isar-bootstrap recipe.
 
  - According to the list of custom packages in bitbake recipes, the initial
-   filesystem will be populated by successfully built packages.
+   filesystem will be populated by successfully built packages from locally
+   created Isar repository.
 
 # 3 Isar Internal Processes
 
@@ -120,7 +127,7 @@ All these steps are described in details below.
 ## 3.2 Minimal base system
 
 A minimal base system is generated by the isar-bootstrap recipe found here:
-`meta/recipes-core/isar-bootstrap/isar-bootstrap.bb`.
+`meta/recipes-core/isar-bootstrap/isar-bootstrap-[host,target].bb`.
 
 This recipe implements several tasks which are executed in this order:
 
@@ -155,9 +162,12 @@ This recipe implements several tasks which are executed in this order:
 As mentioned above, initial buildchroot is generated using the minimal base
 system generated by isar-bootstrap. The bitbake recipe which is responsible for
 buildchroot can be found here:
-`meta/recipes-devtools/buildchroot/buildchroot.bb`
+`meta/recipes-devtools/buildchroot/buildchroot-[host,target].bb`
 
-This recipe implementes `do_build` task which performs the following:
+Section 3.8 describes when host or target architecture is used, please refer
+to it for more details.
+
+This recipe implements `do_build` task which performs the following:
 
 1. Calls the `setup_root_file_system` helper function defined in
    `meta/classes/isar-bootstrap-helper.bbclass` that copies the minimal base
@@ -191,7 +201,8 @@ here: `meta-isar/recipes-core/images/files`, and it implements `do_build` task.
 Isar provides the possibility to build Debian packages from sources. This
 feature works with Debian-like source packages, i.e. the source code tree
 should contain debian folder. This build process is implemented in
-`meta/classes/dpkg.bbclass`.
+`meta/classes/dpkg.bbclass`. Moreover this process is common for both: native
+and cross compilation modes.
 
 Another way of creating Debian packages is implemented in
 `meta/classes/dpkg-raw.bbclass`. This class can be used for customizations that
@@ -247,3 +258,15 @@ This process contains the following steps:
 
    1.1. `do_ext4_image`: target filesystem is packed to extfs image.
    1.2. `do_wic_image`: a bootable disk image gets created for the platform
+
+## 3.8 Cross-compilation
+
+Isar provides possibility to cross-compile all or individual packages. There is
+variable ISAR_CROSS_COMPILE that could be set globaly for whole Isar build,
+but also it could be overwritten from the individual recipe to force specific
+compilation mode for it. This variable influences on which buildchroot will be
+used for recipe compilation. Isar is free from packages modification to perform
+cross-compilation, this is done by the same tools as for native compilation.
+Depending on ISAR_CROSS_COMPILE value, additional architecture specifiers are
+passed to build tools automatically, so this is absolutely transparent from
+the user point of view.
diff --git a/doc/user_manual.md b/doc/user_manual.md
index 7549d26..4e7f29a 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)
+ - [Enabling Cross-compilation](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#isar-cross-compilation)
  - [Create an ISAR SDK root filesystem](https://github.com/ilbers/isar/blob/master/doc/user_manual.md#create-an-isar-sdk-root-filesystem)
 
 ## Introduction
@@ -582,6 +583,32 @@ For the variables please have a look at the previous example, the following new
 
 Have a look at the `example-raw` recipe to get an idea how the `dpkg-raw` class can be used to customize your image.
 
+## Isar Cross-compilation
+
+### Motivation
+
+binfmt is a powerful feature that makes possible to run foreign architectures like ARM on x86 hosts. But at the same the performance of
+such emulation is quite low. For the cases when lots of packages should be built from sources, a cross-compilation support could be very
+useful.
+
+### Solution
+
+Cross-compilation mode could be enabled by using the `ISAR_CROSS_COMPILE` variable. This variable could be set in both:
+
+ - In `local.conf` to set cross-compilation mode to be the default option for the whole build.
+ - In specific recipe to overwrite global settings. This could be useful when package doesn't support cross-compilation, so the following line
+   should be added to its recipe: `ISAR_CROSS_COMPILE := "0"`.
+
+The cross-building process is absolutely the same as for native compilation, no extra tasks are added and removed: newly built packages are
+put into Isar apt.
+
+### Limitation
+
+Debian cross-compilation works out of the box starting from Debian stretch distribution. So currently the only following build configurations are supported in Isar:
+
+ - qemuarm-stretch
+ - qemuarm64-stretch
+
 ## Create an ISAR SDK root filesystem
 
 ### Motivation
-- 
2.11.0