From 8f0d98a506d0b27598d63ad1730082e8a83ebb20 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Mon, 1 Mar 2021 13:32:31 +0000
Subject: [PATCH] Update documentation

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 pressure-vessel/wrap.1.md | 154 ++++++++++++++++++++++++++++----------
 pressure-vessel/wrap.c    |   5 ++
 2 files changed, 121 insertions(+), 38 deletions(-)

diff --git a/pressure-vessel/wrap.1.md b/pressure-vessel/wrap.1.md
index e682891fd..b75218707 100644
--- a/pressure-vessel/wrap.1.md
+++ b/pressure-vessel/wrap.1.md
@@ -53,29 +53,46 @@ pressure-vessel-wrap - run programs in a bubblewrap container
     directory. This is the same home directory that a Flatpak app for
     freedesktop.org app *ID* would use.
 
+`--gc-legacy-runtimes`, `--no-gc-legacy-runtimes`
+:   Garbage-collect old temporary runtimes in the `--runtime-base` that
+    appear to be left over from older versions of the **SteamLinuxRuntime**
+    launcher scripts. `--no-gc-legacy-runtimes` disables this behaviour,
+    and is the default.
+
 `--gc-runtimes`, `--no-gc-runtimes`
 :   If using `--variable-dir`, garbage-collect old temporary
     runtimes that are left over from a previous **pressure-vessel-wrap**.
     This is the default. `--no-gc-runtimes` disables this behaviour.
 
 `--generate-locales`, `--no-generate-locales`
-:   Passed to **pressure-vessel-wrap**(1).
+:   Passed to **pressure-vessel-adverb**(1).
     The default is `--generate-locales`, overriding the default
-    behaviour of **pressure-vessel-wrap**(1).
+    behaviour of **pressure-vessel-adverb**(1).
+
+`--graphics-provider` *DIR*
+:   If using a `--runtime`, use *DIR* to provide graphics drivers.
+
+    If *DIR* is the empty string, take the graphics drivers from the
+    runtime. This will often lead to software rendering, poor performance,
+    incompatibility with recent GPUs or a crash, and is only intended to
+    be done for development or debugging.
+
+    Otherwise, *DIR* must be the absolute path to a directory that is
+    the root of an operating system installation (a "sysroot"). The
+    default is `/`.
 
 `--home` *DIR*
 :   Use *DIR* as the home directory. This implies `--unshare-home`.
 
 `--host-ld-preload` *MODULE*
-:   Add *MODULE* from the host system to `LD_PRELOAD` when executing
-    *COMMAND*. If *COMMAND* is run in a container, the path of the
-    *MODULE* will be adjusted appropriately.
+:   Deprecated equivalent of `--ld-preload`. Despite its name, the
+    *MODULE* has always been interpreted as relative to the current
+    execution environment, even if **pressure-vessel-wrap** is running
+    in a container.
 
 `--import-vulkan-layers`, `--no-import-vulkan-layers`
 :   If `--no-import-vulkan-layers` is specified, the Vulkan layers will
-    not be imported from the host system. Please note that some layers might
-    still be reachable from inside the container. E.g. layers located in
-    `~/.local/share/vulkan` if used in combination with `--share-home`.
+    not be imported from the host system.
     The default is `--import-vulkan-layers`.
 
 `--keep-game-overlay`, `--remove-game-overlay`
@@ -87,6 +104,20 @@ pressure-vessel-wrap - run programs in a bubblewrap container
     elements after `--` will be used as arguments for
     `pressure-vessel-launcher`. This option implies `--batch`.
 
+`--ld-audit` *MODULE*
+:   Add *MODULE* from the current execution environment to `LD_AUDIT`
+    when executing *COMMAND*. If *COMMAND* is run in a container, or if
+    **pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND*
+    will be run in a different container or on the host system, then the
+    path of the *MODULE* will be adjusted as necessary.
+
+`--ld-preload` *MODULE*
+:   Add *MODULE* from the current execution environment to `LD_PRELOAD`
+    when executing *COMMAND*. If *COMMAND* is run in a container, or if
+    **pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND*
+    will be run in a different container or on the host system, then the
+    path of the *MODULE* will be adjusted as necessary.
+
 `--only-prepare`
 :   Prepare the runtime, but do not actually run *COMMAND*.
     With `--copy-runtime`, the prepared runtime will appear in
@@ -141,7 +172,11 @@ pressure-vessel-wrap - run programs in a bubblewrap container
 `--runtime-id` *ID*
 :   Use *ID* to construct a directory into which the `--runtime-archive`
     will be unpacked, overriding an accompanying `-buildid.txt` file
-    if present.
+    if present. The *ID* must match the regular expression
+    `^[A-Za-z0-9_][-A-Za-z0-9_.]*$` (a non-empty sequence of ASCII
+    letters, digits, underscores, dots and dashes, starting with a
+    letter, digit or underscore). It will typically be in a format
+    similar to `0.20210301.0` or `soldier_0.20210301.0`.
 
     If the *ID* is the same as in a previous run of pressure-vessel-wrap,
     the content of the `--runtime-archive` will be assumed to be the
@@ -196,7 +231,7 @@ pressure-vessel-wrap - run programs in a bubblewrap container
     the `--shell` options.
 
 `--terminal=xterm`, `--xterm`
-:   Start an `xterm`(1) inside the container.
+:   Start an **xterm**(1) inside the container.
 
 `--terminate-timeout` *SECONDS*, `--terminate-idle-timeout` *SECONDS*
 :   Passed to **pressure-vessel-wrap**(1).
@@ -216,9 +251,11 @@ pressure-vessel-wrap - run programs in a bubblewrap container
 :   Print the version number and exit.
 
 `--with-host-graphics`, `--without-host-graphics`
-:   If using a `--runtime`, either import the host system's
-    graphics stack into it (default), or use the runtime's graphics
-    stack if any (likely to result in slow rendering or a crash).
+:   Deprecated form of `--graphics-provider`.
+    `--with-host-graphics` is equivalent to either
+    `--graphics-provider=/run/host` if it looks suitable, or
+    `--graphics-provider=/` if not.
+    `--without-host-graphics` is equivalent to `--graphics-provider=""`.
 
 # ENVIRONMENT
 
@@ -227,7 +264,7 @@ The following environment variables (among others) are read by
 
 `__EGL_VENDOR_LIBRARY_DIRS`, `__EGL_VENDOR_LIBRARY_FILENAMES`
 :   Used to locate EGL ICDs to be made available in the container
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `BWRAP` (path)
 :   Absolute path to **bwrap**(1).
@@ -240,13 +277,17 @@ The following environment variables (among others) are read by
 `DISPLAY`
 :   Used to locate the X11 display to make available in the container.
 
+`FLATPAK_ID`
+:   Used to locate the app-specific data directory when running in a
+    Flatpak environment.
+
 `LIBGL_DRIVERS_PATH`
 :   Used to locate Mesa DRI drivers to be made available in the container
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `LIBVA_DRIVERS_PATH`
 :   Used to locate VA-API drivers to be made available in the container
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `PRESSURE_VESSEL_BATCH` (boolean)
 :   If set to `1`, equivalent to `--batch`.
@@ -257,8 +298,8 @@ The following environment variables (among others) are read by
     If set to `0`, equivalent to `--no-copy-runtime`.
 
 `PRESSURE_VESSEL_COPY_RUNTIME_INTO` (path or empty string)
-:   If the string is empty, equivalent to `--no-copy-runtime`.
-    Otherwise, equivalent to
+:   If the string is empty, it is a deprecated equivalent of
+    `--no-copy-runtime`. Otherwise, it is a deprecated equivalent of
     `--copy-runtime --variable-dir="$PRESSURE_VESSEL_COPY_RUNTIME_INTO"`.
 
 `PRESSURE_VESSEL_FILESYSTEMS_RO` (`:`-separated list of paths)
@@ -284,12 +325,18 @@ The following environment variables (among others) are read by
 :   If set to `1`, equivalent to `--generate-locales`.
     If set to `0`, equivalent to `--no-generate-locales`.
 
+`PRESSURE_VESSEL_GRAPHICS_PROVIDER` (absolute path or empty string)
+:   Equivalent to `--graphics-provider="$PRESSURE_VESSEL_GRAPHICS_PROVIDER"`.
+
 `PRESSURE_VESSEL_HOME` (path)
 :   Equivalent to `--home="$PRESSURE_VESSEL_HOME"`.
 
 `PRESSURE_VESSEL_HOST_GRAPHICS` (boolean)
-:   If set to `1`, equivalent to `--with-host-graphics`.
-    If set to `0`, equivalent to `--without-host-graphics`.
+:   Deprecated form of `$PRESSURE_VESSEL_GRAPHICS_PROVIDER`.
+    If set to `1`, equivalent to either
+    `--graphics-provider=/run/host` if it looks suitable, or
+    `--graphics-provider=/` if not.
+    If set to `0`, equivalent to `--graphics-provider=""`.
 
 `PRESSURE_VESSEL_IMPORT_VULKAN_LAYERS` (boolean)
 :   If set to `1`, equivalent to `--import-vulkan-layers`.
@@ -310,9 +357,15 @@ The following environment variables (among others) are read by
 `PRESSURE_VESSEL_RUNTIME` (path, filename or empty string)
 :   Equivalent to `--runtime="$PRESSURE_VESSEL_RUNTIME"`.
 
+`PRESSURE_VESSEL_RUNTIME_ARCHIVE` (path, filename or empty string)
+:   Equivalent to `--runtime-archive="$PRESSURE_VESSEL_RUNTIME_ARCHIVE"`.
+
 `PRESSURE_VESSEL_RUNTIME_BASE` (path, filename or empty string)
 :   Equivalent to `--runtime-base="$PRESSURE_VESSEL_RUNTIME_BASE"`.
 
+`PRESSURE_VESSEL_RUNTIME_ID` (string matching `^[A-Za-z0-9_][-A-Za-z0-9_.]*$`)
+:   Equivalent to `--runtime-id="$PRESSURE_VESSEL_RUNTIME_ID"`.
+
 `PRESSURE_VESSEL_SHARE_HOME` (boolean)
 :   If set to `1`, equivalent to `--share-home`.
     If set to `0`, equivalent to `--unshare-home`.
@@ -400,33 +453,42 @@ The following environment variables (among others) are read by
 
 `STEAM_RUNTIME` (path)
 :   **pressure-vessel-wrap** refuses to run if this environment variable
-    is set. Use `pressure-vessel-unruntime`(1) instead.
+    is set. Use **pressure-vessel-unruntime**(1) instead.
 
 `SteamAppId` (integer)
 :   Equivalent to `--steam-app-id="$SteamAppId"`.
     Must only be set for the main processes that are running a game, not
     for any setup/installation steps that happen first.
+    `STEAM_COMPAT_APP_ID` is used with a higher priority.
 
 `VDPAU_DRIVER_PATH`
 :   Used to locate VDPAU drivers to be made available in the container
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `VK_ICD_FILENAMES`
 :   Used to locate Vulkan ICDs to be made available in the container
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
+
+`VK_LAYER_PATH`
+:   Used to locate Vulkan explicit layers
+    if `--runtime` and `--graphics-provider` are active.
 
 `WAYLAND_DISPLAY`
 :   Used to locate the Wayland display to make available in the container.
 
+`XDG_DATA_DIRS`
+:   Used to locate Vulkan ICDs and layers
+    if `--runtime` and `--graphics-provider` are active.
+
 The following environment variables are set by **pressure-vessel-wrap**(1).
 
 `__EGL_VENDOR_LIBRARY_DIRS`
-:   Unset if `--runtime` and `--with-host-graphics` are active,
+:   Unset if `--runtime` and `--graphics-provider` are active,
     to make sure `__EGL_VENDOR_LIBRARY_FILENAMES` will be used instead.
 
 `__EGL_VENDOR_LIBRARY_FILENAMES`
 :   Set to a search path for EGL ICDs
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `DBUS_SESSION_BUS_ADDRESS`, `DBUS_SYSTEM_BUS_ADDRESS`
 :   Set to paths in the container's private `/run` where the well-known
@@ -436,20 +498,23 @@ The following environment variables are set by **pressure-vessel-wrap**(1).
 :   Set to a value corresponding to the socket in the container's
     `/tmp/.X11-unix`.
 
+`LD_AUDIT`
+:   Set according to `--ld-audit`.
+
 `LD_LIBRARY_PATH`
 :   Set to a search path for shared libraries if `--runtime` is active.
 
 `LD_PRELOAD`
-:   Set according to `--host-ld-preload`, `--keep-game-overlay`,
+:   Set according to `--ld-preload`, `--keep-game-overlay`,
     `--remove-game-overlay`.
 
 `LIBGL_DRIVERS_PATH`
 :   Set to a search path for Mesa DRI drivers
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `LIBVA_DRIVERS_PATH`
 :   Set to a search path for VA-API drivers
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `PATH`
 :   Reset to a reasonable value if `--runtime` is active.
@@ -463,13 +528,23 @@ The following environment variables are set by **pressure-vessel-wrap**(1).
 `PWD`
 :   Set to the current working directory inside the container.
 
+`STEAM_RUNTIME`
+:   Set to `/` if using the Steam Runtime 1 'scout' runtime.
+
+`TERMINFO_DIRS`
+:   Set to the required search path for **terminfo**(5) files if
+    the `--runtime` appears to be Debian-based.
+
 `VDPAU_DRIVER_PATH`
 :   Set to a search path for VDPAU drivers
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
 
 `VK_ICD_FILENAMES`
 :   Set to a search path for Vulkan ICDs
-    if `--runtime` and `--with-host-graphics` are active.
+    if `--runtime` and `--graphics-provider` are active.
+
+`VK_LAYER_PATH`
+:   Unset if `--runtime` and `--graphics-provider` are active.
 
 `XAUTHORITY`
 :   Set to a value corresponding to a file in the container's
@@ -487,6 +562,10 @@ The following environment variables are set by **pressure-vessel-wrap**(1).
 :   Set to `$HOME/.local/share` (in the private home directory)
     if `--unshare-home` is active.
 
+`XDG_DATA_DIRS`
+:   Set to include a search path for Vulkan layers
+    if `--runtime` and `--graphics-provider` are active.
+
 `XDG_RUNTIME_DIR`
 :   Set to a new directory in the container's private `/run`
     if `--runtime` is active.
@@ -539,20 +618,19 @@ or significant Steam integration.
 
     $ steam steam://install/1070560     # Steam Linux Runtime 'scout'
     $ steam steam://install/302380      # Floating Point, a small free game
-    $ rm -fr ~/tmp/scout
-    $ mkdir -p ~/tmp/scout
-    $ tar \
-        -C ~/tmp/scout \
-        -xzvf ~/.steam/steamapps/common/SteamLinuxRuntime/com.valvesoftware.SteamRuntime.Platform-amd64,i386-scout-runtime.tar.gz
+    $ rm -fr ~/tmp/pressure-vessel-var
+    $ mkdir -p ~/tmp/pressure-vessel-var
+    $ archive=com.valvesoftware.SteamRuntime.Platform-amd64,i386-scout-runtime.tar.gz
     $ cd ~/.steam/steam/steamapps/common/"Floating Point"
     $ /path/to/pressure-vessel/bin/pressure-vessel-wrap \
-        --runtime ~/tmp/scout/files \
+        --runtime-archive ~/.steam/steamapps/common/SteamLinuxRuntime/"$archive" \
+        --variable-dir ~/tmp/pressure-vessel-var \
         --shell=instead \
         -- \
         "./Floating Point.x86"
 
-In the resulting `xterm`(1), you can explore the container interactively,
-then type `"$@"` to run the game itself.
+In the resulting **xterm**(1), you can explore the container interactively,
+then type `"$@"` (including the double quotes) to run the game itself.
 
 For more joined-up integration with Steam, install the Steam Linux Runtime
 (`steam://install/1070560`), and configure a native Linux game in Steam
diff --git a/pressure-vessel/wrap.c b/pressure-vessel/wrap.c
index 1a80817c2..5c15be373 100644
--- a/pressure-vessel/wrap.c
+++ b/pressure-vessel/wrap.c
@@ -1707,6 +1707,10 @@ main (int argc,
       /* Assume "bwrap" to exist in the host system and to be in its PATH */
       bwrap_executable = g_strdup ("bwrap");
 
+      /* Deliberately not documented: only people who are in a position
+       * to run their own modified versions of Flatpak and pressure-vessel
+       * should be using this, and those people can find this in the
+       * source code */
       if (g_getenv ("PRESSURE_VESSEL_FLATPAK_PR4018") != NULL)
         {
           g_warning ("Assuming your version of Flatpak contains unmerged "
@@ -1723,6 +1727,7 @@ main (int argc,
           flatpak_bwrap_add_arg (flatpak_subsandbox,
                                  "--bus-name=org.freedesktop.portal.Flatpak");
         }
+      /* Also deliberately not documented */
       else if (g_getenv ("PRESSURE_VESSEL_FLATPAK_SANDBOX_ESCAPE") != NULL)
         {
           g_warning ("Assuming permissions have been set to allow Steam "
-- 
GitLab