Skip to content

Development

Jump to bottom
Derek J. Clark edited this page Jun 4, 2022 · 66 revisions

ChimeraOS Development

About

This page is for holding development documentation and how to get involved

Resources

The main set of repositories can be found here.

  • chimeraos: Primary repository for the operating system.

  • chimera-data: Holds frequently changing data used by chimera (Proton GE lists, game tweaks, game compatibility db); chimera automatically downloads this data at the start of the gaming session through hooks in steamos-compositor-plus. This repo is separated from the chimera repo so we can update the data without rolling new releases of Chimera or ChimeraOS.

  • chimeraos.github.io: Web page content

  • chimera: The ChimeraOS web interface. Formally known as "Steam Buddy".

  • steamos-compositor-plus: A fork of the steamos compositor with some game compatibility fixes

  • install-media: Defines and builds the installation media through GitHub Actions

  • frzr: A deployment and automatic update mechanism for operating systems

Sprint/Kanban Board

The current list of backlog and current task can be found here.

How ChimeraOS Works

  • Installation…​

  • chimera app…​

  • Update mechanism

  • Uses frzr to pull down a compressed image

  • User reboots and the image is put into place

  • Packages and traditional package management system are not used to simplify the user experience and make it as seamless as possible, mimicking a console environment.

  • ChimeraOS boots directly to Steam Big Picture mode with a custom window manager.

ChimeraOS Components

Below is a list of packages/repositories and how they fit together

chimeraos

This repository houses the main underpinnings of how the OS comes together.

├── BUILDING.md: Basic instructions on building ChimeraOS yourself  
├── build.sh: Main build script for the OS  
├── Dockerfile: Dockerfile build recipe for the OS.  
├── index.html
├── LICENSE
├── manifest
├── README.md
├── repos: Artifact of an old build process, not used anymore.
└── rootfs
    ├── etc
    │   ├── bluetooth
    │   ├── initcpio
    │   ├── locale.conf
    │   ├── locale.gen
    │   ├── mkinitcpio.conf
    │   ├── modprobe.d
    │   ├── modules-load.d: Contains system tweaks
    │   ├── polkit-1: Rules for polkit (controlls system-wide privileges)
    │   ├── resolv.conf
    │   ├── sudoers.d: Sudo rule files
    │   ├── suspend-modules.conf
    │   ├── systemd
    │   └── udev: Device rules
    ├── extra_certs
    └── usr: User files

frzr

Overview

frzr is the A/B btrfs update system which downloads system images from the ChimeraOS repo. Available channels are unstable, testing, stable. Unstable has completely untested builds directly from GitHub Actions and most poeple should never use it. Testing images have at least been verified to boot, but might contain problems that require manual intervention to recover from. Stable are fully tested images that should be used by everyday users.

  • Compressed image is delivered to user containing the entire basic OS

  • btrfs subvolumes

  • rootfs is read only

  • Additional software

  • Flatpak

  • custom images you can create

  • No usage of pacman (changes are reverted at next update)

File system

The design is split into a physical and user-facing file system design:

filesystem

Physical filesystem

  • / (root)

    • /deployments: Here you’ll find deployments that are downloaded for updates / upgrades.

    • /deployments/gameros_<verzion>: ChimeraOS versions (the entire filesytem for a given version).

  • State volumes: Handle a base state in-between updates

    • /etc: Overlay. Needed to maintain settings (timezone, preferences, and so on)

    • /home: btrfs subvolume

    • /var: btrfs subvolume

User-facing filesystem * Exposed the user * /home and /var mounted * Actual / mounted to /fzr_root for the user (for update machanisms)

Update Mechanism * Update is downloaded into /deployments, extracted into it’s specific /deployments/chimeraos_<version> subfolder * Boot loader is updated to point to this new subvolume (e.g. /deployments/chimeraos_20`) * User reboots at time of their choosing * New state is mounted to the user-facing filesystem side as it was initially upon installation.

Game Compatibility

SteamOS Compositor Plus

  • Forked version of steamcompmgr to work around some issues.

Steam Tweaks

  • Additional features available to bolster game usability with Proton

  • Gamepad support

  • Proton configuration

  • Launch options

  • Patches

Chimera app

  • Formally known as "Steam Buddy".

  • Web frontend

  • Install games (ROMs, Flathub, EPIC Store)

  • System Actions

  • Shortcut management

  • Steam session / system event handling (restart Steam, volume, restart system etc…​)

  • Toggle performance overlay (MangoHUD)

Setting Up a Development System

Contributing

There are three channels that are available with ChimeraOS images. Two of them are used for testing and development. Be aware that these are much less stable channel and things may break from time to time. Be prepared to have to re-install your system from scratch. - stable, contains the most recent release revision available. Fully tested software. - testing, contains release candidate software. Partially tested software undergoing validation. - unstable, contains untested development software. This branch is only recommended for developers testing new features. - additionally, previous versions can be manually set. This is useful if a major bug or regression made it to stable release, or for testing upgrade paths.

If you still want to participate, you can switch to the testing channel like so:

  1. [access the terminal](https://github.com/ChimeraOS/chimeraos/wiki/FAQ#how-can-i-access-the-terminal-from-chimeraos)

  2. run the command sudo frzr-deploy ChimeraOS/chimeraos:testing to switch to the testing channel and update the system (NOTE: there may not be an update if there is no testing version currently available)

  3. restart the system once the update is complete

Switching to the unstable branch is much the same, run the command sudo frzr-deploy ChimeraOS/chimeraos:unstable

To go back to the stable channel, run: sudo frzr-deploy ChimeraOS/chimeraos:stable

To go to a previous release, change to the version number you are targeting. i.e.: sudo frzr-deploy ChimeraOS/chimeraos:32

Pull Request

Major Feature work

Collaboration

Most musing and technical chit chat on current/future ongoings takes place on the discord channel: https://discord.gg/e3Crvnew

Clone this wiki locally