doc: add bob-init manpage

Author: jkloetzke

doc/conf.py

@@ -260,6 +260,7 @@ def __getattr__(cls, name):
     ('manpages/bob-clean', 'bob-clean', 'Delete unused src/build/dist paths of release builds', ['Jan Klötzke'], 1),
     ('manpages/bob-dev', 'bob-dev', 'Bob develop mode build', ['Jan Klötzke'], 1),
     ('manpages/bob-graph', 'bob-graph', 'Generate dependency graph', ['Ralf Hubert'], 1),
+    ('manpages/bob-init', 'bob-init', 'Initialize out-of-source build tree', ['Jan Klötzke'], 1),
     ('manpages/bob-jenkins', 'bob-jenkins', 'Configure Jenkins server', ['Jan Klötzke'], 1),
     ('manpages/bob-ls', 'bob-ls', 'List package hierarchy', ['Jan Klötzke'], 1),
     ('manpages/bobpaths', 'bobpaths', 'Specifying paths to Bob packages', ['Jan Klötzke'], 7),

doc/manpages/bob-build-dev.rst

@@ -1,3 +1,12 @@
+Build tree location
+-------------------
+
+The build can be done directly in the project root directory or in a separate
+directory. To build outside of the project directory the build-tree must first
+be initialized with :ref:`bob init <manpage-bob-init>`. Any number of build
+trees may refer to the same project. Inside the external build-tree there may
+be a dedicated ``default.yaml``, overriding settings from the project.
+
 Options
 -------
 
@@ -255,3 +264,4 @@ See also
 --------
 
 :ref:`bobpaths(7) <manpage-bobpaths>` :ref:`bob-status(1) <manpage-bob-status>`
+:ref:`bob-init(1) <manpage-bob-init>`

doc/manpages/bob-init.rst

@@ -0,0 +1,32 @@
+.. _manpage-bob-init:
+
+bob-init
+========
+
+.. only:: not man
+
+   Name
+   ----
+
+   bob-init - Initialize out-of-source build tree
+
+Synopsis
+--------
+
+::
+
+    bob init [-h] PROJECT [BUILD]
+
+
+Description
+-----------
+
+Setup a build directory that builds the project located at ``PROJECT``. By
+default the current directory is initialized. Optionally the build directory
+can be specified as 2nd parameter ``BUILD``. The directories to the build
+directory will be created if they do not exist yet.
+
+See also
+--------
+
+:ref:`bob-build(1) <manpage-build>` :ref:`bob-dev(1) <manpage-dev>`

doc/manpages/index.rst

@@ -11,6 +11,7 @@ Contents:
    bob-clean
    bob-dev
    bob-graph
+   bob-init
    bob-jenkins
    bob-ls
    bobpaths

doc/tutorial/compile.rst

@@ -169,6 +169,20 @@ and test the whole QEMU image. The choice is yours.
    before moving on. Otherwise you risk that your changes are wiped out if Bob
    determines that a clean build is needed (e.g. due to recipe changes).
 
+Out of tree builds
+==================
+
+The :ref:`manpage-dev` and :ref:`manpage-build` commands do not need to be
+executed in the project directory directly. It is also possible to initialize
+an external build directory with :ref:`manpage-bob-init`::
+
+    $ bob init . /path/to/build/directory
+    $ cd /path/to/build/directory
+    $ bob dev vexpress
+
+Each build directory can have its own :ref:`configuration-config-usr` that
+overrides the defaults of the project.
+
 Query SCM status
 ================