Common tasks
============

Adding a library to the SDK
---------------------------

Suppose you want to add `libfoo-dev` to the SDK.

Install `libfoo-dev` in a `soldier` container/chroot, and check what other
packages it pulls in, and where they came from (`soldier` or `buster`).
Check that those packages have acceptable licensing terms.

Check whether you can install `libfoo-dev:amd64` and `libfoo-dev:i386`
in a `soldier` container/chroot without needing to remove anything else.

Edit `debian/control` and add `libfoo-dev` to an appropriate `Depends`
list. If you can co-install the amd64 and i386 versions of it, add it
to `steamrt-libdevel`. If not, add it to `steamrt-libdevel-non-multiarch`.

If you want to be able to ship games that use this library unconditionally,
you'll need to provide the library in the runtime (see below).

Adding a library to the Platform
--------------------------------

Suppose you want to add `libFoo.so.1` to the runtime.

Install `libfoo1` (or whatever is the right package name) in a `soldier`
container/chroot, and check what other packages it pulls in, and where
they came from (`soldier` or `buster`).  Check that those packages have
acceptable licensing terms.

Check whether you can install `libfoo1:amd64` and `libfoo1:i386`
in a `soldier` container/chroot without needing to remove anything else.
If you can't, improve the packaging until you can (install to Multi-Arch
directories and set `Multi-Arch: same`). We don't support libraries that
are not multi-arch co-installable.

Edit `abi/steam-runtime-abi.yaml` and add the new library and each of its
(recursive) dependencies. If the name of the package matches the SONAME,
you can just add it to the list as a string, similar to `libX11.so.6`. If
not, you'll have to add it as a dict that contains a `deb:` key, similar
to `libz.so.1` containing `deb: zlib1g`.

After editing `abi/steam-runtime-abi.yaml`, regenerate
the `abi/expectations` directory by running
`abi/maintainer-generate-expectations.py` in a `soldier` chroot or container.

If you want to be able to compile against this library without downloading
extra packages, you'll need to provide the library in the SDK (see above).

Testing a new soldier runtime
-----------------------------

### Within Steam

Build the runtime using CI or `flatdeb-steam`.
Various artifacts are produced, but the ones we need here are
`com.valvesoftware.SteamRuntime.Platform-amd64,i386-soldier-runtime.tar.gz`
and optionally `steam-container-runtime.tar.gz`.

If you have downloaded `steam-container-runtime.tar.gz`, you can replace
the entire `steamapps/common/SteamLinuxRuntime_soldier` directory:

```
$ common=/path/to/steamapps/common
$ rm -fr "$common"/SteamLinuxRuntime_soldier/*
$ tar --strip-components=2 \
    -C "$common/SteamLinuxRuntime_soldier" \
    -xf steam-container-runtime.tar.gz \
    steam-container-runtime/depot
$ tar -C "$common"/SteamLinuxRuntime_soldier/soldier_platform_* \
    -xf com.valvesoftware.SteamRuntime.Platform-amd64,i386-soldier-runtime.tar.gz
```

This will replace everything in the SLR directory, including pressure-vessel.

Or if you only downloaded
`com.valvesoftware.SteamRuntime.Platform-amd64,i386-soldier-runtime.tar.gz`,
you can modify an existing copy of SLR to use it, keeping the existing
pressure-vessel and helper scripts:

```
$ common=/path/to/steamapps/common
$ rm -fr "$common"/SteamLinuxRuntime_soldier/soldier_test
$ mkdir "$common"/SteamLinuxRuntime_soldier/soldier_test
$ tar -C "$common"/SteamLinuxRuntime_soldier/soldier_test \
    -xf com.valvesoftware.SteamRuntime.Platform-amd64,i386-soldier-runtime.tar.gz
$ sed -i -e 's,^dir=,dir=soldier_test,' "$common"/SteamLinuxRuntime_soldier/run
$ sed -i -e 's,^dir=,dir=soldier_test,' "$common"/SteamLinuxRuntime_soldier/run-in-soldier
```

You can use multiple subdirectories of `SteamLinuxRuntime_soldier`
to keep different runtime versions available, but for compatibility
with old versions of the runtime, their names cannot start with either
`soldier_0.` or `soldier_before_`.  A name starting with `soldier_test`
or `soldier_platform` is recommended.

There are currently three interesting use-cases for soldier:

* Configure a Windows game to use the `Proton Experimental`
    compatibility tool, or Proton version 5.13 or newer (or run a
    Windows-only game that uses one of these Proton versions by default).
    These Proton versions run in a `soldier` container.

* Configure a native Linux game to use the `Steam Linux Runtime`
    compatibility tool. This runs `scout` games in a `soldier` container,
    with a few libraries from `scout` and the rest from `soldier`.

* Run a native Linux game that has done its own unsupported workarounds to
    find and use a `soldier` runtime. Retroarch is currently the only
    known example.

In both cases, it can be useful to launch Steam with the environment
variable `PRESSURE_VESSEL_SHELL=instead`, or set the game's launch options
to `PRESSURE_VESSEL_SHELL=instead %command%`. This provides an easy way to
confirm that you are using the runtime you think you are using: its version
number appears in the shell prompt. Type `"$@"` to run the game.

### Outside Steam

Build the runtime using CI or `flatdeb-steam`, as before.
Various artifacts are produced, but the only one we need here is
`com.valvesoftware.SteamRuntime.Platform-amd64,i386-soldier-runtime.tar.gz`.

Unpack it into an empty directory, for example `~/tmp/soldier`, so that
you have `~/tmp/soldier/metadata` and `~/tmp/soldier/files/bin/env`.
Create a directory on the same filesystem that can be used for temporary
copies and logs, for example `~/tmp/pressure-vessel-var`.

Download a pressure-vessel relocatable release from
<https://repo.steampowered.com/pressure-vessel/snapshots/> and unpack it
into a directory, or use the one included in `SteamLinuxRuntime_soldier`,
or build your own.

Then run a command like:

```
$ .../pressure-vessel/bin/pressure-vessel-wrap \
    --variable-dir ~/tmp/pressure-vessel-var \
    --copy-runtime \
    --runtime ~/tmp/soldier \
    -- \
    xterm
```

Testing a new soldier SDK
-------------------------

Build the runtime using CI or `flatdeb-steam`. Various artifacts are
produced, but the ones we'll need here are
`com.valvesoftware.SteamRuntime.Sdk-amd64,i386-soldier-sysroot.tar.gz`
and `com.valvesoftware.SteamRuntime.Sdk-amd64,i386-soldier-sysroot.Dockerfile`.
Download them into a new, empty directory and `cd` into that directory.

For Docker users:

    $ sudo docker build -t steamrt_soldier_amd64:latest -f *.Dockerfile .

Then you can use the `steamrt_soldier_amd64` Docker image for builds.

For Podman users: it's the same as Docker, but use `podman build` instead
of `sudo docker build`.

For `schroot` users:

    $ /path/to/steam-runtime/setup_chroot.sh --suite=soldier --amd64 --tarball *-sysroot.tar.gz
