-
Simon McVittie authored
We are not going to be able to do this from within Flatpak, and it is unsuitable for running runtimes other than Steam Runtime 1 'scout', for which the LD_LIBRARY_PATH runtime mostly already works. If we need an automatic fallback to running on the host for scout games, we can do that better by running `pressure-vessel-wrap --test`. Signed-off-by:
Simon McVittie <smcv@collabora.com>
Simon McVittie authoredWe are not going to be able to do this from within Flatpak, and it is unsuitable for running runtimes other than Steam Runtime 1 'scout', for which the LD_LIBRARY_PATH runtime mostly already works. If we need an automatic fallback to running on the host for scout games, we can do that better by running `pressure-vessel-wrap --test`. Signed-off-by:
Simon McVittie <smcv@collabora.com>
title: pressure-vessel-wrap
section: 1
NAME
pressure-vessel-wrap - run programs in a bubblewrap container
SYNOPSIS
pressure-vessel-wrap [OPTIONS] [--] COMMAND [ARGUMENTS...]
pressure-vessel-wrap --test
pressure-vessel-wrap --version
DESCRIPTION
pressure-vessel-wrap runs COMMAND in a container, using bwrap(1).
OPTIONS
--batch
- Disable all interactivity and redirection: ignore
--shell
, all--shell-
options,--terminal
,--tty
and--xterm
. -
--copy-runtime-into
DIR - If a
--runtime
is active, copy it into a subdirectory of DIR, edit the copy in-place, and mount the copy read-only in the container, instead of setting up elaborate bind-mount structures. -
--env-if-host
VAR=VAL - If COMMAND is run with
/usr
from the host system, set environment variable VAR to VAL. If not, leave VAR unchanged. -
--filesystem
PATH - Share PATH from the host system with the container.
-
--freedesktop-app-id
ID - If using
--unshare-home
, use ~/.var/app/ID as the home directory. This is the same home directory that a Flatpak app for freedesktop.org app ID would use. -
--gc-runtimes
,--no-gc-runtimes
- If using
--copy-runtime-into
, 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).
The default is
--generate-locales
, overriding the default behaviour of pressure-vessel-wrap(1). -
--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. -
--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
. The default is--import-vulkan-layers
. -
--keep-game-overlay
,--remove-game-overlay
- If
--remove-game-overlay
is specified, remove the Steam Overlay from theLD_PRELOAD
. The default is--keep-game-overlay
. --launcher
- Instead of specifying a command with its arguments to execute, all the
elements after
--
will be used as arguments forpressure-vessel-launcher
. This option implies--batch
. --only-prepare
- Prepare the runtime, but do not actually run COMMAND.
With
--copy-runtime-into
, the prepared runtime will appear in a subdirectory of DIR. -
--pass-fd
FD - Pass the file descriptor FD (specified as a small positive integer) from the parent process to the COMMAND. The default is to only pass through file descriptors 0, 1 and 2 (stdin, stdout and stderr).
--runtime=
- Use the current execution environment's /usr to provide /usr in the container.
-
--runtime
PATH - Use PATH to provide /usr in the container.
If PATH/usr exists, PATH is assumed to be a complete sysroot
(containing bin/sh, usr/bin/env and many other OS files).
Otherwise, PATH is assumed to be a merged-/usr environment
(containing bin/sh, bin/env and many other OS files).
For example, the
files
subdirectory of a Flatpak runtime is a suitable value for PATH. -
--runtime-base
PATH - If
--runtime
specifies a relative path, look for it relative to PATH. -
--share-home
,--unshare-home
- If
--unshare-home
is specified, use the home directory given by--home
,--freedesktop-app-id
,--steam-app-id
or their corresponding environment variables, at least one of which must be provided.If--share-home
is specified, use the home directory from the current execution environment.The default is--share-home
, unless--home
or its corresponding environment variable is used. -
--share-pid
,--unshare-pid
- If
--unshare-pid
is specified, create a new process ID namespace. Note that this is known to interfere with IPC between Steam and its games. The default is--share-pid
. --shell=none
- Don't run an interactive shell. This is the default.
-
--shell=after
,--shell-after
- Run an interactive shell in the container after COMMAND exits.
In that shell, running
"$@"
will re-run COMMAND. -
--shell=fail
,--shell-fail
- The same as
--shell=after
, but do not run the shell if COMMAND exits with status 0. -
--shell=instead
,--shell-instead
- The same as
--shell=after
, but do not run COMMAND at all. -
--steam-app-id
N - Assume that we are running Steam app ID N, specified as an integer.
If using
--unshare-home
, use ~/.var/app/com.steampowered.AppN as the home directory. --terminal=none
- Disable features that would ordinarily use a terminal.
--terminal=auto
- Equivalent to
--terminal=xterm
if a--shell
option other thannone
is used, or--terminal=none
otherwise. -
--terminal=tty
,--tty
- Use the current execution environment's controlling tty for
the
--shell
options. -
--terminal=xterm
,--xterm
- Start an
xterm
(1) inside the container. -
--terminate-timeout
SECONDS,--terminate-idle-timeout
SECONDS - Passed to pressure-vessel-wrap(1).
--test
- Perform a smoke-test to determine whether pressure-vessel-wrap can work, and exit. Exit with status 0 if it can or 1 if it cannot.
--verbose
- Be more verbose.
--version
- 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).
ENVIRONMENT
The following environment variables (among others) are read by pressure-vessel-wrap(1).
-
__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. -
BWRAP
(path) - Absolute path to bwrap(1). The default is to try several likely locations.
-
DBUS_SESSION_BUS_ADDRESS
,DBUS_SYSTEM_BUS_ADDRESS
- Used to locate the well-known D-Bus session and system buses so that they can be made available in the container.
DISPLAY
- Used to locate the X11 display to make available in the container.
LIBGL_DRIVERS_PATH
- Used to locate Mesa DRI drivers to be made available in the container
if
--runtime
and--with-host-graphics
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. -
PRESSURE_VESSEL_BATCH
(boolean) - If set to
1
, equivalent to--batch
. If set to0
, no effect. -
PRESSURE_VESSEL_COPY_RUNTIME_INTO
(path or empty string) - Equivalent to
--copy-runtime-into="$PRESSURE_VESSEL_COPY_RUNTIME_INTO"
. -
PRESSURE_VESSEL_FILESYSTEMS_RO
(:
-separated list of paths) - Make these paths available read-only inside the container if they
exist, similar to
--filesystem
but read-only. For example, MangoHUD and vkBasalt users might usePRESSURE_VESSEL_FILESYSTEMS_RO="$MANGOHUD_CONFIGFILE:$VKBASALT_CONFIG_FILE"
if the configuration files are outside the home directory. -
PRESSURE_VESSEL_FILESYSTEMS_RW
(:
-separated list of paths) - Make these paths available read/write inside the container if they
exist, similar to
--filesystem
. -
PRESSURE_VESSEL_FDO_APP_ID
(string) - Equivalent to
--freedesktop-app-id="$PRESSURE_VESSEL_FDO_APP_ID"
. -
PRESSURE_VESSEL_GC_RUNTIMES
(boolean) - If set to
1
, equivalent to--gc-runtimes
. If set to0
, equivalent to--no-gc-runtimes
. -
PRESSURE_VESSEL_GENERATE_LOCALES
(boolean) - If set to
1
, equivalent to--generate-locales
. If set to0
, equivalent to--no-generate-locales
. -
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 to0
, equivalent to--without-host-graphics
. -
PRESSURE_VESSEL_IMPORT_VULKAN_LAYERS
(boolean) - If set to
1
, equivalent to--import-vulkan-layers
. If set to0
, equivalent to--no-import-vulkan-layers
. -
PRESSURE_VESSEL_REMOVE_GAME_OVERLAY
(boolean) - If set to
1
, equivalent to--remove-game-overlay
. If set to0
, equivalent to--keep-game-overlay
. -
PRESSURE_VESSEL_RUNTIME
(path, filename or empty string) - Equivalent to
--runtime="$PRESSURE_VESSEL_RUNTIME"
. -
PRESSURE_VESSEL_RUNTIME_BASE
(path, filename or empty string) - Equivalent to
--runtime-base="$PRESSURE_VESSEL_RUNTIME_BASE"
. -
PRESSURE_VESSEL_SHARE_HOME
(boolean) - If set to
1
, equivalent to--share-home
. If set to0
, equivalent to--unshare-home
. -
PRESSURE_VESSEL_SHARE_PID
(boolean) - If set to
1
, equivalent to--share-pid
. If set to0
, equivalent to--unshare-pid
. -
PRESSURE_VESSEL_SHELL
(none
,after
,fail
orinstead
) - Equivalent to
--shell="$PRESSURE_VESSEL_SHELL"
. -
PRESSURE_VESSEL_TERMINAL
(none
,auto
,tty
orxterm
) - Equivalent to
--terminal="$PRESSURE_VESSEL_TERMINAL"
. -
PRESSURE_VESSEL_VERBOSE
(boolean) - If set to
1
, equivalent to--verbose
. PULSE_CLIENTCONFIG
- Used to locate PulseAudio client configuration.
PULSE_SERVER
- Used to locate a PulseAudio server.
PWD
- Used to choose between logically equivalent names for the current working directory (see get_current_dir_name(3)).
-
STEAM_COMPAT_APP_ID
(integer) - Equivalent to
--steam-app-id="$STEAM_COMPAT_APP_ID"
. -
STEAM_COMPAT_APP_LIBRARY_PATH
(path) - Deprecated equivalent of
STEAM_COMPAT_MOUNTS
, except that it is a single path instead of being colon-delimited. -
STEAM_COMPAT_APP_LIBRARY_PATHS
(:
-separated list of paths) - Deprecated equivalent of
STEAM_COMPAT_MOUNTS
. -
STEAM_COMPAT_CLIENT_INSTALL_PATH
(path) - When used as a Steam compatibility tool, the absolute path to the Steam client installation directory. This is made available read/write in the container.
-
STEAM_COMPAT_DATA_PATH
(path) - When used as a Steam compatibility tool, the absolute path to the variable data directory used by Proton, if any. This is made available read/write in the container.
-
STEAM_COMPAT_INSTALL_PATH
(path) - Top-level directory containing the game itself, even if the current working directory is actually a subdirectory of this. This is made available read/write in the container.
-
STEAM_COMPAT_LIBRARY_PATHS
(:
-separated list of paths) - Colon-delimited list of paths to Steam Library directories containing the game, the compatibility tools if any, and any other resources that the game will need, such as DirectX installers. Each is currently made available read/write in the container.
-
STEAM_COMPAT_MOUNT_PATHS
(:
-separated list of paths) - Deprecated equivalent of
STEAM_COMPAT_MOUNTS
. -
STEAM_COMPAT_MOUNTS
(:
-separated list of paths) - Colon-delimited list of paths to additional directories that are to be made available read/write in the container.
-
STEAM_COMPAT_SESSION_ID
(integer) - (Not used yet, but should be.)
-
STEAM_COMPAT_SHADER_PATH
(path) - When used as a Steam compatibility tool, the absolute path to the variable data directory used for cached shaders, if any. This is made available read/write in the container.
-
STEAM_COMPAT_TOOL_PATH
(path) - Deprecated equivalent of
STEAM_COMPAT_TOOL_PATHS
, except that it is a single path instead of being colon-delimited. -
STEAM_COMPAT_TOOL_PATHS
(:
-separated list of paths) - Colon-delimited list of paths to Steam compatibility tools in use, such as Proton and the Steam Linux Runtime. They are currently made available read/write in the container.
-
STEAM_RUNTIME
(path) -
pressure-vessel-wrap refuses to run if this environment variable
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. VDPAU_DRIVER_PATH
- Used to locate VDPAU drivers to be made available in the container
if
--runtime
and--with-host-graphics
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. WAYLAND_DISPLAY
- Used to locate the Wayland display to make available in the container.
The following environment variables are set by pressure-vessel-wrap(1).
__EGL_VENDOR_LIBRARY_DIRS
- Unset if
--runtime
and--with-host-graphics
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. -
DBUS_SESSION_BUS_ADDRESS
,DBUS_SYSTEM_BUS_ADDRESS
- Set to paths in the container's private
/run
where the well-known D-Bus session and system buses are made available. DISPLAY
- Set to a value corresponding to the socket in the container's
/tmp/.X11-unix
. 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
,--remove-game-overlay
. LIBGL_DRIVERS_PATH
- Set to a search path for Mesa DRI drivers
if
--runtime
and--with-host-graphics
are active. LIBVA_DRIVERS_PATH
- Set to a search path for VA-API drivers
if
--runtime
and--with-host-graphics
are active. PATH
- Reset to a reasonable value if
--runtime
is active. PULSE_CLIENTCONFIG
- Set to the address of a PulseAudio client configuration file.
PULSE_SERVER
- Set to the address of a PulseAudio server socket.
PWD
- Set to the current working directory inside the container.
VDPAU_DRIVER_PATH
- Set to a search path for VDPAU drivers
if
--runtime
and--with-host-graphics
are active. VK_ICD_FILENAMES
- Set to a search path for Vulkan ICDs
if
--runtime
and--with-host-graphics
are active. XAUTHORITY
- Set to a value corresponding to a file in the container's
private
/run
. XDG_CACHE_HOME
- Set to
$HOME/.cache
(in the private home directory) if--unshare-home
is active. XDG_CONFIG_HOME
- Set to
$HOME/.config
(in the private home directory) if--unshare-home
is active. XDG_DATA_HOME
- Set to
$HOME/.local/share
(in the private home directory) if--unshare-home
is active. XDG_RUNTIME_DIR
- Set to a new directory in the container's private
/run
if--runtime
is active.
OUTPUT
The standard output from COMMAND is printed on standard output.
The standard error from COMMAND is printed on standard error. Diagnostic messages from pressure-vessel-wrap and pressure-vessel-wrap may also be printed on standard error.
SIGNALS
The pressure-vessel-wrap process replaces itself with a bwrap(1)
process. Fatal signals to the resulting bwrap(1) process will result
in SIGTERM
being received by the pressure-vessel-wrap process
that runs COMMAND inside the container.
EXIT STATUS
Nonzero (failure) exit statuses are subject to change, and might be changed to be more like env(1) in future.
- 0
- The COMMAND exited successfully with status 0
- Assorted nonzero statuses
- An error occurred while setting up the execution environment or starting the COMMAND
- Any value 1-255
- The COMMAND exited unsuccessfully with the status indicated
- 128 + n
- The COMMAND was killed by signal n (this is the same encoding used by bash(1), bwrap(1) and env(1))
- 255
- The COMMAND terminated in an unknown way (neither a normal exit nor terminated by a signal).
EXAMPLE
In this example we install and run a small free game that does not require communication or integration with Steam, without going via Steam to launch it. This will only work for simple games without DRM 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
$ cd ~/.steam/steam/steamapps/common/"Floating Point"
$ /path/to/pressure-vessel/bin/pressure-vessel-wrap \
--runtime ~/tmp/scout/files \
--shell=instead \
-- \
"./Floating Point.x86"
In the resulting xterm
(1), you can explore the container interactively,
then type "$@"
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
to be run with the Steam Linux Runtime
"compatibility tool".