gpak(1) General Commands Manual gpak(1)

gpak - build Debian packages from PKGBUILD repositories

gpak [options...] [packages...]

gpak automates building binary Debian packages from PKBUILD source scripts. gpak reads PKGBUILD scripts from repositories of source packages. Each source package resides in a separate directory with at least one PKGBUILD file inside. For example: 

.
├── package1
│   └── PKGBUILD
├── package2
│   ├── PKGBUILD
│   └── PKGBUILD.sid
└── package3
    ├── changelog.Debian
    ├── copyright
    ├── PKGBUILD.bullseye
    └── PKGBUILD.bookworm

By default gpak treats its current working directory as a root of package repository, Using --packages-dir option changes that and allows running gpak from a different directory than repository root. Gpak builds all packages found in the repository, unless the list of wanted packages is narrowed down by passing a packages list.

To build packages, gpak uses OSI containers through docker commands. Gpak builds in a sandboxed environment and for different distributions. Once built, gpak copies packages to a directory which is available on a host and automatically accessible for the user who runs the gpak command. Output Output directories for packages are located inside a build directory (see: --build-dir).

-b, --build-dir=DIRECTORY
Change the directory where gpak stores build artifacts. This includes built packages, logs and Docker Context.

-d, --distribution=NAME

Build packages for specified distributions. This switch may be used many times to set many different distributions. Its existence overwrites DISTRIBUTIONS (plural form) configuration variable (see: CONFIGURATION).

When building a package for a specific distribution, gpak prefers distribution-specific PKGBUILD files, with extension the same as a distribution name, for example PKGBUILD.sid. If distribution-specific PKGBUILD file doesn't exist, then gpak will select ordinary PKGBUILD file for package source.

Name of currently built distribution is propagated to the environment in which gpak executes PKGBUILD. It is accessible as GPAK_DISTRO environment variable. As such, it doesn't rely on the output of lsb_release(1) command.

-r, --remote-path=PATH

Destination path to which packages are sent (see: --send). Remote path must conform to the rsync URL format, which typically is [USER@]HOST[:PORT]:DEST. See rsync(1) for details.

--clean

Remove a build directory before building anything. This enforces rebuilding container images.

-p, --packages-dir=DIRECTORY

Change package repository root directory. If not specified, current working directory is used.

--docker-context

Directory which contains Docker Context files. See DOCKER CONTEXT section below for details.

--build-docker, --no-build-docker

Enable or disable building container images. It is enabled by default.

--build, --no-build

Enable or disable building packages. It is enabled by default.

--lint, --no-lint

Enable or disable running lintian for the built packages. Lintian runs before sending packages (see: --send), but it doesn't stop gpak's pipeline when it fails (i.e. packages will be sent anyway). This step is disabled by default. See also: lintian(1).

--send, --no-send

Enable or disable sending packages to the remote repository configured with --remote-path. rsync(1) is used to transfer files to remote hosts. Only currently selected packages be sent, however if there are many versions of single package, typically from previous builds, then all of them will be sent.

Gpak will refuse sending unsafe packages, i.e. the ones which aren't built inside a container (--build-local) or with cache enabled (--cache). To send them anyway, --force switch should be used.

By default sending packages is disabled.

-l, --build-local

Don't build packages insie the container, but build them locally (on the host).

This option is unsafe because local environment can have unpredicted side effects on build process. When it's enabled, gpak will refuse to send packages to remote hosts. Using --force switch sends packages anyway.

Using this option requires makedeb(8) program installed on the host system.

By default, packages are built inside the containers (this switch is disabled).

--cache

Keep containers after build and reuse them for future builds.

Normally containers used for package building are ephemeral: gpak creates a new one before build and removes it after. This option saves package containers for future builds of particular package. Note however that containers are never shared between packages.

This option is unsafe because old builds might leave artifacts inside cached containers which may cause side effects for any future builds. Because of that, gpak will refuse to send packages built in cached containers. Using --force switch sends packages anyway.

-f, --force

Force sending packages after local and cached builds.

--ugly

Don't hide output behind pretty spinners but print it to the console. This also disables collecting output in a log file inside a build directory.

--emoji, --no-emoji

Use or don't use emoji glyphs for prettier output. By default gpak uses emoji glyphs.

--version

Show version of gpak.

-h, --help

Show help message.

All OPTIONS can be set in a configuration file. Gpak's configuration is a Bash script which defines gpak options in the UPPERCASE_SNAKE_CASE format. Following rules apply:

•options which accept an argument are set by assigning a desired value to it.
•boolean switches are set to either value 1 (switch enabled) or 0 (switch disabled). If there's a "--no-" equivalent of boolean switch (e.g. --build and --no-build), then assigning a value 0 to the positive name is the same as choosing the "--no-" form.
•options which can be specified many times are defined in the plural form of the original option name. They are assigned an array of options.

Options in configuration file have precedens over gpak's default values for options. Options passed directly to gpak during its invocation have precedence over options set inside configuration file.

Gpak searches the following paths for configuration file and uses the first one found:

•${XDG_CONFIG_HOME}/gpak/config
•${HOME}/.config/gpak/config
•/etc/gpak/config 

PACKAGES_DIR="${HOME}/packages"
SEND=1
LINT=0
DISTRIBUTIONS=( bullseye bookworm )

Using --docker-context option changes the default Docker Context directory. It holds a source code and instructions (Dockerfile_) for building base container images in which packages are built. Normally it isn't necessary to change it, unless a custom, specialized image is needed, for example one with a different set of packages which are built by default.

Users should be very careful when providing their own Docker Contexts. Preferably they should copy-paste default gpak's Docker Context, or inherit through a FROM: Dockerfile's clause. Some gpak's features are tightly coupled with how containers are run.

Gpak preprocesses files inside the Docker Context and saves them to a build directory. First, Docker Context is copied into the build directory. Then, gpak finds all files which end with the .in extension and substitutes certain variables in them(see Docker Context Variables below). .in extension is stripped from the resulting files. Once all files are preprocessed, gpak builds the image.

The following variables are preprocessed and changed by gpak before the container image is built:

•@CODENAME@ - replaced with the value of currently processed distribution name (see: --distribution)

Below is a typical safe session with gpak, which allows inspecting packages at user's pace: 

$ gpak --clean --no-send --lint -d sid mypackage
$ dpkg-info build/gpak/sid/mypackage/*.deb
$ dpkg-deb -c build/gpak/sid/mypackage/*.deb
$ gpak --send --no-build-docker --no-build -d sid mypackage

However, when developing new packages, using "unsafe" options should allow faster iterations:

$ gpak --build-local --lint mypackage
$ gpak --cache --no-build-docker mypackage

makedeb(8), PKGBUILD(5), docker(1), dpkg(1), lintian(1), rsync(1)

Michał Góral <dev@goral.net.pl>

Source code: https://git.goral.net.pl/gpak.git

2023-04-03