path: root/spm.1

.TH SPM 1 "May 2026" "spm" "User Commands"
.SH NAME
spm \- Simple Package Manager
.SH SYNOPSIS
.B spm \-b
.I file
.br
.B spm \-i
.I file
.br
.B spm \-u
.I file
.br
.B spm \-r
.I name
.br
.B spm \-l
.I name
.br
.B spm \-o
.I file
.br
.B spm \-a
.br
.B spm \-h
.SH DESCRIPTION
.B spm
is a POSIX-compatible package manager for Linux.
It builds, installs, upgrades, and removes
.B .spm
packages \(em compressed tar archives whose filename encodes the
package identity.
.PP
Packages follow the naming convention:
.PP
.RS
.I name\fB#\fIversion\fB\-\fIrelease\fB.spm
.RE
.PP
where
.I name
contains no
.B #
characters,
.I version
contains no
.B \-
characters, and
.I release
is a positive integer.
Example:
.PP
.RS
.B vim#9.1-1.spm
.RE
.PP
Install, upgrade, and remove operations require root privileges.
.SH OPTIONS
.TP
.B \-a
List all installed packages, one per line.
.TP
.BI \-b " file"
Build a package from the current working directory.
.I file
is the full or relative path for the output package.
Files in the current directory are archived into the package.
Files under
.B etc/
are renamed with a
.B .new
suffix so they do not overwrite existing configuration files
on install.
.TP
.B \-h
Print the help message and exit.
.TP
.BI \-i " file"
Install a package.
The package must not already be installed; use
.B \-u
to upgrade or reinstall.
Requires root.
.TP
.BI \-l " name"
List all files installed by the package
.IR name .
.TP
.BI \-o " file"
Print the package that owns
.IR file .
.TP
.BI \-r " name"
Remove the installed package
.IR name .
Files unique to the package are deleted; directories
shared with other packages are preserved.
Requires root.
.TP
.BI \-u " file"
Upgrade or reinstall a package.
The package must already be installed; use
.B \-i
for a fresh install.
Files present in the old package but absent from the new one
are removed after extraction.
Requires root.
.SH PACKAGE FORMAT
An
.B .spm
package is a compressed tar archive whose contents mirror the
target filesystem tree relative to
.BR / .
.PP
During packaging, files under
.B etc/
are renamed with a
.B .new
suffix. When the package is installed, each
.B .new
file is moved into place (suffix removed) only if the
destination does not already exist or is identical to the
packaged version. This preserves locally modified configuration
files across upgrades.
.PP
The compression algorithm is selected via
.B SPM_COMPRESSION
and defaults to gzip.
.SH PACKAGE DATABASE
Package metadata is stored under
.B /var/lib/spm/
(or
.B $SPM_ROOT/var/lib/spm/
when an alternate root is set):
.TP
.B db/\fIname
One file per installed package. The first line records
.IB version \- release \fR.
Subsequent lines list every file and directory installed
by the package. Directories have a trailing
.BR / .
.TP
.B perms/\fIname
Directories with non-standard permissions (numeric mode
followed by the path).
.TP
.B owner/\fIname
Directories with non-root ownership
.RI ( user : group
followed by the path).
.SH CONFLICT DETECTION
Before installing,
.B spm
checks whether any file in the package already exists on
the filesystem and is not owned by the package being
upgraded. Cross-type conflicts (e.g. a package contains a
file where a directory exists on disk) are also detected.
If any conflict is found, the list is printed and
installation is aborted.
Set
.B SPM_FORCEINSTALL
to skip this check.
.SH ENVIRONMENT
.TP
.B SPM_ROOT
Override the installation root (default:
.BR / ).
All files are installed relative to this path and the
package database lives under
.BR $SPM_ROOT/var/lib/spm/ .
The directory must already exist.
.TP
.B SPM_FORCEINSTALL
Skip conflict detection during installation.
.TP
.B SPM_VERBOSE
Print each file path as it is installed or removed.
.TP
.B SPM_COMPRESSION
Compression algorithm for building packages:
.B gzip
(default),
.BR bzip2 ,
or
.BR xz .
.SH FILES
.TP
.B /tmp/spminstall.lock
Lock file for install/upgrade operations.
Remove manually if a previous run was interrupted.
.TP
.B /tmp/spmpackage.lock
Lock file for build operations.
Remove manually if a previous build was interrupted.
.SH EXIT STATUS
.TP
.B 0
Operation completed successfully.
.TP
.B 1
An error occurred. The error message is printed to stdout.
.SH EXAMPLES
.PP
Build a package:
.PP
.RS
.B cd /path/to/staged/files
.br
.B spm \-b /tmp/mypkg#1.0-1.spm
.RE
.PP
Install a package:
.PP
.RS
.B spm \-i /tmp/mypkg#1.0-1.spm
.RE
.PP
Upgrade an installed package:
.PP
.RS
.B spm \-u /tmp/mypkg#1.1-1.spm
.RE
.PP
Remove a package:
.PP
.RS
.B spm \-r mypkg
.RE
.PP
List files owned by a package:
.PP
.RS
.B spm \-l mypkg
.RE
.PP
Find which package owns a file:
.PP
.RS
.B spm \-o /usr/bin/myprog
.RE
.PP
Install into an alternate root:
.PP
.RS
.B SPM_ROOT=/mnt/chroot spm \-i /tmp/mypkg#1.0-1.spm
.RE
.PP
Build with xz compression:
.PP
.RS
.B SPM_COMPRESSION=xz spm \-b /tmp/mypkg#1.0-1.spm
.RE
.SH NOTES
.B spm
must be run as root for install, upgrade, and remove
operations.
.PP
.B ldconfig(8)
is invoked after each install or upgrade if
.B /sbin/ldconfig
is present and executable.
.SH SEE ALSO
.BR tar (1),
.BR ldconfig (8)