Chapter 1. Preparing Your System

Table of Contents

Installing Development Software
Using apk to Install Software
Installing the Adélie Linux Development System
Components of the Adélie Linux Development System
Packaging Primer
Packages and Repositories
Using the abuild Command
abuild Subcommands
Configuring Your System
Configuring abuild for Your Environment

Welcome to the Adélie Linux 1.0 Developer's Handbook. This handbook will teach you how to develop the software and packages that powers the Adélie Linux distribution. You may follow along at your own pace.

We'll start with installing the software and writing the configuration files necessary to perform development.

In this section, you will learn:

  • How to install software on Adélie Linux;

  • What software you will use to develop Adélie Linux; and

  • What task each utility in the Adélie Linux development system performs.

Please make sure that you are at an Adélie Linux terminal before continuing.

The apk package manager is the central software management tool on the Adélie Linux distribution. For a more thorough introduction to the apk package manager, please consult the Adélie Linux 1.0 Administrator's Guide, chapter 3: "Packages".

The apk package manager automatically resolves dependencies for requested software packages, and will automatically remove or "clean up" unneeded dependencies when a software package is removed. If a software package's files become corrupted, it can be reinstalled with the fix subcommand.

The add subcommand will add the specified package(s) to the system's list of packages, and then resolve all necessary dependent libraries and other software packages to ensure the system has the requested packages installed. The del subcommand will remove the specified package(s) from the system's list of packages, and then remove any other libraries and software packages that are no longer required for the system's operation. For example, the command:

# apk add build-tools

will install the build-tools package, and any packages and libraries it requires. Similarly,

# apk del libressl-dev

will remove the libressl-dev package, and any packages and libraries that it required and no other package on the system requires.

The development environment is made of two essential parts: the build-tools package, which provides the basic compiler infrastructure, including a C compiler, build system, linker, assembler, and other utilities; and the abuild package, which takes package "recipe" files with build instructions, and creates the APK package files using them. You may install these two packages by executing the following command:

# apk add abuild build-tools

The development system uses many open-source technologies that work together to provide a responsive, cohesive, libre environment.

Development System Components

abuild (abuild)

Builds APK package files from APKBUILD package "recipe" files.

autoconf (autoconf)

The GNU package for generating ./configure scripts in packages that require them to be generated.

automake (automake)

The GNU package for generating Makefiles in packages that use the autoconf package.

bash (bash, sh)

A Unix shell mostly compliant with the POSIX™ standard, used by many packages for build scripts and testing.

binutils (as, ld, nm, …)

Low-level development utilities including assembler (as), linker (ld), and others.

bzip2 (bzip2, bunzip2, bzless, …)

A popular compression format, included for the ability to unpack .bz2 archives within which packages may be distributed.

cmake (cmake, ctest)

The CMake build system, used to build many packages, and the CTest test system, used to prove packages are functioning correctly on the local system.

diffutils (diff, cmp)

Compares two or more files together, showing the differences. Used by many test suites, and also useful for troubleshooting and generating .patch files.

gcc (c99, c11, gcc, g++)

The GNU Compiler Collection, a mostly standards-compliant C and C++ compiler.

git (git)

A distributed version control system used by many projects to keep a record of file history; the current distribution method for Adélie's package repository.

gzip (gzip, gunzip)

A popular, long-standing compression format, included for the ability to unpack .gz archives within which packages may be distributed.

libarchive (cpio, tar)

tar allows creation of APK files and extraction of a popular archive format; cpio is used to create the initial boot disk for CD images.

libtool (libtool)

The GNU library manipulation tool, used by many packages to create shared (.so) and static (.a) library files.

make (make)

The GNU version of the standard Unix make command.

mawk (awk)

A POSIX™ compliant implementation of the AWK programming language.

openssl (openssl)

A command to sign packages cryptographically, ensuring they are not tampered with when a user downloads them.

patch (patch)

The GNU version of Larry Wall's standard patchutility.

pkgconf (pkgconf, pkg-config)

A freely licensed, mathematically proven pkg-config implementation, used by package build systems to determine the location of libraries on the system.

sed (sed)

The GNU version of the Unix sed command.

xz (xz, unxz)

An efficient compression format, included for the ability to unpack .xz archives within which packages may be distributed.

In this section, you will learn:

  • How repositories and packages work in the Adélie Linux distribution;

  • How to use the abuild command; and

  • The options and commands available in abuild.

The abuild command enables you to build a package file for later installation on to one or more computers running the Adélie Linux dsitribution. A package file is a kind of archive file that contains two key parts: package metadata, and package content files.

Package metadata is a collection of information used by a package manager, such as apk, to determine information about the package and the package file, including its name, version, maintainer contact information, installed size on disk, and more. The package content files are a collection of one or more files that comprise the package itself, including executables, default configuration, data files, and any other files needed for the package to work properly. In some cases it may also include templates, examples, or documentation.

All packages belong to a package repository or repo. A repository is a collection of related packages. The Adélie Linux distribution has two main repositories: the system repository, used for system software and important libraries; and the user repository, used for the majority of packages that users may be interested in. While you are developing on your own computer, you may have as many, or as few, repositories as you like. It can use any name except the above two ('system' and 'user'). You may use a name such as mypackages, or just your username. Your repository is named after the directory where it is stored on your computer's hard disk. You may create it anywhere, but it is highly recommended that you store your repository as a subdirectory of your home directory (/home/yourname/yourrepository).

Each package you create will have its own directory inside your repository. If you use the newapkbuild command (discussed later), this will be created for you automatically. Inside this directory will be at least an APKBUILD file, which tells abuild the commands to run to build the package. It may also contain patches or other files required for building the package, if necessary.

Typically, the abuild command is executed inside the package's directory (for example, /home/yourname/mypackages/pkgname). However, by setting the APKBUILD environment variable to the absolute path on disk to an APKBUILD file, you may run abuild from any directory.

Running the abuild command with no arguments in a directory containing an APKBUILD file will cause it to fetch the package's sources (if necessary), build the package, and create the package file. Passing the -r parameter to abuild will cause it to install the dependencies of the package as listed in the APKBUILD, and then build the package. Afterwards, the dependencies of the package that were not already installed on your computer are removed. If the build concluded successfully, the directory tree created for the source code and build system are removed by default. If the build fails to conclude successfully, no directories are removed by default. You may configure what abuild removes when a package concludes building; refer to the section called “Configuring abuild for Your Environment” for more information.

abuild has many subcommands that you may use, for finer-grained control over the build process. You may use the abuild deps subcommand to only install the dependencies of the package, and use the abuild unpack subcommand to unpack the source archive into the directory tree where it can later be built. These and many other subcommands are described in more detail in the following section.

There are additionally a number of options that you may pass to abuild, which are also described in more detail in the next section.

The abuild command provides many subcommands that you may use while packaging software.

checksum

This subcommand instructs abuild to recreate the checksum lines at the end of the APKBUILD. This is typically used when "bumping" or upgrading the software package (which causes it to have new source code). It is also used when creating, modifying, or removing patches from the package.

fetch

This subcommand instructs abuild to fetch external source(s) specified in source to the SRCDEST specified in your abuild.conf, and ensure they match the checksum(s) specified in the APKBUILD. The default SRCDEST is /var/cache/distfiles.

unpack

This subcommand instructs abuild to unpack the archive files specified in source to the source directory. For instance, if source contained "https://my-package.org/foobar-1.2.zip", the contents of "foobar-1.2.zip" would be extracted to the source directory.

prepare

This subcommand instructs abuild to run the prepare() function from the APKBUILD. If no prepare() is provided in the APKBUILD, abuild will run a default prepare() which will apply all patches specified in source to the source tree.

build

This subcommand instructs abuild to run the build() function from the APKBUILD.

package

This subcommand instructs abuild to run the package() function from the APKBUILD.

rootpkg

This subcommand instructs abuild to run the package() function, any split functions, and then create the APK files.

In this section, you will learn:

  • How to configure abuild for your environment;

  • How to create and use package signing keys; and

  • The directory layout used by abuild and how to create it.

Please make sure that you are at an Adélie Linux terminal before continuing.

The abuild system reads its configuration from two files on your system, if they exist. The /etc/abuild.conf file contains system-wide configuration, used by all users on a system. The $HOME/.abuild/abuild.conf contains user-specific configuration, including the packager name and key pair path. This allows multiple users to create their own repositories on a single system. Configuration set in the /etc/abuild.conf will apply to all packages on the system unless overridden by the user-specific configuration file.

The most common configuration variables are explained below. For a list of all available configuration variables, consult the abuild.conf(5) manual page by running man 5 abuild.conf on a computer where the abuild-doc package is installed.

abuild.conf Configuration Variables

CFLAGS

CFLAGS contains the flags passed to the C compiler. For more information about available flags, consult the documentation for your compiler.

CXXFLAGS

CXXFLAGS contains the flags passed to the C++ compiler. If CXXFLAGS is not set, and CFLAGS is set, then CXXFLAGS is set to the value of CFLAGS.

CPPFLAGS

CPPFLAGS contains the flags passed to the C and C++ preprocessors.

LDFLAGS

LDFLAGS contains the flags passed to the linker. For more information about available flags, consult the documentation for your toolchain (likely binutils).

JOBS

JOBS should be set to the number of concurrent build processes you would like to run on your system. Most dedicated build servers use a number equal to the number of CPU cores.

MAKEFLAGS

MAKEFLAGS contains the flags passed to make. The default value is -j$JOBS. For more information about available flags, consult the documentation for make.

USE_COLORS

USE_COLORS controls whether or not the abuild command will output colours to the terminal. If you prefer a colourless output, or your terminal is not capable of ANSI colour codes, set this to 0. The default value is 1.

SRCDEST

SRCDEST should be an absolute path where source files are downloaded. The default, and typical, value is /var/cache/distfiles.

REPODEST

REPODEST should be an absolute path where finished packages are placed when built. The default is $HOME/packages/.

PACKAGER

The value of PACKAGER is added to every produced package as the person responsible for packaging it. Typically, this follows an RFC822-style "Name <Email Address>" format. There is no default value; it must be set before running abuild.

PACKAGER_PRIVKEY

PACKAGER_PRIVKEY should be an absolute path to the packager's private key, which will be used to sign every produced package. Typically, this is set for you by the abuild-keygen command. There is no default value; it must be set before running abuild.

MAINTAINER

The value of MAINTAINER is used as a point of contact if a user has an issue with a package, or if a security patch or update is available for the patch. Typically, this follows an RFC822-style "Name <Email Address>" format. The default value is the value of PACKAGER.

CLEANUP

CLEANUP controls the cleanup procedure after a build that concludes with success. The default value is srcdir pkgdir deps.

ERROR_CLEANUP

ERROR_CLEANUP controls the cleanup procedure after a build that concludes with failure. The default value is deps.

DEFAULT_DBG

DEFAULT_DBG controls whether a debug package will be created for compiled packages. It is unset by default; being set to any value enables the option. The typical value to enable the option is YesPlease.