path: root/man/apkg.8

.\" -*- mode: troff; coding: utf-8 -*-
.TH APKG 8
.SH NAME
apkg \- Alice Linux package build and install tool
.SH DESCRIPTION
.LP
\fBapkg\fR is the package manager for Alice Linux. It builds packages from source
using \fIabuild\fR recipe files and installs them through the \fBspm\fR(8) backend.

It operates in two modes: when given a package name, it locates the recipe in
\fBAPKG_REPO\fR and processes it; when run from inside a package directory, it
uses the \fIabuild\fR file in the current directory directly.

The build pipeline is: fetch sources \f[R] checksum verification \f[R] extract
\f[R] auto-detect build system \f[R] patch \f[R] compile \f[R] post-process
(strip, compress man pages, remove conflicts) \f[R] package into \fI.spm\fR
format \f[R] install/upgrade via \fBspm\fR.

.SH OPTIONS
.TP
\fB\-h\fR
Print help and exit.
.TP
\fB\-i\fR \fI<pkg...>\fR
Build and install package(s). Skips packages already installed. Does not
resolve dependencies; use \fB\-I\fR for that.
.TP
\fB\-I\fR \fI<pkg...>\fR
Install package(s) with all dependencies resolved recursively. Prompts for
confirmation unless \fBAPKG_NOPROMPT\fR is set.
.TP
\fB\-u\fR \fI<pkg...>\fR
Upgrade (rebuild and reinstall) package(s). Skips packages not currently installed.
.TP
\fB\-U\fR
System upgrade. Checks all installed packages for outdated versions, resolves
dependencies for the full upgrade set, installs new packages first, then
upgrades existing ones. Respects \fBAPKG_MASK\fR.
.TP
\fB\-f\fR
Force rebuild even if an existing \fI.spm\fR package file is found.
.TP
\fB\-r\fR \fI<pkg...>\fR
Remove (uninstall) package(s) via \fBspm \-r\fR. Requires root.
.TP
\fB\-o\fR \fI<pkg...>\fR
Download sources only; do not build or install.
.TP
\fB\-d\fR \fI<pkg>\fR
List direct dependencies of a package (from its \fIdepends\fR file).
Respects \fBAPKG_ALIAS\fR.
.TP
\fB\-D\fR \fI<pkg...>\fR
List all dependencies recursively in install order (dependencies before
dependents). Detects and skips dependency cycles.
.TP
\fB\-j\fR \fI<pkg>\fR
List reverse dependencies \-- packages that list the given package in their
\fIdepends\fR file.
.TP
\fB\-p\fR \fI<pkg>\fR
Print the filesystem path to the package's recipe directory. Searches each
directory in \fBAPKG_REPO\fR in order; the first match wins.
.TP
\fB\-s\fR \fI<pattern>\fR
Search for packages by name across all configured repos. With \fB\-v\fR, also
prints the version from the \fIabuild\fR file.
.TP
\fB\-S\fR \fI<pattern>\fR
Search package file lists (the \fI.files\fR files in each repo) for a pattern.
Prints the repo path and matching filename.
.TP
\fB\-a\fR
List all installed packages. With \fB\-v\fR, also prints the installed version.
.TP
\fB\-l\fR
List outdated packages by comparing each installed package's version against
the version available in the repo. Respects \fBAPKG_MASK\fR.
.TP
\fB\-g\fR \fI<pkg>\fR
Generate or update the \fI.shasum\fR checksum file for the package's source files.
Uses \fBsha3sum\fR by default.
.TP
\fB\-k\fR \fI<pkg>\fR
Regenerate the \fI.files\fR file listing from the built \fI.spm\fR package.
.TP
\fB\-t\fR \fI<pkg...>\fR
Run post-install triggers: fontconfig cache, GDK-Pixbuf loaders, GIO modules,
GSettings schemas, GTK2/GTK3 input method modules, icon theme cache, udev
hardware database, X font indices, desktop MIME cache, and shared MIME database.
Only triggers that are relevant to the package's installed files are executed.
With no arguments, triggers all installed packages.
.TP
\fB\-v\fR
Verbose output. Affects \fB\-s\fR (show versions), \fB\-a\fR (show versions),
and \fB\-l\fR (internal use).

.SH ABUILD RECIPE FORMAT
.LP
An \fIabuild\fR file is a POSIX shell snippet sourced by \fBapkg\fR. The
directory containing it must be named identically to the \fBname\fR variable.

.SS Required variables
.TP
\fBname\fR
Package name. Must match the parent directory name.
.TP
\fBversion\fR
Upstream version string. Used in source URLs via \fB$name\fR and \fB$version\fR.
.TP
\fBrelease\fR
Integer starting at 1. Increment on each rebuild; reset to 1 when \fBversion\fR
changes.

.SS Optional variables
.TP
\fBsource\fR
Whitespace-separated list of source files. Five formats are accepted:
.RS
.IP \- 2
\fI<url>\fR \-- a source tarball URL (e.g. \fIhttps://example.com/$name-$version.tar.gz\fR)
.IP \- 2
\fI<filename>::<url>\fR \-- custom local filename for the downloaded source
.IP \- 2
\fI<url>::noextract\fR \-- download but do not unpack
.IP \- 2
\fI<filename>\fR \-- a local file in the recipe directory (not downloaded)
.IP \- 2
\fI<filename>::noextract\fR \-- a local file, not extracted
.RE
.IP
If \fBsource\fR is empty, a dummy (meta) package is created containing only
\fI/usr\fR.
.TP
\fBbuild_opt\fR
Extra flags passed to the build system (appended after the defaults).
.TP
\fBsv\fR
Runit service files to install into \fI/etc/sv\fR. Accepts names like \fIrun\fR,
\fIfinish\fR, \fI<name>.run\fR, \fI<name>.finish\fR.
.TP
\fBbuild_type\fR
Force a specific build system. Normally auto-detected; set to one of:
\fImuon_build\fR, \fImeson_build\fR, \fIconfigure_build\fR, \fIcmake_build\fR,
\fIpython_build\fR, \fIperlmodule_build\fR, \fImakefile_build\fR.
.TP
\fBbuild_dir\fR
Subdirectory within the extracted source to enter before building.
.TP
\fBskip_patch\fR
If set to 1, skip automatic patch application (so \fIbuild()\fR can call
\fBapply_patch\fR manually).
.TP
\fBpatch_opt\fR
Options passed to \fBpatch\fR(1). Default: \fB\-p1\fR.
.TP
\fBkeep_static\fR
If set, keep \fI*.a\fR static libraries (removed by default).
.TP
\fBkeep_libtool\fR
If set, keep \fI*.la\fR libtool archives (removed by default).
.TP
\fBkeep_locale\fR
If set, keep locale files in \fI/usr/share/locale\fR and \fI/usr/lib/locale\fR.
.TP
\fBkeep_doc\fR
If set, keep documentation in \fI/usr/share/doc\fR and \fI/usr/doc\fR.
.TP
\fBno_strip\fR
If set, skip ELF binary and library stripping.

.SS Build function hooks
.LP
If a \fBbuild()\fR function is defined, it is called directly (in \fBset \-ex\fR
mode) and the auto-detection pipeline is bypassed. \fB$SRC\fR and \fB$PKG\fR
point to the source extraction and fakeroot directories respectively. Several
\fBDESTDIR\fR-style variables are pre-exported for common build systems:
\fBDESTDIR\fR, \fBDEST_DIR\fR, \fBINSTALLROOT\fR, \fBinstall_root\fR, and
\fBINSTALL_ROOT\fR.

If no \fBbuild()\fR function is present, \fBprebuild()\fR (if any) runs first,
then the auto-detected build system, then \fBpostbuild()\fR (if any).

.SS Other files in the recipe directory
.TP
\fBdepends\fR
One dependency per line. Lines starting with \fB#\fR are comments.
.TP
\fBpreinstall\fR
Executable script run before the package is built (only during \fB\-i\fR or
\fB\-u\fR).
.TP
\fBpostinstall\fR
Executable script run after the package is installed or upgraded.
.TP
\fB.shasum\fR
Auto-generated checksum file. Regenerate with \fB\-g\fR.
.TP
\fB.files\fR
Auto-generated sorted file list from the package contents. Regenerate with
\fB\-k\fR.

.SH BUILD SYSTEMS
.LP
When no \fBbuild()\fR function is defined, the build type is auto-detected by
checking for these files in order:
.IP 1. 3
\fBmeson.build\fR \-- \fBmuon setup\fR (or \fBmeson setup\fR if
\fBbuild_type=meson_build\fR) with LTO and PIE enabled,
\fBwrap_mode=nodownload\fR, \fBbuildtype=plain\fR
.IP 2. 3
\fBconfigure\fR \-- \fB./configure --prefix=/usr --sysconfdir=/etc ...\fR
.IP 3. 3
\fBCMakeLists.txt\fR \-- \fBcmake\fR with \fBRelease\fR build type,
\fBninja\fR preferred over \fBmake\fR
.IP 4. 3
\fBsetup.py\fR \-- \fBpython3 setup.py build && install --root=$PKG\fR
.IP 5. 3
\fBMakefile.PL\fR \-- \fBperl Makefile.PL && make && make install\fR
.IP 6. 3
\fBMakefile\fR, \fBmakefile\fR, or \fBGNUmakefile\fR \-- \fBmake\fR with
standard prefix/sysconfdir variables

.SS Post-build processing
.LP
After compilation, \fBapkg\fR automatically:
.IP \- 2
Compresses man pages (gzip, keeps only man[1-8] sections) and info pages
.IP \- 2
Removes common conflict files (\fIfonts.dir\fR, \fIfonts.scale\fR,
\fIperllocal.pod\fR, \fIcharset.alias\fR)
.IP \- 2
Removes static libraries (\fI*.a\fR), libtool archives (\fI*.la\fR),
locales, and docs unless the corresponding \fBkeep_*\fR variable is set
.IP \- 2
Strips ELF executables (\fB\-\-strip-all\fR), shared objects
(\fB\-\-strip-unneeded\fR), and static archives (\fB\-\-strip-debug\fR)
unless \fBno_strip\fR is set
.IP \- 2
Installs runit service files from the \fBsv\fR variable into \fI/etc/sv\fR

.SH ENVIRONMENT
.TP
\fBAPKG_REPO\fR
Space-separated list of directories containing package recipes. Searched in
order; the first match wins. Default: current directory.
.TP
\fBAPKG_PACKAGE_DIR\fR
Directory where built \fI.spm\fR packages are stored. Default: current directory.
.TP
\fBAPKG_SOURCE_DIR\fR
Directory for downloaded source tarballs. Default: current directory.
.TP
\fBAPKG_WORK_DIR\fR
Directory for build working trees (subdirectories \fIapkg-src-<name>\fR and
\fIapkg-pkg-<name>\fR are created and cleaned automatically). Default: current
directory.
.TP
\fBAPKG_ROOT\fR
Alternative root directory for installation (e.g. for cross-compilation or
staged installs). Sets \fBSPM_ROOT\fR. Default: \fI/\fR.
.TP
\fBAPKG_KEEP_WORKDIR\fR
If set, do not remove the work directory on build failure (useful for debugging).
.TP
\fBAPKG_NOPROMPT\fR
If set, skip the confirmation prompt in \fB\-I\fR and \fB\-U\fR operations.
.TP
\fBAPKG_ALIAS\fR
Space-separated list of \fIreal:alias\fR pairs for dependency substitution
(e.g. \fIopenssl:libressl\fR makes packages depending on openssl pull libressl).
.TP
\fBAPKG_MASK\fR
Space-separated list of packages to exclude from \fB\-l\fR and \fB\-U\fR.
.TP
\fBAPKG_LOG\fR
If set, enable build logging.
.TP
\fBAPKG_LOG_DIR\fR
Directory for build log files (log filename is \fI$name.log\fR).
.TP
\fBCFLAGS\fR, \fBCXXFLAGS\fR
Compiler flags used by the cmake build system.
.TP
\fBCROSS_COMPILE\fR
Prefix for the \fBstrip\fR command (e.g. \fIx86_64-linux-musl-\fR).
.TP
\fBCARGO_HOME\fR, \fBGOCACHE\fR
Set inside the build environment for Rust and Go builds respectively.

.SH FILES
.TP
\fI/var/lib/spm/db/\fR
SPM package database. Each installed package has a file here whose first line
is the installed version-release string.

.SH EXAMPLES
.LP
Build and install a package:
.RS
\f(CRapkg \-i mypkg\fR
.RE
.LP
Install with automatic dependency resolution:
.RS
\f(CRapkg \-I firefox\fR
.RE
.LP
Full system upgrade:
.RS
\f(CRapkg \-U\fR
.RE
.LP
Search for packages:
.RS
\f(CRapkg \-s icon\fR
.RE
.LP
Find which package owns a file:
.RS
\f(CRapkg \-S libpng.so\fR
.RE
.LP
List outdated packages:
.RS
\f(CRapkg \-l\fR
.RE
.LP
Force rebuild:
.RS
\f(CRapkg \-f jupp\fR
.RE
.LP
Check direct dependencies:
.RS
\f(CRapkg \-d mypkg\fR
.RE

.SH SEE ALSO
.BR apkg-chroot (8),
.BR apkg-clean (8),
.BR apkg-deps (8),
.BR apkg-foreign (8),
.BR apkg-genabuild (8),
.BR apkg-orphan (8),
.BR apkg-purge (8),
.BR apkg-redundantdeps (8),
.BR reposync (8),
.BR revdep (8),
.BR updateconf (8),
.BR spm (8)

.SH AUTHORS
.LP
emmett1 \c
.MT me@emmett1.my
.ME

.SH REPORTING BUGS
.LP
.UR https://codeberg.org/emmett1/autils/issues
.UE