.\" -*- mode: troff; coding: utf-8 -*-
.TH APKG\-BIN 8
.SH NAME
apkg\-bin \- Alice Linux binary package manager
.SH DESCRIPTION
.LP
\fBapkg\-bin\fR is the binary package manager for Alice Linux. It fetches
pre-built \fI.spm\fR package archives from a binary repository, resolves
dependencies, and installs or upgrades packages via the \fBspm\fR(8) backend.
It is the binary counterpart to the source-based \fBapkg\fR(8).

Before use, run \fBapkg\-bin \-S\fR to sync the package index from
\fBAPKGBIN_REPO\fR. The index is cached locally at \fBAPKGBIN_CACHE_DIR\fR;
subsequent operations operate against the cache.

.SH OPTIONS
.TP
\fB\-h\fR
Print help and exit.
.TP
\fB\-g\fR
Generate a binary repository index (\fIAPKGBINDB\fR) from \fI.spm\fR files found
in \fBAPKG_PACKAGE_DIR\fR. Reads \fIdepends\fR, \fIinfo\fR, \fIpreinstall\fR,
and \fIpostinstall\fR files from \fBAPKG_REPO\fR directories. The index is
written to \fBAPKG_PACKAGE_DIR\fR and copied to \fBAPKGBIN_CACHE_DIR\fR for
immediate local use.
.TP
\fB\-S\fR
Sync the binary repository index from \fBAPKGBIN_REPO\fR. For remote URLs (http,
https, ftp), downloads \fIAPKGBINDB\fR via \fBcurl\fR(1). For local paths, copies
the file directly. Cached at \fI$APKGBIN_CACHE_DIR/APKGBINDB\fR.
.TP
\fB\-s\fR [\fIpattern\fR]
Search available binary packages by name pattern. Without a pattern, lists all
packages. With \fB\-v\fR, prints name, version-release, and description.
Without \fB\-v\fR, prints package name only.
.TP
\fB\-i\fR \fI<pkg...>\fR
Install package(s) without dependency resolution. Skips packages that are
already installed. Requires root.
.TP
\fB\-I\fR \fI<pkg...>\fR
Install package(s) with full recursive dependency resolution. Skips packages
that are already installed. Prompts for confirmation before proceeding unless
\fBAPKG_NOPROMPT\fR is set. Requires root.
.TP
\fB\-u\fR \fI<pkg...>\fR
Upgrade or reinstall specific package(s). No dependency resolution, no
confirmation prompt. Reinstalls even if already up to date. Skips packages
not currently installed. Requires root.
.TP
\fB\-U\fR
Full system upgrade. Compares all installed packages against the cached index,
resolves the full dependency closure for outdated packages, installs any new
dependencies, and upgrades all outdated packages. Prompts for confirmation
unless \fBAPKG_NOPROMPT\fR is set. Respects \fBAPKG_MASK\fR. Requires root.
.TP
\fB\-d\fR \fI<pkg>\fR
Show direct dependencies for a package. Prints one dependency name per line.
.TP
\fB\-D\fR \fI<pkg...>\fR
Show full dependency tree for package(s) (recursive, all transitive dependencies).
Prints one dependency name per line, with the input package last.
.TP
\fB\-l\fR
List installed packages that have newer versions available in the binary index.
.TP
\fB\-a\fR
List all installed packages. With \fB\-v\fR, also prints the installed version.
.TP
\fB\-o\fR \fI<pkg...>\fR
Download package(s) only, without installing. Resolves each package name in the
binary index and downloads the \fI.spm\fR to \fI$APKGBIN_CACHE_DIR\fR.
.TP
\fB\-c\fR
Clean downloaded packages with sha3sum mismatch. Scans \fI$APKGBIN_CACHE_DIR/\fR,
compares each \fI.spm\fR against the expected sha3sum in APKGBINDB, and removes
any with a mismatch.
.TP
\fB\-f\fR
Force re-download of cached \fI.spm\fR files. Usable with \fB\-i\fR, \fB\-I\fR,
\fB\-u\fR, and \fB\-o\fR.
.TP
\fB\-v\fR
Verbose output. Affects \fB\-s\fR (show descriptions) and \fB\-a\fR (show versions).

.SH BINARY REPOSITORY FORMAT
.LP
A binary repository is a directory (local or remote) containing:
.TP
\fIAPKGBINDB\fR
The package index file. Each line is a pipe-delimited record:
.RS
.IP
\fIname\fB#\fIversion-release\fB|\fIsize\fB|\fIsha3sum\fB|\fIdep1,dep2,...\fB|\fIpreinstall_b64\fB|\fIpostinstall_b64\fB|\fIdescription\fR
.RE
.IP
Fields: package identifier, file size in bytes, sha3sum hash, comma-separated
dependency names (empty if none), base64-encoded preinstall script (empty if
none), base64-encoded postinstall script (empty if none), and a human-readable
description. Use \fBapkg\-bin \-g\fR to generate.
.TP
\fI<name>#<version-release>.spm\fR
Pre-built package archives in \fBspm\fR(8) format. The \fB#\fR in filenames
is URL-encoded as \fB%23\fR when served over HTTP.

.SH ENVIRONMENT
.TP
\fBAPKGBIN_REPO\fR
Binary repository URL or local path. Required for \fB\-S\fR, \fB\-i\fR,
\fB\-I\fR, \fB\-u\fR, \fB\-U\fR, and \fB\-o\fR.
.TP
\fBAPKGBIN_CACHE_DIR\fR
Directory where the synced \fIAPKGBINDB\fR and downloaded \fI.spm\fR packages
are cached. Required.
.TP
\fBAPKG_REPO\fR
Space-separated list of source repository directories. Required for \fB\-g\fR
(to read \fIdepends\fR, \fIinfo\fR, \fIpreinstall\fR, and \fIpostinstall\fR
files).
.TP
\fBAPKG_PACKAGE_DIR\fR
Directory for package storage. Scanned by \fB\-g\fR for \fI.spm\fR files.
Default: current directory.
.TP
\fBAPKG_ROOT\fR
Alternative root directory for installation. Sets \fBSPM_ROOT\fR. Default: \fI/\fR.
.TP
\fBAPKG_MASK\fR
Space-separated list of packages to skip during \fB\-U\fR (system upgrade).
.TP
\fBAPKG_ALIAS\fR
Space-separated list of \fIreal:alias\fR pairs for dependency substitution
(e.g. \fIopenssl:libressl\fR).
.TP
\fBAPKG_NOPROMPT\fR
If set, skip the confirmation prompt in \fB\-I\fR and \fB\-U\fR operations.

.SH FILES
.TP
\fI$APKGBIN_CACHE_DIR/APKGBINDB\fR
Cached binary repository index.
.TP
\fI$APKGBIN_CACHE_DIR/\fR
Downloaded \fI.spm\fR package files.
.TP
\fI/var/lib/spm/db/\fR
SPM package database. Used to check installed packages and versions.

.SH EXAMPLES
.LP
Sync the binary repository index:
.RS
\f(CRAPKGBIN_REPO=https://example.com/alice/main apkg\-bin \-S\fR
.RE
.LP
Search for packages:
.RS
\f(CRapkg\-bin \-s browser\fR
.RE
.LP
Install a package without dependency resolution:
.RS
\f(CRapkg\-bin \-i firefox\fR
.RE
.LP
Install a package with all dependencies:
.RS
\f(CRapkg\-bin \-I firefox\fR
.RE
.LP
Show dependencies of a package:
.RS
\f(CRapkg\-bin \-d firefox\fR
.RE
.LP
Reinstall a package (force re-download):
.RS
\f(CRapkg\-bin \-u \-f opus\fR
.RE
.LP
List outdated packages:
.RS
\f(CRapkg\-bin \-l\fR
.RE
.LP
Full system upgrade:
.RS
\f(CRapkg\-bin \-U\fR
.RE
.LP
Generate a binary index (for repo maintainers):
.RS
\f(CRapkg\-bin \-g\fR
.RE
.LP
Clean mismatched downloads:
.RS
\f(CRapkg\-bin \-c\fR
.RE

.SH SEE ALSO
.BR apkg (8),
.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