added man page and Makefile

2 files changed, 290 insertions, 0 deletions

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..7eeec65
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,26 @@
+PREFIX ?= /usr
+BINDIR ?= $(DESTDIR)$(PREFIX)/bin
+MANDIR ?= $(DESTDIR)$(PREFIX)/share/man
+
+.PHONY: help install uninstall
+
+help:
+	@echo "spm — Simple Package Manager"
+	@echo
+	@echo "Targets:"
+	@echo "  make install        install spm and man page"
+	@echo "  make uninstall      remove spm and man page"
+	@echo
+	@echo "Variables:"
+	@echo "  PREFIX              installation prefix (default: /usr)"
+	@echo "  DESTDIR             staging directory for packaging"
+
+install:
+	install -d $(BINDIR)
+	install -m755 spm $(BINDIR)/spm
+	install -d $(MANDIR)/man1
+	install -m644 spm.1 $(MANDIR)/man1/spm.1
+
+uninstall:
+	rm -f $(BINDIR)/spm
+	rm -f $(MANDIR)/man1/spm.1
diff --git a/spm.1 b/spm.1
new file mode 100644
index 0000000..ba74344
--- /dev/null
+++ b/spm.1
@@ -0,0 +1,264 @@
+.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)