doc: document added sandbox switches of remaining commands

BobBuildTool · Oct 13, 2024 · bdb6580 · bdb6580
1 parent 7a6d161
commit bdb6580
Show file tree

Hide file tree

Showing 8 changed files with 124 additions and 29 deletions.
diff --git a/doc/manpages/bob-graph.rst b/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``.

diff --git a/doc/manpages/bob-ls.rst b/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

diff --git a/doc/manpages/bob-project.rst b/doc/manpages/bob-project.rst
@@ -17,7 +17,7 @@ Synopsis
 
     bob project [-h] [--list] [-D DEFINES] [-c CONFIGFILE] [-e NAME] [-E]
                 [--download MODE] [--resume] [-n] [-b] [-j [JOBS]]
-                [--sandbox | --no-sandbox]
+                [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
                 [projectGenerator] [package] ...
 
 
@@ -32,6 +32,13 @@ Options
 ``-c CONFIGFILE``
     Use config File
 
+``--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, packages)
 
@@ -57,7 +64,7 @@ Options
     work
 
 ``--no-sandbox``
-    Disable sandboxing
+    Disable sandboxing. This is the default.
 
 ``-b``
     Do build only (bob dev -b) before generate project Files. No checkout
@@ -66,7 +73,27 @@ Options
     Resume build where it was previously interrupted
 
 ``--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.
+
+``--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.
 
 Eclipse CDT project generator
 -----------------------------

diff --git a/doc/manpages/bob-query-meta.rst b/doc/manpages/bob-query-meta.rst
@@ -17,7 +17,7 @@ Synopsis
 ::
 
     bob query-meta [-h] [-D DEFINES] [-c CONFIGFILE] [-r]
-                   [--sandbox | --no-sandbox]
+                   [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
                    packages [packages ...]
 
 Description
@@ -34,11 +34,20 @@ Options
 ``-D DEFINES``
     Override default environment variable
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``--no-sandbox``
     Disable sandboxing
 
 ``-r``
     Also list metaEnvironment variables for all dependencies.
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
diff --git a/doc/manpages/bob-query-path.rst b/doc/manpages/bob-query-path.rst
@@ -15,9 +15,11 @@ Synopsis
 
 ::
 
-    bob query-path [-h] [-f FORMAT] [-D DEFINES] [-c CONFIGFILE]
-                   [--sandbox | --no-sandbox] [--develop | --release]
-                   [-q] [--fail] PACKAGE [PACKAGE ...]
+    bob query-path [-h] [-f FORMAT] [-D DEFINES] [-c CONFIGFILE] [-q]
+                   [--fail]
+                   [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
+                   [--develop | --release]
+                   PACKAGE [PACKAGE ...]
 
 Description
 -----------
@@ -26,15 +28,15 @@ This command lists existing workspace directory names for packages given
 on the command line. Output is formatted with a format string that can
 contain placeholders
 
-    +----------+------------------+
-    |{name}    |package name      |
-    +----------+------------------+
-    |{src}     |checkout directory|
-    +----------+------------------+
-    |{build}   |build directory   |
-    +----------+------------------+
-    |{dist}    |package directory |
-    +----------+------------------+
+    +-----------+--------------------+
+    | {name}    | package name       |
+    +-----------+--------------------+
+    | {src}     | checkout directory |
+    +-----------+--------------------+
+    | {build}   | build directory    |
+    +-----------+--------------------+
+    | {dist}    | package directory  |
+    +-----------+--------------------+
 
 The default format is '{name}<tab>{dist}'.
 
@@ -52,6 +54,9 @@ Options
 ``-D DEFINES``
     Override default environment variable
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``--develop``
     Use developer mode
 
@@ -71,5 +76,10 @@ Options
     Use release mode
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
 
+``--strict-sandbox``
+    Enable strict sandboxing.
diff --git a/doc/manpages/bob-query-recipe.rst b/doc/manpages/bob-query-recipe.rst
@@ -16,7 +16,7 @@ Synopsis
 ::
 
     bob query-recipe [-h] [-D DEFINES] [-c CONFIGFILE]
-                     [--sandbox | --no-sandbox]
+                     [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
                      package
 
 Description
@@ -33,8 +33,17 @@ Options
 ``-D DEFINES``
     Override default environment variable
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``--no-sandbox``
     Disable sandboxing
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
diff --git a/doc/manpages/bob-query-scm.rst b/doc/manpages/bob-query-scm.rst
@@ -14,8 +14,10 @@ Synopsis
 --------
 
 ::
+
     bob query-scm [-h] [-D DEFINES] [-c CONFIGFILE] [-f FORMATS]
-                  [--default DEFAULT] [-r] [--sandbox | --no-sandbox]
+                  [--default DEFAULT] [-r]
+                  [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
                   packages [packages ...]
 
 Description
@@ -44,6 +46,9 @@ Options
 ``--default DEFAULT``
     Default for missing attributes (default: "")
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``-f FORMATS``
     Output format for scm (syntax: scm=format). Can be specified multiple times.
 
@@ -54,4 +59,10 @@ Options
     Recursively display dependencies
 
 ``--sandbox``
-    Enable sandboxing
+    Enable partial sandboxing.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing.
diff --git a/doc/manpages/bob-show.rst b/doc/manpages/bob-show.rst
@@ -15,7 +15,8 @@ Synopsis
 
 ::
 
-    bob show [-h] [-D DEFINES] [-c CONFIGFILE] [--sandbox | --no-sandbox]
+    bob show [-h] [-D DEFINES] [-c CONFIGFILE]
+             [--sandbox | --slim-sandbox | --dev-sandbox | --strict-sandbox | --no-sandbox]
              [--show-empty] [--show-common] [--indent INDENT | --no-indent]
              [--format {yaml,json,flat,diff}]
              [-f {buildNetAccess,buildTools,buildToolsWeak,buildVars,buildVarsWeak,
@@ -62,6 +63,9 @@ the properties that are different between both packages.
 Options
 -------
 
+``--dev-sandbox``
+    Enable development sandboxing.
+
 ``-f FIELD``
    Show only the given ``FIELD``. This option may be specified more than once
    to show additional fields. If this option is not given then all fields are
@@ -83,7 +87,7 @@ Options
    Disable sandboxing.
 
 ``--sandbox``
-   Enable sandboxing.
+   Enable partial sandboxing.
 
 ``--show-common``
    The ``diff`` format suppresses identical fields by default. This option
@@ -94,3 +98,9 @@ Options
    as short as possible. Specifying this option will still show them. If the
    package does not have a checkout- or build-step the respective properties do
    not exist and will never be shown.
+
+``--slim-sandbox``
+    Enable slim sandboxing.
+
+``--strict-sandbox``
+    Enable strict sandboxing.