man/mkpkg.1

SPS · log · files · refs · tags · releases · people · languages · GitHub · file
.TH MKPKG 1 "2026-08-30" "SPS 1.0" "SPS Commands"
.SH NAME
mkpkg \- build an SPS source recipe into a binary package
.SH SYNOPSIS
.B mkpkg
.RI [ options ]
.RI [ recipe ]
.SH DESCRIPTION
.B mkpkg
reads declarative metadata from a recipe, verifies sources, executes only the
named build phase records, stages installation away from the live root,
generates SPS metadata, manifests, and hashes, then writes a standard tar package.
The default recipe is
.BR ./recipe .
A directory argument means its
.B recipe
file.
.PP
Build phases normally run with the host environment.
.BR --build-root ,
when given, runs every build phase with the root's
.B /usr/bin
and
.B /bin
first on
.B PATH
and exposes the root as
.BR SYSROOT .
Recipes that stage a toolchain inside a root (an LFS-style sysroot) use this to
ensure their compiler, linker, and headers resolve from the target root rather
than the host. It does not use a chroot, does not require root privileges, and
never writes into the build root itself.
.SH OPTIONS
.TP
.BI "-o, --output " dir
Write the completed package to DIR.
.TP
.BI "-C, --compression " type
Select
.BR auto ,
.BR none ,
.BR gzip ,
.BR xz ,
or
.BR zstd .
.TP
.BI "-R, --build-root " dir
Run build phases with
.B DIR/usr/bin
and
.B DIR/bin
first on
.B PATH
and expose the absolute
.B DIR
as
.BR SYSROOT .
.B DIR
must already exist.
.TP
.B --no-download
Require remote sources to already exist in the source cache.
.TP
.B --keep-build
Keep build and staging directories for inspection after exit.
.TP
.BI "--artifact-file " path
After a successful build, write the absolute package archive path to PATH.
The file is replaced only when the archive exists. A previous value is removed
at the start of the run so a failed build cannot leave a stale success. Callers
such as
.BR sget (1)
use this to obtain the artifact without capturing build output.
.TP
.B --print-artifact
Print the absolute package archive path as the final stdout line. Build
commands also write to stdout, so this is only reliable for recipes whose
phases produce no output. Prefer
.B --artifact-file
for scripts.
.SH RECIPES
Required keys are
.BR name ,
.BR version ,
and
.BR release .
A recipe must also contain at least one
.B install
record, and installation must produce a non-empty staged payload.
Common repeatable keys include
.BR source ,
.BR hash ,
.BR depend ,
.BR builddep ,
.B optional
and the phase records
.BR prepare ,
.BR configure ,
.BR build ,
and
.BR install .
Metadata parsing never executes these phase records.
.PP
Each
.B source
must have one corresponding
.B hash
in declaration order. The only accepted form is
.BR sha256:HEX ,
with exactly 64 hexadecimal digits. There is no checksum-skip value.
.PP
The optional
.B arch
key defaults to
.BR SPS_ARCH .
Use
.B any
for an architecture-independent package;
.B noarch
is accepted as a compatibility spelling.
.PP
A real
.B files
or
.B patches
directory beside the recipe is copied to
.B $SRC/files
or
.BR $SRC/patches .
Nothing in these directories is applied or installed automatically.
.PP
A recipe directory may provide explicit lifecycle scripts in
.B hooks/pre-install,
hooks/post-install, hooks/pre-remove, and hooks/post-remove. No other hook
names are accepted.
.SH ENVIRONMENT
.B PKG
is the package staging root;
.B SRC
contains acquired sources and support trees;
.B WORK
is the extracted source root. Each phase starts there and runs with
.B /bin/sh
and options
.BR -eu .
.PP
.B SPS_ARCH
provides the default architecture.
.B SPS_MAKEJOBS
provides per-package parallelism and is exposed to build commands as
.BR MAKEJOBS .
.B SPS_CACHE
contains downloaded sources;
.B SPS_BUILD
contains temporary build/staging trees.
When
.B SPS_ROOT
is not
.BR / ,
every build phase also searches that root for headers, libraries, and
pkg-config files
.RB ( CFLAGS ,
.BR LDFLAGS ,
.BR LIBRARY_PATH ,
.BR PKG_CONFIG_SYSROOT_DIR ,
.BR CMAKE_PREFIX_PATH ).
.B OPENSSL_MODULES
and
.B OPENSSL_CONF
point at providers and
.B openssl.cnf
already installed in that root so a just-built Python
.B _ssl
module does not load the live disc's OpenSSL.
Live
.BR setup (1)
installs into a mounted target with the live compiler; without this, a
package cannot link against a library
.BR pkin (1)
just unpacked into the target.
With
.BR --build-root ,
.B SYSROOT
is the absolute controlled root directory.
.SH OUTPUT
SPS status messages go to stderr in the form
.BR "mkpkg: text" .
Upstream configure, compile, and install commands keep their own stdout and
stderr. Remote fetches print
.B mkpkg: fetching
then use curl or wget progress so a download does not look idle.
.PP
On success,
.B mkpkg
reports
.B mkpkg: built
followed by the archive basename. The archive path is not printed on stdout
unless
.B --print-artifact
is given. Machine callers should use
.BR --artifact-file .
.SH EXIT STATUS
Returns 0 on success, 2 for usage, 3 for missing recipe/source, 4 for invalid
metadata/package content, 6 for checksum failure, 7 when the output artifact
already exists, 8 for filesystem failure, 9 for download failure, and 10 for
build failure.
.SH SEE ALSO
.BR sget (1),
.BR pkin (1),
.BR sps.conf (5)