diff options
Diffstat (limited to 'man/apkg.8')
| -rw-r--r-- | man/apkg.8 | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/man/apkg.8 b/man/apkg.8 new file mode 100644 index 0000000..b810666 --- /dev/null +++ b/man/apkg.8 @@ -0,0 +1,368 @@ +.\" -*- 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: +\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 \-- \fBmeson setup\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 +Merges \fI/bin\fR, \fI/sbin\fR, \fI/usr/sbin\fR into \fI/usr/bin\fR if +\fBAPKG_BINMERGE\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_BINMERGE\fR +If set, merge \fI/bin\fR, \fI/sbin\fR, and \fI/usr/sbin\fR into +\fI/usr/bin\fR during packaging. +.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 |