# Solus 5: AerynOS tooling migration planning

## Introduction

Per agreement in Solus Staff chat, this document will be maintained to act as the overarching focal point for project-specific action items, issues and PRs, with a specific view to breaking things out into "phases".

Ikey has explicitly promised that AerynOS will help research, develop and document the necessary migration tooling and processes in such a way that Solus stakeholders can (in time) take over ownership and maintenance of them until the migration is complete.

### Stakeholder overview

**AerynOS Stakeholders:**
- Product Owner: tarkah, ermo
- Process Coordination: ermo
- Tooling Contributors: ermo, jonas, Evan, Gavin, Joey, Jonas, Reilly, Silke, tarkah

**Solus Stakeholders:**
- Change Management Owners: Evan, sheepman, silke
- Process Coordination: Evan, sheepman, silke
- Tooling Contributors: ermo, Evan, Joey, Gavin, sheepman, Harvey, Joey, Reilly, Silke

Anyone from Solus who feel they have the extra bandwidth for it is welcome to be stakeholders. =)

## Solus 5 (moss-based) targets

### /usr merge (DONE)

*Solus Tracker Issue [here](https://github.com/getsolus/packages/issues/293)*

Since the AerynOS tooling is explicitly avoiding controlling anything but /usr, a hard prerequisite on the Solus side is to get the /usr merge process finished.

### Migration to py3-based eopkg.bin (DONE)

*Solus Tracker Issue: [here](https://github.com/getsolus/packages/issues/2193)*

*Solus PR: [unified eopkg py3 + nuitka PR](https://github.com/getsolus/packages/pull/2169)*

Given that we now have the ability to quickly stand up an `eopkg_venv` testing environment (see [section below](#eopkg_venv-support-convenient-testing)), the idea is that it can be used to test the pisi->eopkg.bin upgrade process without having to resort to building a VM, because it allows for quick pure-python eopkg py3 code turnaround times.

As it turns out, both pisi (py2) and eopkg.bin (py3 nuitka version) allows the user to _overwrite_ files owned by each other.

This was cleverly exploited by sheepman in [PR#5820](https://github.com/getsolus/packages/pull/5820)

#### eopkg_venv support (convenient testing) (DONE)

ermo has now completed the first pass of the eopkg_venv functionality, which lives in the [eopkg python3 branch](https://github.com/getsolus/eopkg/tree/python3?tab=readme-ov-file#eopkg-venv-testing).

On his system, a new eopkg_venv chroot takes around a minute or two to set up from start to finish assuming all 168 packages are cached on the host system, thus making multiple epoch testing runs trivial to accomplish in quick succession. In addition, this process will see native filesystem speeds, which is a clear advantage over any VM-backed process.

EbonJaeger has updated the venv script to work with the new way eopkg4 is being built.

### Solus epoch upgrade (DONE)

Status [here](https://github.com/getsolus/packages/issues/4119)

This will be achieved by a so-called "epoch upgrade" process [(collected notes here)](https://hackmd.io/@cf7jUxWMSJi3p8x32jOTGg/H1sSQGpEC), which involves a carefully controlled sequence of operations on user systems that essentially upgrades them to the lastest pre-epoch tooling, which in turn then enables the actual epoch upgrade process to happen in a controlled way on each user system.

## AerynOS infrastructure work items

Solus' move to AerynOS-developed infrastructure depends on a couple of tasks on the AerynOS side as well.

### `autobuild`-based package build workflow

**Serpent Tracker Issue:** https://github.com/serpent-os/moss/issues/206

**Solus Tracker Issue:** https://github.com/getsolus/packages/issues/2175

The first thing that needs to happen, infrastructure wise, is that both AerynOS and Solus settle on using Gavin's [`autobuild`](https://github.com/GZGavinZhao/autobuild) for generating and building local packages in the correct build order.

Autobuild has just recently become capable of correctly and consistently resolving and planning build orders the same way each time it is run on a given set of input.

On the Solus side of the fence, Gavin and I came up with the _tentative_ term "Auxiliary Dependencies" (or `auxdeps`) as described in the tracker issue at the top of this section.

AerynOS is happy with the "Auxiliary Dependencies" / `auxdeps` moniker and has developed an annotation strategy that is trivial to implement in AerynOS tooling once we are freed from the existing DLang libmoss shackles in terms of how we specify dependencies.

### Binary conversion from .eopkg to .stone

Tooling: https://github.com/serpent-os/a-piece-of-pisi

The intent is for this process to be used to generate a set of .stone artefacts which can be used as a "seed" binary repo to rebootstrap the Solus 5 recipe repo using AerynOS-developed, but Solus-deployed infrastructure tooling.

The idea is to begin doing conversion runs in parallel with normal Solus package.yml-based development, as a way to help Solus understand which .eopkgs are not yet compliant with the AerynOS tooling requirements, such that work can be focused appropriately.

Now that ypkg is py3, there is nothing stopping Solus from incrementally adopting AerynOS build macros in ypkg, which will in turn help with the Recipe conversion process outlined below.

### Recipe conversion from package.yml to stone.yaml

*Tooling: **TBD***

Once the binary conversion is in good shape, the current solus `packages` repo will then need to be converted to AerynOS `stone.yaml` format.

This way, the new Solus 5 binary repo can be built up gradually from the new Solus 5 recipe repo, using known-good converted-from-.eopkg .stones as builddeps and rundeps when building the new stone.yaml recipes with the AerynOS boulder build tool (replaces solbuild).

### AerynOS infra-in-rust progress

Rust infra work is ongoing, but the MVP is in production and has built 6+k packages at this point (primo Q4 2025).

The current _tentative_ plan is that we will need to define a set of targets capabilities that the AerynOS-side of the infra needs to support.

Next to that, we need to define a set of target capabilities that the Solus recipe repo needs to expose for it to be able to take advantage of the AerynOS infra.

Chiefly, this revolves around building a tool which can analyse both individual packages _inside_ `solbuild` _and_ is capable of inspecting a package.yml + pspec XML + associated .eopkg (in a temporary folder?) and then creating a suitable AerynOS-infra-supported manifest for increased whole-tree insight and dep-analysis.

Only once these targets have been met on both the AerynOS infra side and the Solus recipe tree side, will we be able to move forward with the infrastructure plans it seems.

One of the ideas we have played around with is to have an auxiliary .yaml file that allows us to play with adding new keys/metadata _outside_ of package.yml on the solus side, to make it easier to experiment with new stuff on both the AerynOS and the solus side.

Right now, we could even (re)-use gavin's proposed autobuild.yaml files for this as a starting point?