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
============

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

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

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

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

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

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

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

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

For Docker users:

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

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

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