Arch Linux Ports

Introducing a new port

New ports are added by proposing them in an RFC. At least two package maintainers have to lead a port to ensure it will be developed longer term.

Once an introduction RFC is accepted, the work on a port may start. Initial work includes additions of port specific integration (e.g. custom pacman.conf, makepkg.conf, etc.) to the official build tooling.

Port maintainers are expected to work together with relevant Arch Linux teams to enable the setup of any required infrastructure. Required changes to existing tooling should be proposed and if possible also implemented by port maintainers, to ease the workload on the existing teams.

As part of the porting work, port maintainers rely on the official architecture independent packages of the distribution. Any architecture independent packages, that are identified as architecture dependent by a port (this may include e.g. header-only packages for which the upstream build system provides different sets of files for differing architectures) must be adapted to become architecture dependent.

Source repositories

The package source repositories for all packages are also used for ports.

Tickets that are specific to a port are labeled accordingly to provide a better overview and allow people working on those specific ports to filter for them.

ports::aarch64
ports::loong64
ports::riscv64
ports::x86_64_v2
ports::x86_64_v3
ports::x86_64_v4

Ports are built from the same tags of a package's default branch as the supported architectures.

The build tooling matches the tag of a package source repository against the specific binary package version in the target repositories (ports, as well as supported architecture) to keep track of the current version of a given architecture.

As long as the architecture is not an officially supported architecture, the PKGBUILD arch array is not updated to contain the port architecture string. The build tooling should allow building for a specific architecture, while ignoring the particular architectures set for a given PKGBUILD.

If a port can not be built using the latest version of a given package source repository, port maintainers are advised to try and provide patches. If additional patches are sufficient, the port version may be built using an updated pkgrel. Alternatively, sub-versions (e.g. pkgrel=1.1) may be used if it is not feasible to rebuild the supported architecture(s).

In case a port is unable to upgrade (e.g. due to issues for which upstream has not yet found a solution, or due to switching to a language unsupported by the architecture), a port has to maintain compatibility with whichever is the last working version of a given project. This may entail providing further updates to pkgrel for rebuilds going forward. For these updates to pkgrel a separate branch named after the port's architecture must be used in the dedicated ports/ namespace (e.g. ports/aarch64, ports/loong64, ports/riscv64, ports/x86_64_v2, ports/x86_64_v3 or ports/x86_64_v4). This branch is kept indefinitely. If the upstream project releases a new version for this older version branch of its software, a new package source repository tracking this particular version should be created (e.g. project -> project1). In case the port is able to return to the default branch of the package source repository, updates to the package again follow the normal workflow.

When using the separate branch in the ports/ namespace, great care has to be taken. Introducing an epoch should only be done after weighing all possible options, as doing so has implications for the default branch later on. If a port returns to using the default branch again after having introduced an epoch for the namespaced ports/ branch, also the default branch must introduce an epoch.

Patches should be applied conditionally, if specific for a port architecture and unconditionally, if merged upstream. For architecture specific patches, dedicated source arrays (e.g. source_riscv64=()) are to be used.

Port maintainers should attempt to provide generic adaptations for PKGBUILDs if there are architecture specific issues to be solved. Package maintainers should apply these adaptations, so that ports can be kept as close to the current supported architecture as possible.

Binary repositories

Each port maintains their own binary package repository. Port repositories are distributed alongside the official Arch Linux repositories on the mirrors in a namespaced directory structure:

/ports/pkg/aarch64/$repo/
/ports/pkg/loong64/$repo/
/ports/pkg/riscv64/$repo/
/ports/pkg/x86_64_v2/$repo/
/ports/pkg/x86_64_v3/$repo/
/ports/pkg/x86_64_v4/$repo/

Installation media

Ports should create generic installation media, which works on a broad set of devices. At the time of writing, this can be achieved using archiso's releng profile as a base. This does not necessitate covering installation scenarios for special purpose hardware (e.g. those only able to boot from an SD card), as for those special purpose bootstrap artifacts need to be created.

Port installation media is distributed alongside the official Arch Linux binary artifacts in a namespaced directory structure:

/ports/install/aarch64/
/ports/install/loong64/
/ports/install/riscv64/
/ports/install/x86_64_v2/
/ports/install/x86_64_v3/
/ports/install/x86_64_v4/

Additionally, it is strongly recommended for port maintainers to work on integration with other software that helps with the installation of Arch Linux, such as archinstall.

Virtual machine images

Ports should create virtual machine images for their specific architecture. At the time of writing this can be achieved by adapting the arch-boxes project.

Port virtual machine images are distributed alongside the official Arch Linux binary artifacts in a namespaced directory structure:

/ports/vm/aarch64/
/ports/vm/loong64/
/ports/vm/riscv64/
/ports/vm/x86_64_v2/
/ports/vm/x86_64_v3/
/ports/vm/x86_64_v4/

Promoting a port

Promoting a port to an officially supported architecture is done by proposing a port to be promoted in an RFC. A port to be promoted should have an average 90% up-to-date ratio over the previous six months. As such a promotion RFC should include numbers on the up-to-date ratio vs. the official repositories and outline how many people are actively working on architecture specific issues and packaging. The estimated workload on maintainers of the existing, officially supported architectures needs to be highlighted and the effective difference between the long-lived port branches vs. the default branches must be evaluated.

After a promotion RFC is accepted, work starts on adapting the default branches of all package repositories. Any changes required to package the ported architecture in the official repositories are applied to the default branch. When all default branches are in sync, the architecture is bootstrapped into the official repositories.

If a promotion RFC is not accepted, it may be re-evaluated at a later point in time, if any major issues that led to it not being accepted have been worked out.

Support

For Arch Linux staff the ability to provide support for a port depends on the availability of hardware and virtual machines to test and reproduce on.

If a port introduces hardware that requires special integration (e.g. a custom bootloader setup for a single board computer), basic user-facing documentation in the Arch Wiki about this device must be provided by relevant package maintainers (e.g. stating which bootloader package to use). Furthermore, any non-trivial packaging steps for such a device must be clearly documented, so that other packagers may share the workload of maintaining such a device.

Closing an existing port

Closing a port as abandoned is done by proposing a port to be closed in an RFC. A port should be closed if no one is willing to lead the project for six months or more, if it has not seen sufficient activity for six months or more, or if the up-to-date ratio of existing ported packages falls below 50% for six months or more. Re-opening a closed port should go through the same procedure as introducing a new port.

If a port has been closed, its long-lived branches may be kept for up to two years, in case volunteers are willing to put in the effort to re-introduce it. After this grace period has passed, the long-lived branches should be removed.

Archweb integration

Archweb should be extended to make multi-architecture packages more organized, easy to search for and filter.

The website should clearly indicate which architectures are unofficial ports and which are officially supported.

Providing progress statistics and graphs would be ideal.

AUR integration

All port architectures alongside the officially supported ones should be allowed in the arch array of PKGBUILDs found in the AUR.

Ideally, the AUR web interface / API is extended to allow filtering packages by architecture.

Keyring

The existing archlinux-keyring will be reused for ports as the packagers remain in the same trust group (Arch Linux Package Maintainers).

Package guidelines

Existing package guidelines should be adapted to become more generic and architecture agnostic. This ensures, that new architectures can reuse existing package build sources easily.

Port maintainers should help extend the distribution's package guidelines wherever friction prevents a straight forward adoption of existing guidelines.

Package repository management

The central package repository server is used to manage the repositories of supported architectures. For this, the host stages all available packages in a package pool directory and symlinks those needed by a specific repository (e.g. core or extra) to its respective package repository directory. Package repositories expose a specific set of packages via their repository sync databases to the end user. Unneeded packages (those no longer mentioned in a repository sync database and therefore no longer in any package repository) are removed from the package repository and package pool on a regular basis.

The handling of port repositories will work in an analogous manner: A dedicated package pool for each port architecture is created on the central package repository server, that will contain packages specific to that architecture. All architecture independent packages (i.e. those of type any) are reused from the package pool of the supported architectures.

The cleanup algorithm of the supported architectures package pool is adjusted to also consider package use in port package repositories.

The contents and handling of a port's package repository relies on two package pool directories. Appropriate changes to the existing or any upcoming package repository management tooling needs to be made to reflect this behavior.

Archival

Arch Linux has a strong commitment towards reproducible builds. As such, a package archive is also required for ports to be able to reproduce packages that were built against packages which are no longer in the current repositories.

Any new port should therefore be archived using established archival procedures.

Debug packages

Debug symbols are a useful and necessary tool to help upstream developers and distribution package maintainers to debug issues with built packages. Due to the size of debug packages and the mostly on demand requirement for them, the focus of providing them should lie on debug-infod integration.

Whether the widespread hosting of dedicated debug package repositories is wanted and is feasible should be evaluated in a separate RFC.

Package build tooling

Arch Linux's official package build tooling devtools must be adapted to make dealing with ports easier and more streamlined.

As an example: Rebasing the arch array of PKGBUILDs every time the canonical package changed is cumbersome. A possible solution to this problem is to modify makepkg to accept options via makepkg.conf as well (e.g. to override -A/ --ignorearch) or to modify pkgctl in such a way that passing in -A/ --ignorearch or a specific architecture becomes possible.

A baseline for compiler flags for each port must be established. The compile flags of a port should stay as close as possible to the ones used by the officially supported architecture(s).

The package lint integration for namcap must be extended to support a port's specific requirements (e.g. verifying SIMD and CPU extension support in binaries).

Existing architecture independent packages and signatures are reused in a port. Edge-cases around these packages such as the following need to be solved: - adding existing packages from the official package pool or maybe even the package archive to a package repository without building them - file collision prevention in case a package needs to be modified and rebuilt due to architecture specific changes (e.g. by using a pkgrel of 1.1 for a port, while the pkgrel for the supported architectures remains at 1)

Whether the integration of QEMU for virtualized builds or direct cross-compilation is worth the effort should be evaluated and if feasible integrated. Virtualization with QEMU's user mode faces many challenges such as: - use of the unsafe "C" flag for binfmt - various issues such as /proc parsing, futex related hangs in Python, Go and Rust - incomplete support for vfork Support for cross-compilation appears to be even more complex as it would mean rethinking larger portions of our current source handling (e.g. defining a separate sysroot for the target architecture and passing in required environment variables etc.). As such this integration should be evaluated and concluded upon in a separate RFC.

Mirrors

Mirror maintainers are strongly encouraged to also host the ports package pools and package repositories.

The additional space requirements for a port currently range between 33 GiB (total size of the architecture dependent packages in the riscv64 port) and 61 GiB (total size of the architecture dependent packages in the official x86_64 repositories).

The space requirements for also hosting debug packages of a port are currently at 72 GiB (total size of debug packages for the official repositories).

Mirror maintainers may opt out of hosting ports (e.g. due to size limitations on their hardware). To exclude a port from the mirror's syncing operations, the port specific package pool and package repository directory structure need to be ignored. To exclude all ports, all port package pool and package repository directory structures have to be ignored.

Mirrorlist

Arch Linux's mirrorlist management, as well as user-facing tools have to be adapted to support filtering by architecture and allow generation of port specific mirrorlists.

Documentation

Ports must maintain documentation that is aimed at its maintainers and outlines how to run them and how to package for them. If the distribution handbook (RFC0021) is accepted, this documentation should be added there, otherwise a dedicated location has to be found for it. This maintainer-aimed documentation should also work towards outlining a generalized process for bootstrapping Arch Linux on new architectures.

User-facing documentation on how to install and use a port should be added to the relevant articles in the ArchWiki.