Add additional sandbox modes

.gitattributes

@@ -1 +1,2 @@
 *.svg binary
+doc/_static/d3.v4.min.js binary

contrib/bash-completion/bob

@@ -57,11 +57,8 @@ __bob_complete_path()
    # influence parsing and must be passed to "bob ls".
    for i in "${words[@]}"; do
       case "$i" in
-         --sandbox)
-            sandbox="--sandbox"
-            ;;
-         --no-sandbox)
-            sandbox="--no-sandbox"
+         --*sandbox)
+            sandbox="$i"
             ;;
 		 -c?* | -D?*)
 		    cmd_settings+=( "$i" )
@@ -130,7 +127,7 @@ __bob_cook()
    elif [[ "$prev" = "--always-checkout" ]] ; then
       COMPREPLY=( )
    else
-      __bob_complete_path "--destination -j --jobs -k --keep-going -f --force -n --no-deps -p --with-provided --without-provided -A --no-audit --audit -b --build-only -B --checkout-only --normal --clean --incremental --always-checkout --resume -q --quiet -v --verbose --no-logfiles -D -c -e -E -M --upload --link-deps --no-link-deps --download --download-layer --shared --no-shared --install --no-install --sandbox --no-sandbox --clean-checkout --attic --no-attic"
+      __bob_complete_path "--destination -j --jobs -k --keep-going -f --force -n --no-deps -p --with-provided --without-provided -A --no-audit --audit -b --build-only -B --checkout-only --normal --clean --incremental --always-checkout --resume -q --quiet -v --verbose --no-logfiles -D -c -e -E -M --upload --link-deps --no-link-deps --download --download-layer --shared --no-shared --install --no-install --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox --clean-checkout --attic --no-attic"
    fi
 }
 
@@ -151,7 +148,7 @@ __bob_graph()
    if [[ "$prev" = "-t" || "$prev" = "--type" ]] ; then
          __bob_complete_words "d3 dot"
    else
-      __bob_complete_path "-c -D -e --exclude -f --filename -H --highlight -n --max-depth -t --type -o --sandbox --no-sandbox"
+      __bob_complete_path "-c -D -e --exclude -f --filename -H --highlight -n --max-depth -t --type -o --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox"
    fi
 }
 
@@ -162,7 +159,7 @@ __bob_help()
 
 __bob_ls()
 {
-   __bob_complete_path "-a --all -c -D -d --direct --no-sandbox -o --origin -p --prefixed -r --recursive --sandbox -u --unsorted"
+   __bob_complete_path "-a --all -c -D -d --direct --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox -o --origin -p --prefixed -r --recursive --sandbox -u --unsorted"
 }
 
 __bob_init()
@@ -183,7 +180,7 @@ __bob_jenkins_add()
 
    case "$cur" in
       -*)
-         __bob_complete_words "--clean --credentials --download --help --host-platform --keep --longdescription --no-sandbox --nodes --prefix --root --shortdescription --upload --windows -D -h -n -o -p -r -w"
+         __bob_complete_words "--clean --credentials --download --help --host-platform --keep --longdescription --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox --nodes --prefix --root --shortdescription --upload --windows -D -h -n -o -p -r -w"
          ;;
       *)
          case "$prev" in
@@ -304,7 +301,7 @@ __bob_jenkins_set_options()
 
    case "$cur" in
       -*)
-         __bob_complete_words "-h --help --reset -n --nodes -o -p --prefix --add-root --del-root -D -U --credentials --authtoken --shortdescription --longdescription --keep --no-keep --download --no-download --upload --no-upload --sandbox --no-sandbox --clean --incremental --host-platform"
+         __bob_complete_words "-h --help --reset -n --nodes -o -p --prefix --add-root --del-root -D -U --credentials --authtoken --shortdescription --longdescription --keep --no-keep --download --no-download --upload --no-upload --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox --clean --incremental --host-platform"
          ;;
       *)
          case "$prev" in
@@ -353,7 +350,7 @@ __bob_project()
    elif [[ -z "$command" ]] ; then
       case "$cur" in
          -*)
-            __bob_complete_words "-b -c -D --download -E -e -j --list -n --no-sandbox --resume --sandbox"
+            __bob_complete_words "-b -c -D --download -E -e -j --list -n --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox --resume --sandbox"
             ;;
          *)
             __bob_complete_words "$($bob --color=never project --list 2>/dev/null)"
@@ -366,22 +363,22 @@ __bob_project()
 
 __bob_query_scm()
 {
-    __bob_complete_path "-c -D -f --default -r --recursive --sandbox --no-sandbox"
+    __bob_complete_path "-c -D -f --default -r --recursive --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox"
 }
 
 __bob_query_path()
 {
-  __bob_complete_path "-f -D -c --sandbox --no-sandbox --develop --release"
+  __bob_complete_path "-f -D -c --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox --develop --release"
 }
 
 __bob_query_meta()
 {
-  __bob_complete_path " -c -D -r --recursive --sandbox --no-sandbox"
+  __bob_complete_path " -c -D -r --recursive --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox"
 }
 
 __bob_query_recipe()
 {
-    __bob_complete_path "-c -D --sandbox --no-sandbox"
+    __bob_complete_path "-c -D --sandbox --no-sandbox --slim-sandbox --dev-sandbox --strict-sandbox"
 }
 
 __bob_status()
@@ -419,7 +416,8 @@ __bob_show()
     elif [[ "$prev" = "--indent" ]] ; then
         COMPREPLY=( )
     else
-        __bob_complete_path "-D -c --sandbox --no-sandbox --show-empty
+        __bob_complete_path "-D -c --sandbox --no-sandbox --slim-sandbox
+            --dev-sandbox --strict-sandbox --show-empty
             --show-common --indent --no-indent --format -f"
     fi
 }

doc/manpages/bob-build-dev.rst

@@ -7,6 +7,67 @@ 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.
 
+Sandboxing
+----------
+
+Sandboxing allows to execute the build steps in ephemeral containers. The
+feature is currently available on Linux only. There are different aspects to
+sandboxing:
+
+1. Isolating from the host environment. By using a project defined sandbox
+   image, the build environment is made independent of the host Linux
+   distribution.
+2. Controlling the accessible project paths. Only declared dependencies are
+   accessible read-only. The build workspace is the only writable path (despite
+   ``/tmp``). All other project paths are not not accessible at all.
+3. Providing stable execution paths. Sometimes the build path is leaking into
+   the created binaries. Inside the sandbox environment, the paths can be made
+   reproducible.
+
+.. only:: not man
+
+    To accommodate for different use cases, five different sandbox modes are
+    supported by Bob. They differ in their degree of isolation and execution path
+    stability:
+
+    +----------------------+--------------------------------+------------------------------------------+
+    | Mode                 | Packages without sandbox image | Packages with sandbox image              |
+    |                      +-------------+------------------+-----------+-------------+----------------+
+    |                      | Isolation   | Execution path   | Isolation | Image used? | Execution path |
+    +======================+=============+==================+===========+=============+================+
+    | ``--no-sandbox``     | \-          |  Workspace       |  \-       | n/a         | Workspace      |
+    +----------------------+-------------+------------------+-----------+-------------+----------------+
+    | ``--sandbox``        | \-          |  Workspace       |  Yes      | Yes         | Stable         |
+    +----------------------+-------------+------------------+-----------+-------------+----------------+
+    | ``--slim-sandbox``   | Yes         |  Workspace       |  Yes      | \-          | Workspace      |
+    +----------------------+-------------+------------------+-----------+-------------+----------------+
+    | ``--dev-sandbox``    | Yes         |  Workspace       |  Yes      | Yes         | Workspace      |
+    +----------------------+-------------+------------------+-----------+-------------+----------------+
+    | ``--strict-sandbox`` | Yes         |  Stable          |  Yes      | Yes         | Stable         |
+    +----------------------+-------------+------------------+-----------+-------------+----------------+
+
+    The overall behaviour depends on the availability of a sandbox image. Such
+    an image must be provided by a recipe via
+    :ref:`configuration-recipes-provideSandbox` and the sandbox image must have
+    been picked up by a ``use: [sandbox]`` dependency.
+
+    The execution path is the path where the checkout/build/packageScript is
+    executed. This is usually the *workspace* path but some modes use a
+    *stable* path instead. Stable paths start with ``/bob/...`` and are computed
+    from the :term:`Variant-Id` of the step. An unchanged step will always be
+    executed at the same stable path in a sandbox.
+
+Using ``--no-sandbox`` will not use any sandboxing features and all build steps
+are executed without any isolation on the build host. The ``--sandbox`` option
+will provide partial isolation only if a sandbox image is available for a package.
+Inside the sandbox image all paths are stable, i.e. independent of the
+workspace path. As a light-weight alternative, the ``--slim-sandbox`` option
+will always provide isolation but an available sandbox image is not used and
+all workspace paths are retained. Likewise, the ``--dev-sandbox`` option will
+also provide full isolation but an available sandbox image is used. The
+``--strict-sandbox`` option further uses stable paths consistently.
+
+
 Options
 -------
 
@@ -65,6 +126,13 @@ Options
     enable ``--with-provided`` to build and copy all provided packages of the
     built package(s).
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
+    Always build packages in an isolated environment where only declared
+    dependencies are visible. If a sandbox image is available, it is used.
+    Otherwise the host paths are made read-only.
+
 ``--download MODE``
     Download from binary archive (yes, no, deps, forced, forced-deps, packages)
 
@@ -134,11 +202,31 @@ Options
     failed and the error has been corrected in the failing package.
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+    Build packages in an ephemeral container if a sandbox image is available
+    for the package. Inside the sandbox, stable execution paths are used. In
+    absence of a sandbox image, no isolation is performed.
 
 ``--shared``
     Use shared packages if they are available. This is the default.
 
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+    Build packages in an isolated mount namespace. Most of the host paths
+    are available read-only. Other workspaces are hidden when building a
+    package unless they are a declared dependency. An optionally available
+    sandbox image is *not* used.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
+
+    Always build packages in an isolated environment where only declared
+    dependencies are visible. If a sandbox image is available, it is used.
+    Otherwise the host paths are made read-only. The build path is always
+    a reproducible, stable path.
+
 ``--upload``
     Upload to binary archive
 

doc/manpages/bob-build.rst

@@ -22,7 +22,8 @@ Synopsis
               [-lc LAYERCONFIG] [-e NAME] [-E] [-M META] [--upload]
               [--link-deps] [--no-link-deps] [--download MODE]
               [--download-layer MODE] [--shared | --no-shared]
-              [--install | --no-install] [--sandbox | --no-sandbox]
+              [--install | --no-install]
+              [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
               [--clean-checkout] [--attic | --no-attic]
               PACKAGE [PACKAGE ...]
 

doc/manpages/bob-dev.rst

@@ -22,11 +22,11 @@ Synopsis
             [-lc LAYERCONFIG] [-e NAME] [-E] [-M META] [--upload]
             [--link-deps] [--no-link-deps] [--download MODE]
             [--download-layer MODE] [--shared | --no-shared]
-            [--install | --no-install] [--sandbox | --no-sandbox]
+            [--install | --no-install]
+            [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
             [--clean-checkout] [--attic | --no-attic]
             PACKAGE [PACKAGE ...]
 
-
 Description
 -----------
 

doc/manpages/bob-graph.rst

@@ -15,7 +15,8 @@ Synopsis
 
 ::
 
-    bob graph [-h] [-D DEFINES] [-c CONFIGFILE] [--sandbox | --no-sandbox]
+    bob graph [-h] [-D DEFINES] [-c CONFIGFILE]
+              [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
               [--destination DEST] [-e EXCLUDES] [-f FILENAME]
               [-H HIGHLIGHTS] [-n MAX_DEPTH] [-t {d3,dot}] [-o OPTIONS]
               PACKAGE [PACKAGE ...]
@@ -45,6 +46,9 @@ Options
 ``--destination``
     Destination of graph output files.
 
+``--dev-sandbox``
+    Enable development sandboxing. Include sandbox dependencies in the graph.
+
 ``-e, --excludes``
     Do not show packages matching this regex. (And all it's
     dependencies)
@@ -64,7 +68,13 @@ Options
     the default.
 
 ``--sandbox``
-    Enable sandboxing. Include sandbox dependencies in the graph.
+    Enable partial sandboxing. Include sandbox dependencies in the graph.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing. Include sandbox dependencies in the graph.
 
 ``-t, --type``
     Set the graph type. ``d3`` (default) or ``dot``.

doc/manpages/bob-jenkins.rst

@@ -26,8 +26,8 @@ Available sub-commands:
     bob jenkins add [-h] [-n NODES] [-o OPTIONS]
                     [--host-platform {linux,msys,win32}] [-w] [-p PREFIX]
                     [-r ROOT] [-D DEFINES] [--keep] [--download] [--upload]
-                    [--no-sandbox] [--credentials CREDENTIALS]
-                    [--clean | --incremental]
+                    [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
+                    [--credentials CREDENTIALS] [--clean | --incremental]
                     [--shortdescription | --longdescription]
                     name url
     bob jenkins export [-h] name dir
@@ -50,7 +50,7 @@ Available sub-commands:
                             [--keep | --no-keep]
                             [--download | --no-download]
                             [--upload | --no-upload]
-                            [--sandbox | --no-sandbox]
+                            [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
                             [--clean | --incremental]
                             name
     bob jenkins set-url [-h] name url
@@ -126,6 +126,13 @@ Options
 ``--del-root DEL_ROOT``
     Remove existing root package.
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
+    Always build packages in an isolated environment where only declared
+    dependencies are visible. If a sandbox image is available, it is used.
+    Otherwise the host paths are made read-only.
+
 ``--download``
     Enable downloads from binary archive. Disabled by default. There must
     be at least one binary archive in the user configuration
@@ -224,7 +231,8 @@ Options
     Disable sandboxing during builds.
 
     Unless required by the project, it is discouraged to disable the sandbox
-    feature. See ``--sandbox`` for the opposite switch.
+    feature. See ``--sandbox``, ``--slim-sandbox``, ``--dev-sandbox`` or
+    ``--strict-sandbox`` for the opposite switches.
 
 ``--no-ssl-verify``
     Disable HTTPS certificate checking.
@@ -296,7 +304,11 @@ Options
     on the previous state.
 
 ``--sandbox``
-    Enable sandboxing. This is the default.
+    Enable partial sandboxing. This is the default.
+
+    Build packages in an ephemeral container if a sandbox image is available
+    for the package. Inside the sandbox, stable execution paths are used. In
+    absence of a sandbox image, no isolation is performed.
 
 ``--shortdescription``
     Do not calculate every possible path of each package in a job for the
@@ -305,6 +317,22 @@ Options
     drawback is that not all packages are then listed in the job description.
     For each unique package only one example path will be shown.
 
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+    Build packages in an isolated mount namespace. Most of the host paths
+    are available read-only. Other workspaces are hidden when building a
+    package unless they are a declared dependency. An optionally available
+    sandbox image is *not* used.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
+
+    Always build packages in an isolated environment where only declared
+    dependencies are visible. If a sandbox image is available, it is used.
+    Otherwise the host paths are made read-only. The build path is always
+    a reproducible, stable path.
+
 ``-U UNDEFINES``
     Undefine environment variable override. This removes a variable previously
     defined with ``-D``.

doc/manpages/bob-ls.rst

@@ -16,10 +16,10 @@ Synopsis
 ::
 
     bob ls [-h] [-a] [-A] [-o] [-r] [-u] [-p | -d] [-D DEFINES]
-           [-c CONFIGFILE] [--sandbox | --no-sandbox]
+           [-c CONFIGFILE]
+           [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
            [package]
 
-
 Description
 -----------
 
@@ -80,6 +80,9 @@ Options
 ``-D DEFINES``
     Override default environment variable
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``--no-sandbox``
     Disable sandboxing
 
@@ -95,7 +98,13 @@ Options
     Recursively display dependencies
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
 
 ``-u, --unsorted``
     Show the packages in the order they were named in the recipe. By default