Alpine Linux Aports — Package Maintainer Guide
Reference for Alpine Linux package maintainers. Covers APKBUILD format, abuild workflow, apk commands, aports contribution guidelines, and packaging best practices.
CRITICAL: grep references/ for detailed rules before answering.
Repository Structure
| Repository |
Branch |
Policy |
testing/ |
edge only |
New packages land here first. No release support. Removed after 9 months if not promoted. |
community/ |
edge + stable |
Must have maintainer and pass tests. Workflow: testing → community. |
main/ |
edge + stable |
Core system packages. Assigned developer required. Workflow: testing → community → main. |
APKBUILD Quick Reference
# Contributor: Name <email>
# Maintainer: Name <email>
maintainer="Name <email>"
pkgname=example
pkgver=1.0.0
pkgrel=0
pkgdesc="Short description"
url="https://example.com"
arch="all"
license="MIT"
depends=""
makedepends=""
subpackages="$pkgname-doc $pkgname-dev"
source="$pkgname-$pkgver.tar.gz::https://example.com/archive/v$pkgver.tar.gz"
build() {
./configure --prefix=/usr
make
}
check() {
make test
}
package() {
make DESTDIR="$pkgdir" install
}
sha512sums="..."
Key Variables
| Variable |
Required |
Notes |
pkgname |
Yes |
Lowercase only, must match directory name |
pkgver |
Yes |
Upstream version, no quotes |
pkgrel |
Yes |
Alpine revision, starts at 0 |
pkgdesc |
Yes |
Short description |
url |
Yes |
Upstream homepage |
arch |
Yes |
all, noarch, or space-separated arch list |
license |
Yes |
SPDX identifier |
depends |
No |
Runtime dependencies |
makedepends |
No |
Build-time dependencies |
checkdepends |
No |
Test-time dependencies |
subpackages |
No |
e.g. $pkgname-doc $pkgname-dev $pkgname-openrc |
source |
Yes |
Source URLs and local files |
options |
No |
e.g. !check !strip net chmod-clean |
builddir |
No |
Defaults to $srcdir/$pkgname-$pkgver |
install |
No |
Pre/post install scripts |
Build Functions (in order)
fetch — Download sources (automatic)unpack — Extract sources (automatic)prepare — Apply patches. If overridden, MUST call default_preparebuild — Compilecheck — Run testspackage — Install to $pkgdir
Common abuild Commands
abuild -r # Build package (fetch, build, check, package)
abuild checksum # Update checksums in APKBUILD
abuild -r -K # Keep builddir after build (for debugging)
abuild clean # Clean build artifacts
abuild undeps # Remove installed makedepends
newapkbuild -n pkgname # Generate new APKBUILD template
abuild rootbld # Build in clean chroot
Commit Message Format
$repository/$pkgname: action
| Type |
Template |
Example |
| New |
testing/foo: new aport |
|
| Upgrade |
main/foo: upgrade to 2.0.0 |
Sets pkgrel=0 |
| Rebuild |
community/foo: rebuild for so:libfoo.so.2 |
Bumps pkgrel |
| Move |
community/foo: move from testing |
|
| Rename |
community/bar: rename from foo |
|
| Remove |
community/foo: remove |
|
| Fix |
main/foo: fix build on aarch64 |
|
| Maintainer |
community/foo: take over maintainership |
|
Rules: lowercase after colon, no trailing dot, imperative present tense, one commit per aport.
References
references/abuild-workflow.md — Full abuild workflow: new package, upgrade (abump), build debug, patch creation, MR submission, glab commands, secfixes, subpackages, rebuild, movereferences/codingstyle.md — APKBUILD coding style (formatting, quoting, naming, metadata order)references/commitstyle.md — Full commit message policy with all types and exceptionsreferences/contributing.md — How to submit MRs/PRs, CI requirementsreferences/apk-commands.md — apk package manager command referencereferences/apk-internals.md — APKINDEX format, package structure, signing, cache
1---2name: alpine-aports-docs3description: USE THIS SKILL WHEN maintaining Alpine Linux packages (aports): writing APKBUILDs, abuild workflow, apk package management, APKINDEX format, commit/coding style, contributing to aports, package upgrade/rebuild/move/rename, subpackages, cross-compilation, secfixes, checksum handling, testing packages, or Alpine Linux packaging best practices. Triggers on: APKBUILD, abuild, apk add, apk del, aports, Alpine package, pkgname, pkgver, pkgrel.4---56# Alpine Linux Aports — Package Maintainer Guide78Reference for Alpine Linux package maintainers. Covers APKBUILD format, abuild workflow, apk commands, aports contribution guidelines, and packaging best practices.910- [aports repo](https://gitlab.alpinelinux.org/alpine/aports) | [GitHub mirror](https://github.com/alpinelinux/aports)11- [Alpine Wiki: Creating APKBUILD](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package)12- [Alpine Wiki: APKBUILD Reference](https://wiki.alpinelinux.org/wiki/APKBUILD_Reference)1314CRITICAL: grep `references/` for detailed rules before answering.1516## Repository Structure1718| Repository | Branch | Policy |19|------------|--------|--------|20| `testing/` | edge only | New packages land here first. No release support. Removed after 9 months if not promoted. |21| `community/` | edge + stable | Must have maintainer and pass tests. Workflow: `testing → community`. |22| `main/` | edge + stable | Core system packages. Assigned developer required. Workflow: `testing → community → main`. |2324## APKBUILD Quick Reference2526```sh27# Contributor: Name <email>28# Maintainer: Name <email>29maintainer="Name <email>"30pkgname=example31pkgver=1.0.032pkgrel=033pkgdesc="Short description"34url="https://example.com"35arch="all"36license="MIT"37depends=""38makedepends=""39subpackages="$pkgname-doc $pkgname-dev"40source="$pkgname-$pkgver.tar.gz::https://example.com/archive/v$pkgver.tar.gz"4142build() {43 ./configure --prefix=/usr44 make45}4647check() {48 make test49}5051package() {52 make DESTDIR="$pkgdir" install53}5455sha512sums="..."56```5758### Key Variables5960| Variable | Required | Notes |61|----------|----------|-------|62| `pkgname` | Yes | Lowercase only, must match directory name |63| `pkgver` | Yes | Upstream version, no quotes |64| `pkgrel` | Yes | Alpine revision, starts at 0 |65| `pkgdesc` | Yes | Short description |66| `url` | Yes | Upstream homepage |67| `arch` | Yes | `all`, `noarch`, or space-separated arch list |68| `license` | Yes | SPDX identifier |69| `depends` | No | Runtime dependencies |70| `makedepends` | No | Build-time dependencies |71| `checkdepends` | No | Test-time dependencies |72| `subpackages` | No | e.g. `$pkgname-doc $pkgname-dev $pkgname-openrc` |73| `source` | Yes | Source URLs and local files |74| `options` | No | e.g. `!check` `!strip` `net` `chmod-clean` |75| `builddir` | No | Defaults to `$srcdir/$pkgname-$pkgver` |76| `install` | No | Pre/post install scripts |7778### Build Functions (in order)79801. `fetch` — Download sources (automatic)812. `unpack` — Extract sources (automatic)823. `prepare` — Apply patches. If overridden, MUST call `default_prepare`834. `build` — Compile845. `check` — Run tests856. `package` — Install to `$pkgdir`8687### Common abuild Commands8889```sh90abuild -r # Build package (fetch, build, check, package)91abuild checksum # Update checksums in APKBUILD92abuild -r -K # Keep builddir after build (for debugging)93abuild clean # Clean build artifacts94abuild undeps # Remove installed makedepends95newapkbuild -n pkgname # Generate new APKBUILD template96abuild rootbld # Build in clean chroot97```9899## Commit Message Format100101```102$repository/$pkgname: action103```104105| Type | Template | Example |106|------|----------|---------|107| New | `testing/foo: new aport` | |108| Upgrade | `main/foo: upgrade to 2.0.0` | Sets pkgrel=0 |109| Rebuild | `community/foo: rebuild for so:libfoo.so.2` | Bumps pkgrel |110| Move | `community/foo: move from testing` | |111| Rename | `community/bar: rename from foo` | |112| Remove | `community/foo: remove` | |113| Fix | `main/foo: fix build on aarch64` | |114| Maintainer | `community/foo: take over maintainership` | |115116Rules: lowercase after colon, no trailing dot, imperative present tense, one commit per aport.117118## References119120- `references/abuild-workflow.md` — Full abuild workflow: new package, upgrade (abump), build debug, patch creation, MR submission, glab commands, secfixes, subpackages, rebuild, move121- `references/codingstyle.md` — APKBUILD coding style (formatting, quoting, naming, metadata order)122- `references/commitstyle.md` — Full commit message policy with all types and exceptions123- `references/contributing.md` — How to submit MRs/PRs, CI requirements124- `references/apk-commands.md` — apk package manager command reference125- `references/apk-internals.md` — APKINDEX format, package structure, signing, cache
wenerme