Skip to content

Development

Jump to bottom Edit New page
Derek J. Clark edited this page Feb 17, 2024 · 66 revisions

Setting Up a Development System

Run the prep-devmode.sh script from [this repository](https://github.com/ruineka/chimeraos-hack-tools/blob/main/hacks/prep-devmode.sh) 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](https://github.com/ChimeraOS/linux-chimeraos/releases/tag/v6.6.13-chos1-1) with sudo pacman -U <link to headers> You can identify your current kernel with `uname -r

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.

For details on how to switch sessions, see the [General Configuration](https://github.com/ChimeraOS/chimeraos/wiki/General-Configuration#session-switching) 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.

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 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.

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.

Entering BIOS/boot menu for specific devices

OneXPlayer Mini AMD

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

AyaNeo Air1S

Hold down volume down as the device powers on. You will need a USB keyboard to page through settings.

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