Developer Manual

Mon, 01 Jan 0001 00:00:00 +0000

Staff Services#

Arch Linux provides a number of services for Arch Linux Staff which they can freely use but fair use is applicable.

accounts.archlinux.org#

This server hosts Keycloak, a single sign on server Arch Linux uses to easily onboard new users to new groups and provide a seamless login experience through all our services once they all use SSO. Currently Gitlab, Matrix and HedgeDoc use SSO and staff only need a Keycloak account to be able to use these services.

32-bit

Mon, 01 Jan 0001 00:00:00 +0000

32-bit package guidelines#

Legacy 32-bit software can be built and installed on machines of another native architecture, such as x86_64. This article explains the production and conventions of such packages.

Package naming#

Prefix 32-bit versions of native packages with lib32-.
Package decriptions should distinguish these from native counterparts, i.e. pkgdesc+=" (32-bit)".

Variables and parameters#

lib32#

Specify these bash variables in a PKGBUILD to tell the compiler to output 32-bit code:

export CFLAGS+=" -m32"
export CXXFLAGS+=" -m32"
export LDFLAGS+=" -m32"
export PKG_CONFIG_PATH='/usr/lib32/pkgconfig'

File placement#

Ensure lib32 package files do not conflict with native package files and include all necessary files, such as architecture-specific includes. For example, if a package builds using GNU Autoconf, specify the following to configure:

CLR

Mon, 01 Jan 0001 00:00:00 +0000

CLR package guidelines#

This document defines the standard for packaging Common Language Runtime (.NET) projects under Arch Linux. Currently only Mono is capable of providing a usable, efficient CLR runtime for multiple systems and this standard will reflect its use. Be aware that a lot of CLR programs were developed with Microsoft .NET in mind and, as such, may or may not run under Mono because of .NET-exclusive factors such as P/Invoke calls and Microsoft digital rights management (DRM) APIs and are thus will not yield a usable package for Arch Linux. However, if combined with Wine as of version 1.5.6 (?), your package may have a chance to run under it. Please see the Wine PKGBUILD Guidelines for more information if such is the case.

CMake

Mon, 01 Jan 0001 00:00:00 +0000

CMake package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for software that uses cmake.

From the CMake web page:

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

Typical usage#

The typical usage consists of running the cmake command and after that execute the building command. The cmake command usually sets some parameters, checks for the needed dependencies and creates the build files, letting the software ready to be built by other tools like make and ninja.

DKMS

Mon, 01 Jan 0001 00:00:00 +0000

DKMS package guidelines#

Here are some guidelines to follow when creating a DKMS package.

Package name#

DKMS packages are named by appending -dkms to the original package name.

The variable $_pkgname is often used below $pkgname to describe the package name minus the -dkms suffix (e.g. _pkgname="${pkgname%-*}")

Dependencies#

Add dkms to depends array. This is important because this will provide tools and hooks that will rebuild the kernel driver provided by the -dkms package whenever the kernel is updated.

Eclipse plugin

Mon, 01 Jan 0001 00:00:00 +0000

Eclipse plugin package guidelines#

There are many ways to install working Eclipse plugins, especially since the introduction of the dropins directory in Eclipse 3.4, but some of them are messy, and having a standardized and consistent way of packaging is very important to lead to a clean system structure. It is not easy, however, to achieve this without the packager knowing every detail about how Eclipse plugins work. This page aims to define a standard and simple structure for Eclipse plugin PKGBUILDs, so that the filesystem structure can remain consistent between all plugins without having the packager to start again for every new package.

Font

Mon, 01 Jan 0001 00:00:00 +0000

Font package guidelines#

This document covers proposed standards and guidelines on writing PKGBUILDs for Fonts.

General guidelines#

Package naming#

TTF fonts: ttf-fontname
OTF fonts: otf-fontname

If the font is a variable font, add the suffix -variable.

ℹ️ Note

The package name should be entirely lowercase.

Ultimately there is no hard rule for font package naming, i.e. these are only guidelines. In general, package naming follows upstream. See also FS#77425.

Package description#

The package description should at least contain the word font and what type of font it is: sans-serif, serif or monospace.

Free Pascal

Mon, 01 Jan 0001 00:00:00 +0000

Free Pascal package guidelines#

This page explains on how to write PKGBUILDs for software built with the Free Pascal Compiler (FPC). Compiling for x86_64 Arch Linux requires the fpc package.

Package naming#

The project name alone is usually sufficient. However, in the case of cross-compiling, the package should be prefixed with fpc32- when targeting i686 Linux from multilib and named in the format of fpc-cpu-system-pkgname when targeting non-Arch Linux systems.

Helpful snippets#

Determine FPC’s version and the CPU and OS of the units to output:

GNOME

Mon, 01 Jan 0001 00:00:00 +0000

GNOME package guidelines#

The GNOME packages on Arch Linux follow a certain schema.

Source URL#

GNOME packages normally follow two source URL scheme: a released tarball stored in GNOME’s FTP server and a specific commit in the software’s Git repository

Using released tarball#

When downloading a released tarball, you can get it from https://download.gnome.org using the following source array:

source=("https://download.gnome.org/sources/$pkgname/${pkgver%.*}/$pkgname-$pkgver.tar.xz")

where ${pkgver%.*} returns the major.minor package version, by removing the suffix of pkgver (which is the micro package version). E.g., if pkgver=3.28.0 then ${pkgver%.*} would return 3.28.

Go

Mon, 01 Jan 0001 00:00:00 +0000

Go package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for Go.

General guidelines#

Package naming#

Use go-modulename if the package provides a program that is strongly coupled to the Go ecosystem. For other applications, use only the program name.

ℹ️ Note

The package name should be entirely lowercase.

Building#

Dependencies#

Go 1.11 introduced the initial support for go modules. This allows Go upstream code to declare dependencies and pin them to the given project version. Currently our packaging efforts utilize this to vendor dependencies.

Haskell

Mon, 01 Jan 0001 00:00:00 +0000

Haskell package guidelines#

This document aims to cover standards and guidelines for producing good Haskell packages on Arch.

Until this document is rewritten, contact User:Felixonmars.

Package naming#

For Haskell libraries, use haskell-libraryname usually the same name as on hackage.

ℹ️ Note

The package name should be entirely lowercase.

Architecture#

See PKGBUILD#arch.

Every Haskell library or program is architecture-dependent.

Source#

The preferred source of a Haskell program or library is from hackage. PKGBUILD#source source=() array should use the following URL template:

Java

Mon, 01 Jan 0001 00:00:00 +0000

Java package guidelines#

This document defines a proposed standard for packaging Java programs under Arch Linux. Java programs are notoriously difficult to package cleanly without overlapping dependencies. This document describes a way to remedy this situation. These guidelines are flexible in order to cover the many different scenarios that arise when dealing with Java applications.

Introduction#

Arch Linux packagers cannot seem to agree on how to handle Java packages. Various methods are used in PKGBUILDs across the official and unofficial repositories and in the AUR. These solutions include placing the whole mess in /opt with shell scripts in /usr/bin or profiles placed in /etc/profile. Others are placed in directories in /usr/share with scripts placed in /usr/bin. Many add unnecessary files to the system CLASSPATH and PATH.

KDE

Mon, 01 Jan 0001 00:00:00 +0000

KDE package guidelines#

⚠️ Warning

This article or section is out of date.

Reason: References kde4, looks really outdated in general.

The KDE packages on Arch Linux follow a certain schema.

Build directory#

A good way of building CMake packages is to make a build directory outside the root of the project and run cmake from that directory. The PKGBUILD should look this way:

prepare() {
  mkdir -p build
}

build() {
  cd build
  cmake ../${pkgname}-${pkgver}
}

Install prefix#

Every packages must set the CMAKE_INSTALL_PREFIX variable.

Kernel module

Mon, 01 Jan 0001 00:00:00 +0000

Kernel module package guidelines#

Package separation#

Packages that contain kernel modules should be treated specially, to support users who wish to have more than one kernel installed on a system.

When packaging software containing a kernel module and other non-module supporting files/utilities, it is important to separate the kernel modules from the supporting files.

Guidelines#

When packaging such software (using the NVIDIA drivers as an example) the convention is:

create an nvidia package containing just the kernel modules built for the vanilla kernel
create an nvidia-utils package containing the supporting files
make sure nvidia depends on nvidia-utils (unless there is a good reason not to do so)
for another kernel like linux-mm, create nvidia-mm containing the kernel modules built against that kernel which provides nvidia and also depends on nvidia-utils
make sure nvidia depends on the kernel, for example:
```
depends=('linux' 'nvidia-utils')
```

Rationale#

While kernel modules built for different kernels always live in different directories and can peacefully coexist, the supporting files are expected to be found in one location. If one package contained module and supporting files, you would be unable to install the modules for more than one kernel because the supporting files in the packages would cause pacman file conflicts.

Lisp

Mon, 01 Jan 0001 00:00:00 +0000

Lisp package guidelines#

At the moment, there are relatively few Lisp packages available in the Arch repositories. This means that at some point or another, more will likely appear. It is useful, therefore, to figure out now, while there are few packages, how they should be packaged.

Directory structure and naming#

There is at least one package in the base repository (libgpg-error) that includes lisp files, which are placed in /usr/share/common-lisp/source/gpg-error. In keeping with this, other lisp packages should also place their files in /usr/share/common-lisp/source/pkgname.

Meson

Mon, 01 Jan 0001 00:00:00 +0000

Meson package guidelines#

From Meson’s official website:

Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible.

Written in Python, Meson features multi-platform support, support for several programming languages, cross compilation, and more.

Meson does not build software directly, but rather sets up a back-end build system. While it is commonly used with ninja, other build systems can be used. It is commonly used to replace GNU Build System.

MinGW

Mon, 01 Jan 0001 00:00:00 +0000

MinGW package guidelines#

This page explains how to write PKGBUILDs for software running on Windows.

In order to build software for Windows on Linux one needs:

Windows header files and import libraries for the WinAPI and the C standard library. There are two options to get those:
- mingw-w64: provides 32 and 64-bit toolchains with secure crt, Vista+ API, DDK (ReactOS), and DirectX (WINE) support. For a full list of supported features and differences with the old MinGW.org, see here. Available from the official repositories by installing mingw-w64-headers and mingw-w64-crt. AUR packages providing further libraries rely on those packages.
- MinGW: provides 32-bit toolchains with limited DirectX support. It also suffers from long-standing breakage in the implementation of thread-local storage and the floating point library support. It has been removed from the official repositories and the AUR.
A compiler and its runtime library.
- For C/C++ one can use GCC and Clang. To use GCC one needs to install mingw-w64-gcc as the regular gcc package cannot be used. To use Clang one can simply use clang specifying an *-w64-mingw32 platform triple as target. Since the regular clang package does not contain the compiler runtime libraries for Windows targets one needs to compile them separately or use the runtime provided by mingw-w64-gcc. AUR packages providing further libraries rely on mingw-w64-gcc.
- For Rust one can use mingw-w64-rust. The regular rust package is not built to be able to cross-compile for Windows. If Rust was installed using the rustup package, you should instead add the Windows target: rustup target add x86_64-pc-windows-gnu.
- For Go one can just use the regular go package.
A C/C++ standard library. One can use libstdc++ provided by mingw-w64-gcc or libc++ from the LLVM project. AUR packages providing further libraries rely on libstdc++.
A linker and additional tooling. One can use GNU binutils provided by mingw-w64-binutils or LLVM/lld provided by llvm and lld. There is also mingw-w64-tools providing a few additional Windows-specific tools.

For ix86/x86_64 the typical choice is to use mingw-w64- with GCC/libstdc++ and binutils. This is therefore what AUR packages following the package naming mingw-w64-pkgname use. The rest of this Wiki page focuses on those packages.

Node.js

Mon, 01 Jan 0001 00:00:00 +0000

Node.js package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for Node.js packages.

Package naming#

💡 Tip

A custom _pkgname variable can be used instead of pkgname. This variable can generically be defined as follows: _pkgname=${pkgname#nodejs-}.

Package names for Node.js libraries should start with a nodejs- prefix. For standalone applications, just use the program name.

Source#

npm provides a stable naming scheme for download URLs. PKGBUILD#source source=() array can use the following URL template:

Non-free

Mon, 01 Jan 0001 00:00:00 +0000

Non-free application package guidelines#

For many applications (most of which are Windows ones) there are neither sources nor tarballs available. Many of such applications can not be freely distributed because of license restrictions and/or lack of legal ways to obtain installer for no fee.

ℹ️ Note

All information here is package-agnostic, for information specific to the most typical non-free software see Wine package guidelines.

Rationale#

There are multiple reasons for packaging even non-packageable software:

OCaml

Mon, 01 Jan 0001 00:00:00 +0000

OCaml package guidelines#

Writing PKGBUILDs for software written in OCaml.

Package naming#

For libraries, use ocaml-modulename. For applications, use the program name. In either case, the name should be entirely lowercase.

File placement#

Libraries#

OCaml libraries should be installed under /usr/lib/ocaml. Installation in /usr/lib/ocaml/site-lib is deprecated.

OCaml libraries should be installed using ocaml-findlib. ocaml-findlib includes library metadata in the package that makes it easy to manage libraries. It is a de-facto standard and a lot of OCaml software now requires it.

PHP

Mon, 01 Jan 0001 00:00:00 +0000

PHP package guidelines#

This document covers the creation of PKGBUILDs for PHP libraries. The target audience of this document is intended to be packagers of PHP libraries. For PHP Web applications, see Web application package guidelines.

Package names#

For modules the package name should begin with php- and the rest of the name should be constructed from the library name by converting it to lowercase and separate words with hyphens. For example the package name corresponding to File iterator will be php-file-iterator.

Python

Mon, 01 Jan 0001 00:00:00 +0000

Python package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for Python software.

Package naming#

For Python 3 library modules, use python-modulename. Also use the prefix if the package provides a program that is strongly coupled to the Python ecosystem (e.g. pip or tox). For other applications, use only the program name.

ℹ️ Note

The package name should be entirely lowercase.

Architecture#

See PKGBUILD#arch.

A Python package that contains C extensions is architecture-dependent. Otherwise it is most likely architecture-independent.

R

Mon, 01 Jan 0001 00:00:00 +0000

R package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for R packages. Most information can be obtained by looking at the package’s DESCRIPTION file. You can get most of this from inside R by running tools::CRAN_package_db(). You could also visit CRAN, Bioconductor link1, and Bioconductor link2 for all the R packages’ information.

Package naming#

Packages should be named r-pkgname, where pkgname is taken from the Package field from the DESCRIPTION file. The package name should be lowercase.

Ruby

Mon, 01 Jan 0001 00:00:00 +0000

Ruby package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for software that uses ruby.

Package naming#

For libraries, use ruby-$_name (where $_name is the upstream project name). For applications, use the project name (without the ruby- prefix) and optionally add ruby-$_name to provides.

Build and tests#

Ruby packages should be built from upstream sources as this provides a transparent chain of trust for the build. To ensure integration with the existing set of Ruby packages, it is expected to run tests using ruby-rake or ruby-rspec.

Rust

Mon, 01 Jan 0001 00:00:00 +0000

Rust package guidelines#

This document covers standards and guidelines on writing PKGBUILDs for software written in Rust.

Package naming#

When packaging Rust projects, the package name should almost always be the same as the name of the generated binary. Note that it does not make any sense to package library crates, so only crates with bins will be packaged. For ones that generate more than one binary, the upstream crate name is usually appropriate. In any event the package name should be entirely lowercase.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Security package guidelines#

This page describes security packaging guidelines for Arch Linux packages. For C/C++ projects the compiler and linker can apply security hardening options. Arch Linux applies PIE, FORTIFY_SOURCE, stack protector, nx and relro by default.

Usage#

Hardening protections can be reviewed by running checksec.

$ checksec --file=/usr/bin/cat

💡 Tip

Namcap also reports some security issues described on this page.

RELRO#

RELRO is a generic mitigation technique to harden the data sections of an ELF binary/process. When a program is loaded several ELF memory sections need to be written to by the linker but can be turned read-only before turning control over to the program. This prevents attackers of overriding some ELF sections. There are two different RELRO modes:

Shell

Mon, 01 Jan 0001 00:00:00 +0000

Shell package guidelines#

Install#

For users to change shells, the shell must appear in /etc/shells. Most shell packages have install scripts like below:

post_install() {
    grep -Fqx /bin/shellname /etc/shells || echo /bin/shellname >>/etc/shells
    grep -Fqx /usr/bin/shellname /etc/shells || echo /usr/bin/shellname >>/etc/shells
}

post_upgrade() {
    post_install
}

post_remove() {
    sed -i -r '/^(\/usr)?\/bin\/shellname$/d' etc/shells
}

Shell completions#

Most shells provide a built in set of completions for a few common commands while also scanning at least one system directory for functions that may be supplied by other packages. The following table is a summary of where packages may place completion files and what the files should be named.

VCS

Mon, 01 Jan 0001 00:00:00 +0000

VCS package guidelines#

Version control systems can be used for retrieval of source code for usual statically versioned packages, and the latest (trunk) version of a development branch.

💡 Tip

Use /usr/share/pacman/PKGBUILD-vcs.proto prototype provided by the pacman package.

Package naming#

Suffix pkgname with -bzr, -cvs, -darcs, -git, -hg, -svn, etc., unless the package fetches a specific release.

Versioning#

If the resulting package is different after changing e.g. the dependencies, URL or sources — update pkgver to the latest version. If pkgver has not changed since the last update to the PKGBUILD, increase pkgrel instead.

Web App

Mon, 01 Jan 0001 00:00:00 +0000

Web application package guidelines#

This page describes how to package web applications.

Separate user#

For security reasons, every web application should be run as a separate (unprivileged) user (i.e. $pkgname).

ℹ️ Note

Traditionally, many web applications were run as the http user/group, which can be considered unsafe, as in such a scenario applications can read each other’s files.

Refer to the systemd-sysusers(8), sysusers.d(5), systemd-tmpfiles(8) and tmpfiles.d(5) man pages for details on how to create users and deal with ownership of files and folders for that user in a package.

Wine

Mon, 01 Jan 0001 00:00:00 +0000

Wine package guidelines#

Many Windows programs may still be useful in Linux and so we may want to have a package for them. The differences between the two operating systems make this task a little complex. In this guideline we will talk about Win32 binaries, since projects where source is available usually are ported to Linux.

Things to check outright#

License: does the license allow the program to be repackaged?
Installer: is it possible to install the program silently? Even better, does an installer-less version exist?
Portability and cleanness: is the program portable? It is clean?

Here we mean a program is portable if it never writes in the registry or outside its directory; we mean a program is clean if it never writes in its directory, but it may write its settings in the user folder. A program can be also both (e.g., it never writes settings) or neither (e.g., it writes in its directory, it writes around, it writes in the registry…)