archives/steamos-manager
archives/steamos-manager
2
0
Fork 1
mirror of https://gitlab.steamos.cloud/holo/steamos-manager.git synced 2025-07-05 06:00:30 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge README.md and HACKING.md and fix up some rewrite issues

Browse source
This commit is contained in:
Vicki Pfau 2024-05-17 17:33:39 -07:00
parent 56323bcf21
commit 6e51d1556b
2 changed files with 61 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

30
HACKING.md
View file

@ -1,30 +0,0 @@
This project is written in [Rust](https://www.rust-lang.org/). For any
unfamiliar with how that works the following should help:
# Building
To build you'll want a Rust implementation for your laptop/device you are testing on.
The [Arch wiki article](https://wiki.archlinux.org/title/rust) has some good
guidelines for getting that sorted, but mostly boils down to installing
`rustup` from the `rustup` package (if you're on Arch) and running `rustup
default stable` to get an initial toolchain.
Once you have that and `cargo` is in your path, to build the project you can
use `cargo build`. To run tests you can use `cargo test`.
Note that Arch also provides the `rust` package for a system-managed Rust
installation, which is also sufficient for development on this project.
# Developing
As far as IDEs go, Visual Studio Code works pretty well for giving errors about
things you are changing and has plugins for vim mode, etc. if you are used to
those keybindings. Most/all IDEs that work with language servers should do that
fine though.
For VS Code, these extensions help: `rust` and `rust-analyzer`.
Before committing code, please run `cargo fmt` to make sure that your code
matches the preferred code style, and `cargo clippy` can help with common
mistakes and idiomatic code.

97
README.md
View file

@ -1,10 +1,9 @@
# SteamOS Manager
SteamOS Manager is a system daemon that aims to abstract steam's
interactions with the operating system. The goal is to have a standardized
interface so that SteamOS specific features in the Steam client, e.g. TDP
management, can be exposed in any linux distro that provides an implementation
of this DBus API.
SteamOS Manager is a system daemon that aims to abstract Steam's interactions
with the operating system. The goal is to have a standardized interface so that
SteamOS specific features in the Steam client, e.g. TDP management, can be
exposed in any linux distro that provides an implementation of this DBus API.
The interface may be fully or partially implemented. The Steam client will
check which which features are available at startup and restrict the settings
@ -16,29 +15,61 @@ Some of the features that SteamOS Manager enables include:
- BIOS/Dock updates
- Storage device maintenance tasks
- External storage device formatting
* Steam geneally performs device enumeration via UDisks2, but formatting happens via SteamOSManager
- Steam geneally performs device enumeration via UDisks2, but formatting
happens via SteamOSManager
For a full list of features please refer to the [interface specification](https://gitlab.steamos.cloud/holo/steamos-manager/-/blob/master/com.steampowered.SteamOSManager1.xml).
Other notable dbus interfaces used by the Steam Client include:
* org.freedesktop.UDisks2
* org.freedesktop.portal.desktop
* org.freedesktop.login1
* org.bluez
- org.freedesktop.UDisks2
- org.freedesktop.portal.desktop
- org.freedesktop.login1
- org.bluez
# Building
This project is written in Rust, so you will need an implementation for the
device you're using for building. The [Arch wiki
article](https://wiki.archlinux.org/title/rust) has some good guidelines for
this, but this mostly consists of installing `rustup` from the
`rustup` package (if you're on Arch) and running `rustup default stable` to get
an initial toolchain, or just installing the regular `rust` package for a
system-managed installation.
Once you have that and `cargo` is in your path, to build the project you can
use `cargo build`.
# Developing
As far as IDEs go, Visual Studio Code works pretty well for giving errors about
things you are changing and has plugins for vim mode, etc. if you are used to
those keybindings. Most/all IDEs that work with language servers should do that
fine though.
For VS Code, these extensions help: `rust` and `rust-analyzer`.
Before committing code, please run `cargo fmt` to make sure that your code
matches the preferred code style, and `cargo clippy` can help with common
mistakes and idiomatic code.
To perform tests, run `cargo test`. This will compile a test configuration of
the project and run the built-in test suite.
## Interface compatibility notes
SteamOS Manager and the Steam client are normally updated independently of
each other. So the interface must remain binary compatible across releases.
SteamOS Manager and the Steam client are normally updated independently of each
other, thus the interface must remain binary compatible across releases.
In general, when making changes to the interface please consider the following:
- Method signatures must not be altered
* Instead, prefer exposing a new symbol and add a compatibility adapter to the previous interface
- Instead, prefer exposing a new symbol and add a compatibility adapter to
the previous interface
- Changes in behaviour should be avoided
* Consider how a change would affect the beta and stable release of the Steam client
- Consider how a change would affect the beta and stable release of the Steam
client
- Features must have a mechanism to discover if they are available or not
* E.g. for a feature exposed as a property if the property is not present on the bus it means the feature is unsupported.
- E.g. for a feature exposed as a property if the property is not present on
the bus it means the feature is unsupported.
Note that while SteamOS Manager must never break binary compatibility of
the interface, the Steam client makes no guarantees that older versions of
@ -46,32 +77,26 @@ an interface will be used if available. As a rule of thumb, the client will
always provide full support for the SteamOS Manager interface version available
in the Stable release of SteamOS.
## Implementation details
SteamOS Manager is compromised of two daemons, one runs as the logged in user
and exposes a public DBus API on the session bus. And the second daemon runs as
the `root` user and exposes a limited DBus API on the system bus for tasks
that require elevated permissions to execute.
SteamOS Manager is compromised of two daemons: one runs as the logged in user
and exposes a public DBus API on the session bus, and the second daemon runs as
the `root` user. The root daemon exposes a limited DBus API on the system bus
for tasks that require elevated permissions to execute.
The DBus API exposed on the system bus is considered a private implementation
detail of SteamOS Manager and it may be changed at any moment and without warning.
For this reason, we don't provide an XML schema for the system daemon's interface.
detail of SteamOS Manager and it may be changed at any moment and without
warning. For this reason, we don't provide an XML schema for the system
daemon's interface and clients shouldn't use it directly.
## Extending the API
To extend the API with a new method or property first update the XML schema.
Then extend the user daemon's DBus API which is implemented in `src/manager/usr.rs`.
If the new functionality requires elevated privileges, then extend the system
daemon's DBus API in `src/manager/root.rs` with the necessary helpers to complete
the task. Please consider keeping as much logic as possible in the user context.
## Building
TODO: pretty much a rust standard Building
## Running tests
TODO
To extend the API with a new method or property update the XML schema and
extend the user daemon's DBus API, which is implemented in
`src/manager/user.rs`. Make sure to also update the proxy implementation in
`src/proxy.rs` and expose it in steamosctl, in `src/bin/steamosctl.rs`.
If the new functionality requires elevated privileges, instead extend the
system daemon's DBus API in `src/manager/root.rs` with the necessary helpers to
complete the task. However, you should keep as much logic as possible in the
user daemon.