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

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

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

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

Check whether you can install `libfoo-dev:amd64` and `libfoo-dev:i386`
in a `heavy` 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 `heavy`
container/chroot, and check what other packages it pulls in, and where
they came from (`heavy` or `jessie`).  Check that those packages have
acceptable licensing terms.

Check whether you can install `libfoo1:amd64` and `libfoo1:i386`
in a `heavy` 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 `heavy` 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 heavy runtime
---------------------------

Build the runtime using CI or the `build-runtime.py` script.
Various artifacts are produced, but the one we need here is
`steam-runtime-heavy.tar.xz`.

Unpack that tarball to get a `steam-runtime-heavy` directory in a temporary
location, for example `~/tmp/steam-runtime-heavy`, so that you have files
that include `~/tmp/steam-runtime-heavy/run.sh`.

Then run Steam with the `STEAM_RUNTIME_HEAVY`
environment variable set to the absolute path to the heavy runtime,
for example:

    $ export STEAM_RUNTIME_HEAVY="$HOME/tmp/steam-runtime-heavy"
    $ steam

It should log:

    steamwebhelper.sh[12345]: Runtime for steamwebhelper: overridden to /home/me/tmp/steam-runtime-heavy

Alternatively, you can overwrite the following files in
`~/.steam/root/ubuntu12_64/` with the versions from the new runtime,
then run Steam with the unsupported parameter that makes it skip the
file integrity check that would normally re-download them (deliberately
not documented here):

* `steam-runtime-heavy.sh`
* `steam-runtime-heavy.tar.xz`
* `steam-runtime-heavy.tar.xz.checksum`
* `steam-runtime-heavy.version.txt`

To test without using Steam, you must run the `setup.sh` script at least
once, and then wrap programs in the `run.sh` script, for example:

    $ ~/tmp/steam-runtime-heavy/setup.sh
    $ ~/tmp/steam-runtime-heavy/run.sh -- gdb steamwebhelper

Testing a new heavy 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-heavy-sysroot.tar.gz`
and `com.valvesoftware.SteamRuntime.Sdk-amd64,i386-heavy-sysroot.Dockerfile`.
Download them into a new, empty directory and `cd` into that directory.

For Docker users:

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

Then you can use the `steamrt_heavy_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=heavy --amd64 --tarball *-sysroot.tar.gz

Committing a new heavy runtime to Steam
---------------------------------------

The following files in `ubuntu12_64/` need to be overwritten with the
versions from the new runtime:

* `steam-runtime-heavy.sh`
* `steam-runtime-heavy.tar.xz`
* `steam-runtime-heavy.tar.xz.checksum`
* `steam-runtime-heavy.version.txt`

Please remember to trigger the `heavy/record-steam-main-branch` Jenkins job
afterwards, setting `CI_SOURCE_VERSION` to the version number of the new
runtime.
