Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/valvesoftware/proton

Compatibility tool for Steam Play based on Wine and additional components
https://github.com/valvesoftware/proton

proton

Last synced: 5 months ago
JSON representation

Compatibility tool for Steam Play based on Wine and additional components

Awesome Lists containing this project

README 

          
Introduction

------------



**Proton** is a tool for use with the Steam client which allows games which are

exclusive to Windows to run on the Linux operating system. It uses Wine to

facilitate this.



**Most users should use Proton provided by the Steam Client itself.** See

[this Steam Community post][steam-play-introduction] for more details.



The source code is provided to enable advanced users the ability to alter

Proton. For example, some users may wish to use a different version of Wine

with a particular title.



**The changelog** is available on [our wiki][changelog].



[steam-play-introduction]: https://steamcommunity.com/games/221410/announcements/detail/1696055855739350561

[changelog]: https://github.com/ValveSoftware/Proton/wiki/Changelog



Obtaining Proton sources

------------------------



Acquire Proton's source by cloning 

and checking out the branch you desire.



You can clone the latest Proton to your system with this command:



```bash

git clone --recurse-submodules https://github.com/ValveSoftware/Proton.git proton

```



Be sure to update submodules when switching between branches:



```bash

git checkout experimental_6.3

git submodule update --init --recursive

```



If you want to change any subcomponent, now is the time to do so. For

example, if you wish to make changes to Wine, you would apply them to the

`wine/` directory.



Building Proton

---------------



Most of Proton builds inside the Proton SDK container with very few

dependencies on the host side.



## Preparing the build environment



You need either a Docker or a Podman setup. We highly recommend [the rootless

Podman setup][rootless-podman]. Please refer to your distribution's

documentation for setup instructions (e.g. Arch [Podman][arch-podman] /

[Docker][arch-docker], Debian [Podman][debian-podman] /

[Docker][debian-docker]).



[rootless-podman]: https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md

[arch-podman]: https://wiki.archlinux.org/title/Podman

[arch-docker]: https://wiki.archlinux.org/title/Docker

[debian-podman]: https://wiki.debian.org/Podman

[debian-docker]: https://wiki.debian.org/Docker



## The Easy Way



We provide a top-level Makefile which will execute most of the build commands

for you.



After checking out the repository and updating its submodules, assuming that

you have a working Docker or Podman setup, you can build and install Proton

with a simple:



```bash

make install

```



If your build system is missing dependencies, it will fail quickly with a clear

error message.



After the build finishes, you may need to restart the Steam client to see the

new Proton tool. The tool's name in the Steam client will be based on the

currently checked out branch of Proton. You can override this name using the

`build_name` variable.



See `make help` for other build targets and options.



## Manual building



### Configuring the build



```bash

mkdir ../build && cd ../build

../proton/configure.sh --enable-ccache --build-name=my_build

```



Running `configure.sh` will create a `Makefile` allowing you to build Proton.

The scripts checks if containers are functional and prompt you if any

host-side dependencies are missing. You should run the command from a

directory created specifically for your build.



The configuration script tries to discover a working Docker or Podman setup

to use, but you can force a compatible engine with

`--container-engine=`.



You can enable ccache with `--enable-cache` flag. This will mount your

`$CCACHE_DIR` or `$HOME/.ccache` inside the container.



`--proton-sdk-image=registry.gitlab.steamos.cloud/proton/soldier/sdk:`

can be used to build with a custom version of the Proton SDK images.



Check `--help` for other configuration options.



NOTE: If **SELinux** is in use, the Proton build container may fail to access

your user's files. This is caused by [SELinux's filesystem

labels][selinux-labels]. You may pass the `--relabel-volumes` switch to

configure to cause the [container engine to relabel its

bind-mounts][bind-mounts] and allow access to those files from within the

container. This can be dangerous when used with system directories. Proceed

with caution and refer your container engine's manual.



[selinux-labels]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/security-enhanced_linux/sect-security-enhanced_linux-working_with_selinux-selinux_contexts_labeling_files

[bind-mounts]: https://docs.docker.com/storage/bind-mounts/



### Building



```

make

```



**Important make targets:**



`make install` - install Proton into your user's Steam directory, see the [install Proton

locally](#install-proton-locally) section for details.



`make redist` - create a redistribute build (`redist/`) that can be copied to

`~/.steam/root/compatibilitytools.d/`.



`make deploy` - create a deployment build (`deploy/`). This is what we use to

deploy Proton to Steam users via Steamworks.



`make module= module` - build both 32- and 64-bit versions of the

specified wine module. This allows rapid iteration on one module. This target

is only useful after building Proton.



`make dxvk` / `make vkd3d-proton` - rebuild DXVK / vkd3d-proton.



### Debug Builds



To prevent symbol stripping add `UNSTRIPPED_BUILD=1` to the `make`

invocation. This should be used only with a clean build directory.



E.g.:



```

mkdir ../debug-proton-build && cd ../debug-proton-build

../proton/configure.sh --enable-ccache --build-name=debug_build

make UNSTRIPPED_BUILD=1 install

```



Install Proton locally

----------------------



Steam ships with several versions of Proton, which games will use by default or

that you can select in Steam Settings' Steam Play page. Steam also supports

running games with local builds of Proton, which you can install on your

machine.



To install a local build of Proton into Steam, make a new directory in

`~/.steam/root/compatibilitytools.d/` with a tool name of your choosing and

place the directory containing your redistributable build under that path.



The `make install` target will perform this task for you, installing the

Proton build into the Steam folder for the current user. You will have to

restart the Steam client for it to pick up on a new tool.



A correct local tool installation should look similar to this:



```

compatibilitytools.d/my_proton/

├── compatibilitytool.vdf

├── filelock.py

├── LICENSE

├── proton

├── proton_dist.tar

├── toolmanifest.vdf

├── user_settings.sample.py

└── version

```



To enable your local build in Steam, go to the Steam Play section of the

Settings window. If the build was correctly installed, you should see

"proton-localbuild" in the drop-down list of compatibility tools.



Each component of this software is used under the terms of their licenses.

See the `LICENSE` files here, as well as the `LICENSE`, `COPYING`, etc files

in each submodule and directory for details. If you distribute a built

version of Proton to other users, you must adhere to the terms of these

licenses.



Debugging

---------



Proton builds have their symbols stripped by default. You can switch to

"debug" beta branch in Steam (search for Proton in your library,

Properties... -> BETAS -> select "debug") or build without stripping (see

[Debug Builds section](#debug-builds)).



The symbols are provided through the accompanying `.debug` files which may

need to be explicitly loaded by the debugging tools. For GDB there's a helper

script `wine/tools/gdbinit.py` (source it) that provides `load-symbol-files`

(or `lsf` for short) command which loads the symbols for all the mapped files.



For tips on debugging see [docs/DEBUGGING-LINUX.md](docs/DEBUGGING-LINUX.md)

and [docs/DEBUGGING-WINDOWS.md](docs/DEBUGGING-WINDOWS.md).



`compile_commands.json`

-----------------------



For use with [clangd](https://clangd.llvm.org/) LSP server and similar tooling.



Projects built using cmake or meson (e.g. vkd3d-proton) automatically come with

`compile_commands.json`. For autotools (e.g. wine) you have to [configure the

build](#configuring-the-build) with `--enable-bear` that uses

[bear](https://github.com/rizsotto/Bear) to create the compilation database.

It's not on by default as it make the build slightly slower.



The build system collects all the created compile_commands.json files in a

build subdirectory named `compile_commands/`.



The paths are translated to point to the real source (i.e. not the rsynced

copy). It still may depend on build directory for things like auto-generated

`config.h` though and for wine it may be beneficial to run `tools/make_requests`

in you source directories as those changes are not committed.



You can then configure your editor to use that file for clangd in a few ways:



1) directly - some editors/plugins allow you to specify the path to `compile_commands.json`

2) via `.clangd` file, e.g.

```bash

cd src/proton/wine/

cat > .clangd <