apkg config¶

apkg looks for config file distro/config/apkg.toml.

Please see distro/config/apkg.toml for up-to-date example.

This document describes apkg compat level 4 config options.

[project]¶

The primary config section containing project-specific settings.

project.name¶

By default, project name is guessed from project dir name but that can break easily when the project dir is renamed so it's better to specify it explicitly in using project.name

[project]
name = "banana"

This is available to templates through {{ project.name }}.

project.make_archive_script¶

In order to create packages from your project source, apkg requires a script which creates archive from current project state.

The script MUST return the path to created archive on the first line of its stdout.

The created archive MUST contain version string, for example:

banana-v1.2.3.tar.gz

The script MAY output additional files (such as signatures) and print their paths on individual stdout lines after the main archive.

Tip

The script SHOULD create archives with unique version strings for individual VCS commits if using VCS. This isn't strictly required by apkg, but it will save you a lot of conflicts and needless work later on.

Include such script in your project and then point to it using make_archive_script:

[project]
make_archive_script = "scripts/make-archive.sh"

Most projects which use apkg have the script in scripts/ directory for historic reasons, but feel free to put it into distro/scripts/ or anywhere else you want.

Tip

It's strongly recommended to reuse the same script in the upstream archive creation during official release so that this code gets properly tested on regular basis - it's used on most apkg operations.

make_archive_script examples in the wild:

[upstream]¶

Config section for project upstream settings.

upstream.archive_url¶

To easily download upstream archives using apkg you can specify upstream.archive_url with templating available including special version variable:

[upstream]
archive_url = "https://banana.proj/dl/{{ project.name }}/{{ project.name }}-{{ version }}.tar.xz"

upstream.signature_url¶

Optional signature file to download alongside upstream archive.

upstream.version_script¶

If default upstream version auto-detection from HTML listing of files at upstream.archive_url parent doesn't work for your project or you want full control over the process, you can create a custom executable script which prints current upstream version to stdout and tell apkg to use it with upstream.version_script option:

[upstream]
version_script = "scripts/upstream-version.py"

This option overrides default auto-detection mechanism.

script example: scripts/upstream-version.py

[apkg]¶

Config section for apkg settings.

apkg.compat¶

In order to allow config file format changes without breaking compatibility, it's strongly recommended to include current apkg compat level in the config file.

That way, apkg will be able work with old and new formats without disruption in the future.

current apkg compat level: 4

[apkg]
compat = 4

[distro]¶

Config section for distro settings.

distro.aliases¶

A list of custom distro aliases.

[[distro.aliases]]
name = "deb-old"
distro = ["debian <= 9", "ubuntu < 20.04"]

[[distro.aliases]]
name = "el-8"
distro = ["rocky == 8", "centos == 8", "rhel == 8"]

[template]¶

Config section for package template settings.

template.ignore_files¶

A list of unix-style file name patterns to select files which should be ignored/skipped during template render.

When not specified, following defaults are used:

[template]
ignore_files = ['.*']

To render all files instead of using defaults, simply set to an empty list:

[template]
ignore_files = []

template.plain_copy_files¶

A list of unix-style file name patterns to select files which should be copied over without templating during template render.

This option is overriden by template.ignore_files - when a file matches both ignore_files and plain_copy_files, it will be ignored.

When not specified, following defaults are used:

[template]
plain_copy_files = ['*.patch']

To template all files instead of using defaults, simply set to an empty list:

[template]
plain_copy_files = []

template.variables¶

A list of custom template variables sources.

Example:

[[template.variables]]
python_module = "apkg.templatevars.debseries"

[[template.variables]]
local_module = "distro/vars/custom_vars.py"

See custom template variables for more info.

[cache]¶

Config section for cache control.

cache.source¶

Set to true or false to enable or disable cache for operations on project source files such as make-archive and srcpkg commands.

Project MUST be maintained in VCS (git) in order to enable cache.source.

When cache.source = true but VCS isn't available, apkg will compain with a warning and disable it.

cache.local¶

Set to true or false to enable or disable cache for operations on local files such as srcpkg and build commands.

cache.local is enabled by default:

[cache]
local = true

cache.remote¶

Set to true or false to enable or disable cache for operations on remote files such as get-archive command.

cache.remote is enabled by default:

[cache]
remote = true