Introduction and Rationale

The AOSC OS ABBS Tree is now home to over 5000 (and counting) packages, which are maintained by over 20 (historical and current) packagers. With more than 5 years of history behind some packages, issues began to emerge in the following fashion:

• Packages lack dependencies.
• Insecure (unquoted) variables in build scripts.
• Hard-to-read build scripts, with little comments or indication of progression.
• Undescriptive package description(s) ($PKGDES).
• Non-standard package section(s) ($PKGSEC).
• ...

Without a comprehensive guildeline for packaging work in the future, these issues will not go away - rather, the list will grow longer and further degrade package qualities in our distribution. This Styling Manual seeks to provide sectioned and targetted sets of guidelines for fixing existing and new packages.

Packager, Package Names, and Descriptions

This section contains the three most basic descriptors for an AOSC OS package.

Packager Information

Packager, or "Maintainer", as referenced in Debian Packages (.deb), should have its value formatted as follows:

Executed Packager <[email protected]>

Package Names

Package names (PKGNAME=, or $PKGNAME) should be lower-cased, and otherwise comply with the choice of package manager.

Descriptions

Package descriptions (PKGDES=, or $PKGDES) are to be composed with the following guidelines:

• Start with a upper-case letter.
• With no period point or any punctuation mark at the end.

However, it is worth noting that package descriptions found with AOSC OS packages should be descriptive, but not definitive. For example, an acceptable package description should look something like...

"Library with common API for various MATE modules"

Or less descriptive, like...

"MATE Desktop Library"

Or too definitive, like...

"Library with concise and convenient API for various MATE modules"

Package Specs

In the current implementation of ACBS (Autobuild CI Build Service), three categories of variables are defined in a file named spec - these variables will be discussed below.

Versioning Variables

Versioning variable define the package's version and revision levels.

VER=

The VER=, or $VER variable defines the main version of the resulting package. When packaging for AOSC OS, packagers should take note of the following requirements. These requirements are presented in the table below.

REL=

The REL=, or $REL variable defines the revision level of the resulting package. This variable should only hold a single positive integer as its value.

Source Variables

Source variables define the package's source(s), and in the case of a VCS (version control system) based source, define in addition a specific source snapshot.

SRCTBL=

The SRCTBL=, or $SRCTBL variable is used when a package's source is released in the form of a single compressed archive. Requirements and recommendations are presented in the table below.

CHKSUM=

The CHKSUM=, or $CHKSUM variable is used in conjunction with $SRCTBL, to define the proper checksum for specific source archive(s). The format is as follows.

CHKSUM="$ALGORITHM::$CHECKSUM"

Where...

• $ALGORITHM is to be replaced with specific hashing algorithms, written in lower-case. For instance, sha256.
• $CHECKSUM is to be replaced with the corresponding hash checksum of the aforementioned algorithm.

For descriptions of different cryptographic hash algorithms, and for identification of insecure (and therefore unacceptable) algorithms, refer to this Wikipedia chapter under "Cryptographic Hash Function".

$CHKSUM will become a required value in the near future.

VCS Variables

VCS (Version Control System) based sources may use any one of the each combinations.

DUMMYSRC=

The DUMMYSRC=, or $DUMMYSRC variable is used when a package is empty (meta package), or uses custom-generated sources. This variable takes a bolean value.

Other Variables

Other variables may be used, so long as they are not any of the variables listed above. These variables are often used to aid with manipulating $SRCDIR, here's the spec file of extra-devel/netbeans, for instance.

VER=8.2
REL=1
SUB=201609300101
SRCTBL="http://download.netbeans.org/netbeans/$VER/final/zip/netbeans-$VER-$SUB.zip"
SUBDIR=.

Dependencies

In the context of AOSC OS packaging, dependencies are arranged in two categories: run-time depedencies, and build-time dependencies. These dependencies are defined by PKGDEP= ($PKGDEP), and BUILDDEP= ($BUILDDEP), respectively.

Run-time Dependencies

Run-time dependencies should be written in such a way that, not only does the package function (programs run, libraries link, etc.), all linkages to the package should also be included. In the case of extra-multimedia/ario, for instance, not only should $PKGDEP contain the following dependencies:

avahi, curl, dbus-glib, gnutls, hicolor-icon-theme, libglade, libmpdclient, libnotify, libsoup, libunique, taglib, xdg-utils

Which, through explicit and implicit dependencies, allows for a system environment that contains sufficient runtime for the program /usr/bin/ario to function.

By the quality assurance standard, defined in code E432, all direct dependencies on the ELF level should also be included in $PKGDEP, and thus the addition of dbus to $PKGDEP is necessary.

As of March 16th, 2019, 42.4% (1592/3705) of all packages provided in the Stable channel for amd64 has the issue of insufficient ELF dependencies.

Additional Notes

• When a package has a sole dependency on the GCC Runtime (gcc-runtime) or the GNU C Library (glibc), these dependencies should be included in $PKGDEP.

Build-time Dependencies

Build-time dependencies should written in such a way that the package will compile, install, and package successfully in the BuildKit build environment. Given this, any packages included in the BuildKit environment will not need to be included in $BUILDDEP. For example...

• CMake (cmake) is required for building extra-devel/extra-cmake-modules, however, cmake is an integral part of BuildKit. Therefore, packagers are not required to include cmake in $BUILDDEP.
• Bazel (bazel) is required fo building extra-scientific/tensorflow. In this case, bazel must be included in $BUILDDEP, as bazel is not installed in BuildKit as standard.

Package Features

When packaging for AOSC OS, please work in accordance to our distribution feature guide. The table below digests some of the common considerations when building packages for AOSC OS.

Scripting

While most packages could be built with one of the pre-defined Autobuild Types ($ABTYPES), and that patches could be applied automatically from the autobuild/patches directory (or via a pre-defined series file to specify patch order), some packages require manual preparation, patching, and build. This section is dedicated to prepare, patch, build, and beyond under the autobuild/ directory.

A general rule of thumb is to write such scripts secure (quoted) variables, sufficient comments, error control, architectural considerations, progression report, ... Writing easy-to-read and reliable build scripts is not easy, and the table below aims to aid you with making good scripting decisions.

As many packagers tend to reference or copy build scripts from Arch Linux, please reference the TODO: AOSC OS-Arch Rosetta Stone for a comprehensive guide on translating PKGBUILD (Arch Linux) into Autobuild3 manifests (AOSC OS).

Patch Naming

Patches should follow a (mostly) uniform file naming for clear arrangement and sorting, before they are included in autobuild/patches/.

Git-based Sources

When dealing with Git-based sources, it is possible to create numbered patches from the following command:

git format-patch -n $HASH

Where n defines the amount of commits from the specific commit $HASH, including the specified commit. Alternatively, you can omit the $HASH...

git format-patch -n

To create a series of patches from n commits to the branch HEAD.

These commands generate a series patches like the following...

0001-contrib-autobuild-aoscarchive-one-more-syntax-fix.patch
0002-common_switches-add-sanitizer-support.patch
0003-contrib-autobuild-aoscarchive-fix-overlay-subdir-che.patch
0004-arch-_common_switches-fix-syntax.patch
0005-autobuild-aoscarchive-adapt-to-new-workflow.patch

Other Sources

Without an automatic mean to generate patches, patches should be named in the following format.

NNNN-$CATEGORY-$CONTENT.patch

Where:

• NNNN, like the sample patch file names, is a "serial" number for sorting patches.
• $CATEGORY defines the category of a patch, for instance, bugfix, feature, etc.
• $CONTENT defines "what is to be done" when a patch is applied, for instance, fix-build-with-openssl-1.1.

Likewise, when including patch(es) from other distributions, they should also be renamed in accordance to the guidelines above.

File Placements

AOSC OS, like many other Linux Distributions, expect packaged files to be located in appropriate directories. Please reference the non-comprehensive table below for our standard of file placements.

Electron and Chromium-based Packages

Electron, Chromium, and other Chromium-based packages should be packaged with the following structure.

Binary Packaging (Binpack)

Binary packages should not be installed to /opt, unless the package's licence prohibits such file movement. With adjustments and other modifications, these packages should be installed to the /usr prefix - if packager find it impossible, they should consider rejecting such packages.

Git Commit Messages

When committing (or contributing, if you like) to the AOSC OS ABBS Tree, please observe the commit message standards, shown in the table below.

Long Messages

When more than one of the actions were committed, and that the short message goes beyond 50 characters (including space and punctuation marks), you should utilise a "long Git commit message", for example:

firefox: update to 64.0.2; #1536
    
    - Enable PGO on AMD64, patches from Fedora and upstream.
    - Clean up defines.
    - Remove deprecated --enable-pie option.
    - More vendor-specific preferences to further limit Pocket integration and telemetry.