Contributing to steamrt
=======================

Issue tracking
--------------

Our main bug tracking system for the whole Steam Runtime is
<https://github.com/ValveSoftware/steam-runtime/issues>. Before reporting
an issue, please take a look at the
[bug reporting information](https://github.com/ValveSoftware/steam-runtime/blob/HEAD/doc/reporting-steamlinuxruntime-bugs.md)
to make sure your issue report contains all the information we need.

The issue tracker on our Gitlab installation, `gitlab.steamos.cloud`, is
primarily used internally by Steam Runtime developers to track issues for
which we already know the technical details of what is happening.

Contributing code
-----------------

At the moment our Gitlab installation, `gitlab.steamos.cloud`, is not
set up to receive merge requests from third-party contributors. However,
git is a distributed version control system, so it is possible to push a
clone of the steamrt git repository to some other git hosting platform
(such as Github or `gitlab.com`) and send a link to a proposed branch
via an issue report.

If you want to contribute code to steamrt, please include a
`Signed-off-by` message in your commits to indicate acceptance of the
[Developer's Certificate of Origin](https://developercertificate.org/)
terms.

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

Updating shared library expectations
------------------------------------

1. Make the source tree available in a steamrt4 chroot or container
2. In the container: `./abi/maintainer-generate-expectations.py`
3. Check and commit the generated files in `abi/expectations/`

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

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

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

Check whether you can install `libfoo-dev:amd64` and `libfoo-dev:i386`
in this branch's 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 and it is
likely to be desirable to do so, 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 this branch's
container/chroot, and check what other packages it pulls in, and where
they came from (`steamrt4` or `trixie`).  Check that those packages have
acceptable licensing terms.

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`.

For libraries where multiarch co-installation is desirable,
check whether you can install `libfoo1:amd64` and `libfoo1:i386`
in this branch's 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`).
Also set `multiarch: true` for the library's entry in
`abi/steam-runtime-abi.yaml`.

After editing `abi/steam-runtime-abi.yaml`, regenerate
the `abi/expectations` directory by running
`abi/maintainer-generate-expectations.py` in this branch's chroot or container,
the same as in section "Updating shared library expectations".

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 container runtime
-------------------------------

### Within Steam

This branch of the container runtime is not yet supported by Steam.

### 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-steamrt4-runtime.tar.gz`.

Unpack it into an empty directory, for example `~/tmp/steamrt4`, so that
you have `~/tmp/steamrt4/metadata` and `~/tmp/steamrt4/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_4`,
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/steamrt4 \
    -- \
    xterm
```

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

For Docker users:

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

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