doc: document bundle

Author: rhubert

doc/manpages/bob-build-dev.rst

@@ -96,6 +96,23 @@ 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 zip-file containing all sources required to build the package. This also
+    enables `--always-checkout` and `--clean-checkout` and can not be used
+    along with `--build-only`.
+
+``--bundle-exclude BUNDLE_EXCLUDE``
+    Do not add packages matching a given regular expression (regex) to the
+    bundle. Can be specified multiple times.
+
+``--bundle-vcs``
+    Add files used by version control systems to the bundle.
+
+``--unbundle BUNDLE``
+    Try to download sources from BUNDLE first. The BUNDLE should be the zip
+    file created with the ``--bundle`` option.
+
 ``--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``)
@@ -363,6 +380,9 @@ Options
 ``-q, --quiet``
     Decrease verbosity (may be specified multiple times)
 
+``--unbundle``
+    Use bundle specified by ``--bundle`` as source input.
+
 ``-v, --verbose``
     Increase verbosity (may be specified multiple times)
 

doc/manpages/bob-build.rst

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

doc/manpages/bob-dev.rst

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

doc/tutorial/compile.rst

@@ -350,3 +350,30 @@ the zlib packages: ::
 .. raw:: html
 
     <iframe src="../_static/sandbox.html" height="500px" width="100%"></iframe>
+
+Using source bundles
+====================
+
+A source code bundle is a zip file containing all the sources required to build a
+package. Such a bundle can be used to compile on a air gapped system, to
+archive the build input, to transfer the sources to a reviewer, ...
+
+To create a bundle for a given package you need to build this package using
+:ref:`manpage-dev` or :ref:`manpage-build` with the ``--bundle`` option. This
+option takes one argument specifying the name of the bundle file. Several other
+`bundle` arguments are available to control what goes into the bundle. Refer to
+the manpages for a detailed description of those.
+
+For example to bundle the sources needed to build `my_package` use: ::
+
+     $ bob build my_package --bundle my_package_bundle.zip
+
+After that you can take the my_package_bundle.tar to another system and use: ::
+
+     $ bob build my_package --unbundle my_package_bundle.zip
+
+to build `my_package` from the bundled-sources.
+
+.. note::
+    The recipes and `bob` are not part of the bundle and need to be handled
+    separately. It's strongly recommended to use matching recipes.