doc: document bundle

Author: rhubert

doc/manpages/bob-build-dev.rst

@@ -96,6 +96,14 @@ Options
 
     This is the default unless the user changed it in ``default.yaml``.
 
+``--bundle BUNDLE``
+    Bundle all the sources needed to build the package. The output of this is a
+    tar-file containing one tar-file for each source workspace needed to build
+    the package. This also enables `--always-checkout`.
+
+``--bundle-exclude RE``
+    Do not add packages matching (fnmatch) RE to the bundle.
+
 ``--clean``
     Do clean builds by clearing the build directory before executing the build
     commands. It will *not* clean all build results (e.g. like ``make clean``)
@@ -360,6 +368,10 @@ Options
 ``-q, --quiet``
     Decrease verbosity (may be specified multiple times)
 
+``--unbundle``
+    Use bundle specified by ``--bundle`` but unbundle the sources from the
+    bundle.
+
 ``-v, --verbose``
     Increase verbosity (may be specified multiple times)
 

doc/manpages/bob-build.rst

@@ -25,6 +25,7 @@ Synopsis
               [--install | --no-install]
               [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
               [--clean-checkout] [--attic | --no-attic]
+              [--bundle BUNDLE] [--bundle-exclude BUNDLE_EXCLUDE] [--unbundle]
               PACKAGE [PACKAGE ...]
 
 Description

doc/manpages/bob-dev.rst

@@ -25,6 +25,7 @@ Synopsis
             [--install | --no-install]
             [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
             [--clean-checkout] [--attic | --no-attic]
+            [--bundle BUNDLE] [--bundle-exclude BUNDLE_EXCLUDE] [--unbundle]
             PACKAGE [PACKAGE ...]
 
 Description

doc/tutorial/compile.rst

@@ -350,3 +350,31 @@ the zlib packages: ::
 .. raw:: html
 
     <iframe src="../_static/sandbox.html" height="500px" width="100%"></iframe>
+
+Using source bundles
+====================
+
+A source code bundle is a tar file with all the sources needed to build a
+package included. This bundle can be used to compile on a air gapped system, to
+archive the build input, to transfer the sources to a reviewer, ...
+
+To bundle a all the input for a given package you need to build it using
+:ref:`manpage-dev` or :ref:`manpage-build` with the ``--bundle`` option. This
+option takes one argument specifying the name of the bundle file.
+There is also a ``--bundle-exclude`` option which allows it to exclude the
+sources of packages to be excluded from the bundle.
+
+For example to bundle the sources needed to build my_package without the packges
+matching `foo**` use: ::
+
+     $ bob build my_package --bundle my_package_bundle.tar --bundle-exclude foo*
+
+After that you can take the my_package_bundle.tar to another system and use: ::
+
+     $ bob build my_package  --bundle my_package_bundle.tar --unbundle
+
+to build `my_package` without having access to the sources in the recipes.
+
+.. note::
+    The recipes and `bob` are not part of the bundle and need to be handled
+    seperately.