Development

Sprint/Kanban Board

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

Setting Up a Development System

Run the prep-devmode.sh script from this repository This script will do the following: - Unlock the filesystem - Remove outdated gnpupkg and fakeroot configurations - Rebuild the archlinux keyring - Install basic build tools - Download and install the ChimeraOS Kernel Headers

Note: Occasionally the GitHub actions produce inconsistent naming conventions for kernel releases. If thus happens you will need to manually install the headers from the releases page with:

sudo pacman -U <link to headers>

You can identify your current kernel with:

uname -r

Building an image locally

Clone the ChimeraOS repository

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.

For details on how to switch sessions, see the General Configuration page.

Collaboration

Most musing and technical chit chat on current/future on-goings take 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.

Under no circumstances should you run an upgrade through pacman (or any AUR helper) with an unlocked filesystem. ChimeraOS locks the archive_date for the official repositories to prevent build conflicts. This can lead to package and dependency drift. Installing updates through the normal arch method can make your system unbootable.

To unlock, 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 the ChimeraOS repository 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.

Updating or adding new AUR packages to a stable channel for a hotfix release

You may need to add or update a new AUR package when releasing a "hotfix" version. These are typically built on top of the current "stable" release channel. Pushing to the stable branch will trigger a build that is sent to the "testing" channel.

• For new packages:

  cd aur-pkgs
  git submodule add https://aur.archlinux.org/<pkgname>

  This will automatically initialize the new module and add it to staging for a commit. Be sure to add the new package to the manifest as above and add it to the same commit.

• For existing packages:

  cd aur-pkgs
  git submodule init <pkgname>
  cd <pkgname>
  git pull
  cd ../..
  git add <pkgname>
  git commit -m "Updated AUR package <pkgname>."

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 on the master branch. Builds made from the stable-XX branches are put into the testing channel directly. 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.

See the Update Channels section for information of switching between these channels.

Release process and chores

All the development of new features for major releases are made in the master branch with each new commit pushed triggering a build.

Pro tip: add [skip ci] to the commit message to avoid triggering a build.

Once you are happy with the changes made and unstable builds became usable with the new features a stabilizing process can begin. Manually run the action Create Stable Branch from the branch master to automatically set up:

• Branch the current master into a new stable-XX branch. The XX number will be read from the manifest in master and filled in by the action.

• Fixate the variable ARCHIVE_DATE to yesterday thus freezing the Archlinux repository versions

• Set up all AUR_PACKAGES as git submodules

• Increment the master manifest version by 1

New commits on this branch will trigger a build and pushed to the testing channel automatically. All fixes should now be committed into stable-XX branch. If you want to trigger a build immediately after the Create Stable Branch action, you can also trigger a build manually giving a branch argument to System image build - stable .

When the testing passes all release criteria release the build as stable channel as usual. Don’t forget to add the same fixes to master if appropriate.

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

Also see: https://wiki.archlinux.org/title/Bisecting_bugs_with_Git

Building linux-chimeraos

To build linux-chimeraos, there are a few things you need to know.

1. The linux-chimeraos repo contains the PKGBUILD that will extract the source tarball that you will create using the linux repo.

2. We will want to take a look at the linux repo when you want to apply patches to a kernel, you can do so by creating a new branch for your changes. For example, if you want to add the 6.9 kernel, create a branch named 6.9/chimeraos. (Not to be confused with linux-chimeraos).

3. Make sure you commit your version changes in the Makefile. Each patch series you create should increment the version by one: EXTRAVERSION = -chos1.

4. To trigger a tag release, you will need to commit the tags using this command: git tag -a v6.8.2-chos1 -m "linux-chimeraos v6.8.2-chos1". This command will create an annotated tag with the name v6.8.2-chos1 and a message indicating the version. Make sure to replace "linux-chimeraos v6.8.2-chos1" message with your specific kernel name you are building.

5. Now we need to take our attention over to linux-chimeraos repo and update the pkgver=6.8.chos1 line of the PKGBUILD. Save your changes and run updpkgsums to update the checksums. Commit these changes with the message linux-chimeraos v6.8.2-chos1 and run ./make-tags.sh to generate your tags. Now all you need to do is run git push --tags and this will trigger a new kernel build.

6. Once this finishes, you will need to update the manifest in the chimeraos GitHub to grab the packages to be installed into the image during build.

Building mesa-chimeraos

1. Create a new branch following the mesa-24.0.1 style and apply your mesa patches. Use the make-tag.sh script provided in the repo to make a commit to push that will trigger a build.