Skip to content

Development

Jump to bottom Edit New page
alkazar edited this page May 17, 2023 · 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. Formerly 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

  • Formerly 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

Building an image locally

A local image can be created with the scripts in the utils folder. Be mindfull that the utilities need to be run from the repo root. Depending on the system you use, these utilities could also require super-user rights.

There are two variants:

First option is to do a local build, this compiles everything on your PC both AUR and packages found in pkgs/ folder (recommended)

$ (sudo) ./utils/build-full-image-local.sh

Second option is to do a remote build, this will use a docker container specified. As with git, you can choose to have the latest or you can have a specific revision of the container. If you use the container with a certain revision you will have an environment that matches a certain build. :master will use the latest revision on the master branch. With this method you will only require to build the AUR packages and finally the system image, since the pkgs/ folder is precompiled in the docker container. To use this method run

$ (sudo) ./utils/build-full-image-remote.sh

The build process is staggered in three stages:

  1. Build the docker container with dev tools, install package overrides, and build/install custom packages from pkgs/. Do not do a full system update after this step.

  2. Build AUR packages with the environment made in the previous step.

  3. Using the environment and built AUR packages the system image is created.

Please refer to the comments within these utilities for further information on what it does.

Installing an Image Locally

FRZR has a feature where you can plug in a flash drive with an image you are wanting to deploy in the root directory of the drive. To do this you will want to format the drive as EXT4 (BTRFS should work too) labeled as FRZR_UPDATE and copy over the .tar.gz.xz file over.

Steps:

  1. Format the drive as EXT4 with the label FRZR_UPDATE.

  2. Copy over the .tar.gz.xz image you built locally. (You can also use the images from the ChimeraOS repo if you find a need to do so found here.)

  3. Boot into the ChimeraOS installer and once you are dropped into the blue installer screen it is safe to remove the installer boot drive and plug in your FRZR_UPDATE drive. (You can keep the install media plugged in and simply add the update drive as well)

Contributing & Testing

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. See 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, use the version number you want: 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

Unlocking the filesystem

By default the root file system is read-only. It is sometimes useful to unlock the filesystem to be able to install additional Arch Linux packages for development or testing purposes.

To do this, run the following command: sudo frzr-unlock

Note that this cannot be undone until the next system update.

Invalid or corrupted package errors

After unlocking the filesystem and using pacman you may encounter the following error: invalid or corrupted package (PGP signature)

To fix this, run the following series of commands: 

sudo rm -fr /etc/pacman.d/gnupg
sudo pacman-key --init
sudo pacman-key --populate archlinux
sudo pacman -S archlinux-keyring

Forking

ChimeraOS is actually ideal as a base for other purpose-built operating systems because it is very easy to customize and fork. This section describes how to create and use your own customized ChimeraOS-based operating system.

The process is as follows:

  1. Fork the main GitHub repository

  2. Enable GitHub Actions to allow system images to be built automatically for you

  3. Make your desired changes/customizations

  4. Wait for GitHub to build your new system image

  5. Point an existing ChimeraOS install to your repository

Note that GitHub has an individual file size limit of 2GB. Be mindful of this when adding packages or files to the system image.

Fork the GitHub repository

Go to https://github.com/chimeraos/chimeraos and click the "Fork" button on the top right of the screen. On the "Create a new fork" page that appears, customize the values as needed and click "Create fork".

This repository is what builds the operating system image.

Enable GitHub Actions

  1. Open your forked repository in GitHub and click on the "Actions" tab. Click on the "I understand my workflows, go ahead and enable them" button.

  2. Open the "Settings" tab on the forked repository, click "Actions", then click "General". Now scroll down to the "Workflow permissions" section and select "Read and write permissions" and click "Save".

Now, whenever you push a commit to the repository, GitHub will automatically build a new system image.

Customize

The main file you will want to customize is manifest. This has variables for determining the name and version of the OS as well as what packages and services to install and run.

There is also a rootfs directory that contains any additional files that need to be installed as part of the OS.

You may also find the need to make changes to build.sh which controls the system image build process.

Install your custom version

You first need to install ChimeraOS.

Then from a terminal, run sudo frzr-deploy MY_GITHUB_USER/MY_FORK:RELEASE_CHANNEL. Make sure to replace MY_GITHUB_USER and MY_FORK with the name of your GitHub user and the project name of your fork. RELEASE_CHANNEL should be replaced with the desired channel to download releases from. See the section below for details.

Release channels

ChimeraOS has three release channels: unstable, testing, stable. Any of these three options can be used with the frzr-deploy command.

New builds will automatically be put on the unstable channel. To move a release form unstable to testing, simply remove the "[UNSTABLE]" text from the release name. To move a release from testing to stable, simply uncheck the "Set as a pre-release" option on the release.

Entering BIOS/boot menu for specific devices

OneXPlayer Mini AMD

Press the orange button and volume up button at the OneXPlayer logo at boot.

Debugging Mesa

Use downgrade to test out older versions of mesa and lib32-mesa.

To build and install mesa from git run 

meson setup build/
ninja -C build/ install

You will need these packages: base-devel cmake ninja meson

Add a custom footer
Add a custom sidebar
Clone this wiki locally