Skip to content
Snippets Groups Projects
After you've reviewed these contribution guidelines, you'll be all set to contribute to this project.
CONTRIBUTING.md 12.52 KiB

Contributing to steam-runtime-tools

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 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 by steam-runtime-tools 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 steam-runtime-tools 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 steam-runtime-tools, please include a Signed-off-by message in your commits to indicate acceptance of the Developer's Certificate of Origin terms.

Compiling steam-runtime-tools

steam-runtime-tools uses the Meson build system. However, because Steam supports both 64-bit x86_64 (amd64) and 32-bit IA32 (x86, i386), to get a fully functional set of diagnostic tools or a fully functional version of pressure-vessel that will work in all situations, it is necessary to build steam-runtime-tools at least twice: once for 64-bit x86_64, and once for 32-bit IA32. The 32-bit build can disable pressure-vessel, but must include at least the "helpers" that are used to identify and inspect 32-bit libraries. Building for multiple architectures is outside the scope of the Meson build system, so we have to do at least two separate Meson builds and combine them.

Also, to make sure that pressure-vessel and the diagnostic tools work with all the operating systems and runtime environments we support, production builds of steam-runtime-tools need to be compiled in a Steam Runtime 1 'scout' environment.

The script build-aux/many-builds.py can be used to compile and test steam-runtime-tools in a convenient way. Please see build-aux/many-builds.md for details.

Production builds are done by Gitlab-CI, which is also run to test proposed branches. This does not use many-builds.py, because it needs to run separate parts of the build in separate containers, but the general principle is the same.

The diagnostic tools provided by steam-runtime-tools are shipped in Steam Runtime releases via a .deb package. We usually build .deb packages via the deb-build-snapshot tool, with a command-line like this:

LC_ALL=C.UTF-8 \
deb-build-snapshot \
--upstream \
--source \
--download ~/tmp/build-area \
--deb-schroot steamrt_scout_amd64 \
--install-all \
build-vm

where build-vm is a virtual machine with steam-runtime-tools' dependencies and a steamrt_scout_amd64 chroot, that can be accessed via ssh build-vm. If the dependencies and chroot are available on your development system, use localhost, which will make deb-build-snapshot do the build locally instead of using ssh.

Design notes

  • ABIs/architectures are identified by their Debian-style multiarch tuple, which is a GNU tuple (x86_64-linux-gnu, arm-linux-gnueabi) with its CPU part normalized to the oldest/most compatible in a CPU family (so i386, not i686, and arm, not armv5tel). Helper subprocesses are prefixed with the multiarch tuple, in the same style used for cross-compilers and cross-tools (x86_64-linux-gnu-inspect-library, i386-linux-gnu-wflinfo).

  • Be careful when adding dependencies to the main library. GLib 2.32 (Ubuntu 12.04 'precise', SteamRT 1 'scout') can be relied on. JSON-GLib is OK (we have a backport in SteamRT 1 'scout'). Anything else is probably bad news.

    • In particular, try not to pull in C++ ABIs, because incompatible C++ ABIs are one of the things that steam-runtime-tools should be able to detect and diagnose. We use C ABIs because they are the lowest common denominator for compatibility between distros.
  • Any checks that can reasonably crash should be in a subprocess. This means that if they crash, they don't bring down the entire Steam client with them.

  • Any checks that need to look at more than one ABI (32- and 64-bit) must be in a subprocess, so that the same process can run both.

  • The inspect-library helper should not have non-libc dependencies - not even GLib. Other helpers may have library dependencies if it is useful to do so.

  • For system information and checks, new functionality should be accessed through SrtSystemInfo so that its cache lifetime can be managed. Separate access points like srt_check_library_presence() will be kept until the next ABI break, but don't add new ones.

Automated tests

New code should have test coverage where feasible. It's OK to have some "design for test" in the APIs to facilitate this, such as srt_system_info_set_environ().

If a helper can't be unit-tested (for example because it needs working OpenGL), we'll understand. The code that calls into the helper should still be unit-tested, by using a mock implementation of the helper.