README.md 9.68 KB
Newer Older
Simon McVittie's avatar
Simon McVittie committed
1
# scout SDK
Simon McVittie's avatar
Simon McVittie committed
2

3
This project provides container images for the Steam Runtime 1 'scout' SDK.
Simon McVittie's avatar
Simon McVittie committed
4

5
6
7
8
For general information about scout, please see the README in the
`steamrt/scout` branch of the `steamrt` package:
<https://gitlab.steamos.cloud/steamrt/steamrt/-/blob/steamrt/scout/README.md>.

9
## Developing software that runs in scout
10

11
12
13
14
15
16
17
18
19
20
21
For widest compatibility with Linux distributions, native Linux
games and tools shipped via Steam should be compiled in the `scout`
Steam Runtime environment.
This ensures that all of their dependencies except for glibc and the
graphics drivers are either provided with Steam (in the Steam Runtime),
or included with the game.
If the user has a newer version of one of the library that is included in the
Steam Runtime (which is likely), then the newer version will automatically
be selected at runtime.

We recommend compiling in an OCI-based container using a framework such
22
as Toolbx, Podman or Docker.
23
24
25
26
27
28
29
30
31
32
33
34
This ensures that only the libraries in the container are used for
compilation, as well as making builds more predictable and reproducible.
See [below](#oci) for more details.

Previous versions of scout, published before container frameworks had
become widespread, recommended using a
[chroot](https://en.wikipedia.org/wiki/Chroot)
environment via the `schroot` tool.
We no longer recommend this, because it is more difficult to set up on
non-Debian-derived machines and requires root privileges, but it is
still possible: see [below](#tar).

35
## OCI images for Docker and Podman <a name="oci"></a>
36
37

For Docker ([more information](doc/docker.md)):
38
39

    sudo docker pull registry.gitlab.steamos.cloud/steamrt/scout/sdk
40
    sudo docker pull registry.gitlab.steamos.cloud/steamrt/scout/sdk/i386
41

42
or for [Podman](https://podman.io/) ([more information](doc/podman.md)):
43
44
45
46

    podman pull registry.gitlab.steamos.cloud/steamrt/scout/sdk
    podman pull registry.gitlab.steamos.cloud/steamrt/scout/sdk/i386

47
or for [Toolbx](https://containertoolbx.org/)
Simon McVittie's avatar
Simon McVittie committed
48
([more information](doc/toolbx.md)):
49

50
    toolbox create -i registry.gitlab.steamos.cloud/steamrt/scout/sdk scout
51
52
    toolbox enter scout

53
    toolbox create -i registry.gitlab.steamos.cloud/steamrt/scout/sdk/i386 scout-i386
54
55
56
57
    toolbox enter scout-i386

Other OCI-compatible tools should also be compatible with these images.

58
59
### Versions

60
Two repositories are available:
61
62

* `registry.gitlab.steamos.cloud/steamrt/scout/sdk` is the 64-bit SDK.
63
64
65
    32-bit versions of some libraries are also available, but most 32-bit
    development libraries are not provided in this SDK. Use this to
    build 64-bit games.
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

* `registry.gitlab.steamos.cloud/steamrt/scout/sdk/i386` is the purely 32-bit SDK.
    64-bit libraries are not provided. Use this to build legacy 32-bit games.

Tags available for those repositories (can be specified after `:` when
using `docker pull`):

* `0.20200604.0` (etc.): Specific versions of the SDK. Use one of these
    if you need to "pin" to an older version for reproducible builds.
    These version numbers correspond exactly to
    <https://repo.steampowered.com/steamrt-images-scout/snapshots/0.20200604.0/> (etc.).

* `latest`, `latest-steam-client-general-availability`:
    An alias pointing to the SDK corresponding to the runtime that is included
    in the current General Availability version of the Steam client.
    If in doubt, build games against this.
    This should always match the version in
    <https://repo.steampowered.com/steamrt-images-scout/snapshots/latest-steam-client-general-availability/>.

* `beta`, `latest-steam-client-public-beta`:
    An alias pointing to the SDK corresponding to the runtime that is included
    in the current public beta version of the Steam client.
    This should always match the version in
    <https://repo.steampowered.com/steamrt-images-scout/snapshots/latest-steam-client-public-beta/>.
90
91
    Games built against this runtime will not always work with the
    General Availability version of the Steam client.
92

93
94
95
These OCI images were prepared using Docker, but should be equally suitable
for other OCI-compatible tools like `podman`.

96
## Tar archives for schroot and other non-OCI environments <a name="tar"></a>
97

98
99
We recommend Toolbx, Podman or Docker as the preferred way to develop
against scout.
100
101
102
103
However, for those who are more familiar with the `schroot` tool or other
non-OCI-based chroot and container environments, the `-sysroot.tar.gz`
archives available from
<https://repo.steampowered.com/steamrt-images-scout/snapshots/>
104
105
106
107
108
109
110
111
contain the same packages as the official OCI images.
[More information about schroot](doc/schroot.md)

If you prefer other chroot or container frameworks such as
`systemd-nspawn`, the same tar archives can be unpacked into a directory
and used with those.

The versions available are the same as for the [OCI images](#oci).
112

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
## Toolchains

### C/C++ compilers

The scout SDK contains multiple C/C++ compilers:

* gcc-4.6 and g++-4.6
* gcc-4.8 and g++-4.8 (default)
* gcc-5 and g++-5
* gcc-9 and g++-9
* clang-3.4 and clang++-3.4
* clang-3.6 and clang++-3.6
* clang-3.8 and clang++-3.8

For compatibility with older host operating systems, `gcc-9` and `g++-9`
always behave as though the `-static-libgcc` and `static-libstdc++`
options had been used.

All C++ code in your project should usually be built with the same compiler.
C-based external dependencies such as SDL and GLib are safe to use, but
passing a STL object such as `std::string` to C++-based libraries from
the Steam Runtime or the operating system (for example `libgnutlsxx` or
`libpcrecpp`) will not necessarily work and is best avoided, especially
if you are using `g++-9`.

Most build systems have a way to use a non-default compiler by specifying
its name, for example Autotools `./configure CC=gcc-5 CXX=g++-5 ...` and
CMake `cmake -DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5 ...`.

Meson users can use a command like `meson --native-file=gcc-5.txt ...`
for native compilers, or `meson --cross-file=gcc-5-m32.txt ...` to
compile legacy 32-bit games in the 64-bit container.
See `/usr/share/meson/native` and `/usr/share/meson/cross` in the container
for all the options available.

Alternatively, you can change the default by running the
`update-alternatives` command as root inside the container:

    (steamrt scout 0.20220119.0):~$ # for gcc-4.6
    (steamrt scout 0.20220119.0):~$ update-alternatives --auto gcc
    (steamrt scout 0.20220119.0):~$ update-alternatives --auto g++
    (steamrt scout 0.20220119.0):~$ update-alternatives --auto cpp-bin

    (steamrt scout 0.20220119.0):~$ # for gcc-4.8
    (steamrt scout 0.20220119.0):~$ update-alternatives --set gcc /usr/bin/gcc-4.8
    (steamrt scout 0.20220119.0):~$ update-alternatives --set g++ /usr/bin/g++-4.8
    (steamrt scout 0.20220119.0):~$ update-alternatives --set cpp-bin /usr/bin/cpp-4.8

    (steamrt scout 0.20220119.0):~$ # for clang-3.4
    (steamrt scout 0.20220119.0):~$ update-alternatives --set gcc /usr/bin/clang-3.4
    (steamrt scout 0.20220119.0):~$ update-alternatives --set g++ /usr/bin/clang++-3.4
    (steamrt scout 0.20220119.0):~$ update-alternatives --set cpp-bin /usr/bin/cpp-4.8

    (steamrt scout 0.20220119.0):~$ # for clang-3.6
    (steamrt scout 0.20220119.0):~$ update-alternatives --set gcc /usr/bin/clang-3.6
    (steamrt scout 0.20220119.0):~$ update-alternatives --set g++ /usr/bin/clang++-3.6
    (steamrt scout 0.20220119.0):~$ update-alternatives --set cpp-bin /usr/bin/cpp-4.8

### binutils

There are also two implementations of the `binutils` linker, assembler, etc.:

* binutils 2.22 (default)
* binutils 2.30

To use binutils 2.30, prepend `/usr/lib/binutils-2.30/bin` to the `PATH`:

    (steamrt scout 0.20220119.0):~$ export PATH="/usr/lib/binutils-2.30/bin:$PATH"

or run individual tools using names like `ld-2.30` and `objcopy-2.30`.

The `gcc-9` and `g++-9` compilers automatically use binutils 2.30.
Older compilers use binutils 2.22 by default.

187
188
189
190
191
192
193
194
195
196
197
198
199
## apt packages

scout is based on, and broadly compatible with, Ubuntu 12.04 'precise':
if additional development tools are required, you can install them
from the Ubuntu 12.04 apt repositories. However, please be careful
not to introduce dependencies on packages that are not included in the
runtime.

Additional development tools can also be installed from precise-backports,
from third-party apt repositories compatible with Ubuntu 12.04, or from
source code. Again, please be careful not to introduce dependencies on
packages that are not included in the runtime.

200
201
## Source code

202
Source code for all the packages that go into the OCI image can be found
203
204
in the appropriate subdirectory of
https://repo.steampowered.com/steamrt-images-scout/snapshots/
205
(look in the `sources/` directory).
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

The OCI image is built using
[flatdeb-steam](https://gitlab.steamos.cloud/steamrt/flatdeb-steam).
The choice of packages to include in the runtime is partly in the
flatdeb configuration, but mostly controlled by
[the steamrt/scout branch of the steamrt source package](https://gitlab.steamos.cloud/steamrt/steamrt/-/tree/steamrt/scout).

The traditional `LD_LIBRARY_PATH` image is built using
[steam-runtime](https://github.com/ValveSoftware/steam-runtime).
Again, the choice of packages to include in the runtime is partly
in `build-runtime.py`, but mostly controlled by
[the steamrt/scout branch of the steamrt source package](https://gitlab.steamos.cloud/steamrt/steamrt/-/tree/steamrt/scout).

Other relevant projects include:

* [steam-runtime-tools](https://gitlab.steamos.cloud/steamrt/steam-runtime-tools),
  which includes the `pressure-vessel` container-runner tool, the
  `steam-runtime-system-info` diagnostic tool, and some library code that
  they share
* [SteamLinuxRuntime](https://gitlab.steamos.cloud/steamrt/steamlinuxruntime),
  which builds the Steampipe depot used to integrate this as a
227
  container runtime in the SteamPlay compatibility tool mechanism