[elbe-devel] [PATCH v3 4/4] docs elbe-pbuilder: add cross and ccache description

[Christian Teklenborg]

Add general information about how to use the --cross option and ccache to the
elbe-pbuilder.txt. Also add benchmarks where these options were tested.
Add a description for pbuilder cross and ccache in the quickstart.txt file and
an example for crosscompiling a linux kernel with them.

Signed-off-by: Christian Teklenborg <chris at linutronix.de>
---
 docs/elbe-pbuilder.txt | 32 +++++++++++++++++++++++++++++++-
 docs/quickstart.txt    | 20 ++++++++++++++++++--
 2 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/docs/elbe-pbuilder.txt b/docs/elbe-pbuilder.txt
index eaf69a1e..be220a14 100644
--- a/docs/elbe-pbuilder.txt
+++ b/docs/elbe-pbuilder.txt
@@ -72,7 +72,13 @@ COMMANDS
 'create'::
 
 A pbuilder environment for the given project or xml File will be created.
-If --cross is given the pbuilder environment will be created to crossbuild packages.
+If --cross is given the pbuilder environment will be created to crossbuild
+packages. (If --cross is given with the create command you have to use --cross
+with the build command also.) The compiler cache `ccache` gets installed by
+default to speed up recompilations. To deactivate use `--no-ccache` with the
+create command. It is possible to change the size with `--ccache-size <string>`
+where string should be a number followed by an optional suffix: k, M, G, T.
+For no limit use 0.
 
 'build'::
 
@@ -83,6 +89,30 @@ environment will be created for the given ELBE XML File, and the 'Debianized
 Project' in the current working directory will be built. The result of the
 package build is stored in ../ like pbuilder does.
 
+NOTES
+-----
+In this benchmark all opportunitys for creating a pbuilder environment and
+building a package with it were tested. All environments were created with the
+'armhf-ti-beaglebone-black.xml' example and with cross, ccache, no-cross or
+no-ccache in all possible variations. The build command was tested with the zlib
+package. All times are real-time captures. The build command with ccache was
+tested twice to see the impact of ccache.
+
+
+pbuilder no-ccache create        6m35,003s
+pbuilder no-ccache build         7m19,467s
+
+pbuilder no-ccache cross create  4m2,553s
+pbuilder no-ccache build         2m39,151s
+
+pbuilder ccache create           6m44,117s
+pbuilder ccache build         1. 7m36,130s
+                              2. 4m47,050s
+
+pbuilder ccache cross create     4m4,190s
+pbuilder ccache cross build   1. 2m40,159s
+                              2. 2m32,650s
+
 EXAMPLES
 --------
 
diff --git a/docs/quickstart.txt b/docs/quickstart.txt
index 60e24434..051f0dbb 100644
--- a/docs/quickstart.txt
+++ b/docs/quickstart.txt
@@ -276,8 +276,15 @@ Since Version 1.9.2, elbe is able to create a pbuilder Environment.
 You can create a pbuilder for a specific xml File inside the initvm.
 
 The repositories and architecture specified in the xml File will be used
-to satisfy build dependencies.
-Pbuilder will only build debianised Software.
+to satisfy build dependencies. It is possible to crosscompile packages for a
+foreign architecture. To do so use the 'elbe pbuilder create' command with the
+--cross option. This will setup the right environment for crosscompiling. To
+use this environment you have to use the --cross option with the build command.
+(If the environment was created with the --cross option, the build command
+must be used with --cross too. Otherwise it will throw an error.) By creating
+an environment the compiler cache `ccache` gets installed by default to speed
+up recompilations. It is possible to change the size or to deactivate it if it
+is not needed. Pbuilder will only build debianised Software.
 
 A pbuilder instance is always associated with a project inside the initvm.
 The `pbuilder create` command will write the project uuid to a file, if instructed to
@@ -315,6 +322,15 @@ The repository is download as elbe-projectrepo-20191002-114244.tar.gz.
 This should be unpacked in the DocumentRoot of your webserver and customized with
 your key as explained in the next chapter.
 
+Here is an example for crosscompiling a linux kernel with debian profiles:
+
+---------------------------------------------------------
+$ elbe pbuilder --cross create --xmlfile examples/armhf-ti-beaglebone-black.xml --writeproject pbuilder.prj
+$ apt source linux
+$ cd linux*/
+$ ../elbe pbuilder --cross --origfile ../linux*.orig.tar.xz --profile nodoc,nopython build --project `cat ../pbuilder.prj`
+---------------------------------------------------------
+
 Custom Repository
 -----------------
 
-- 
2.20.1