expand docs

[zpackage] / doc / zpm-script.8

diff --git a/doc/zpm-script.8 b/doc/zpm-script.8
new file mode 100644 (file)
index 0000000..bf5bbb7
--- /dev/null
+++ b/doc/zpm-script.8
@@ -0,0 +1,89 @@
+.TH zpm-script 8 2019-02-15 "ZPM 0.3"
+.SH NAME
+zpm-script \- run, set, or list package scripts
+.SH SYNOPSIS
+.B zpm script
+[
+.B -Fhq
+]
+[
+.BI -f " pkgfile"
+]
+[
+.BI -p " phase"
+]
+[
+.BI -R " rootdir"
+]
+[
+.BI -o " path"
+]
+[
+.BI -S " script"
+]
+.I package
+.SH DESCRIPTION
+\fBzpm-script\fR
+runs, sets, or lists package scripts for a package.  The package is a package
+id, which may be abbreviated.  Despite the name, scripts can be any
+arbitrary program, though they are usually posix shell scripts.
+.PP
+zpm-script runs in one of three modes, run, list, and set.
+.SS Run Mode
+In run mode, a script for a given phase is run if it exists.  It is not
+an error if there is no script for the given package and phase unless
+the \-F option is given.  Standard output from the script will be redirected
+to /var/tmp/zpm-script.out, or as specified by the -o option.
+.PP
+The script itself will be extracted to /var/tmp/zpm-script, set as executable,
+and then run.  The script is run with one or two arguments.  The
+first argument is the package id being installed, removed, or configured.
+For a package version update (or downgrade) the second argument is
+the previous version of the package.
+.TP
+An example script
+.EX
+#!/bin/sh
+
+echo example and test zpm stage script
+echo args: "$*"
+.EE
+.SS Set Mode
+Set mode will set the script for a given package and phase to the
+path given as an additional argument.  If the -h is given, the script
+is interpreted as a hash to be set directly, and nothing is taken
+from the filesystem.
+.SH OPTIONS
+.TP
+.BI \-p phase
+Specify the script phase.  This defaults to all phases for list mode,
+and configure for running or setting scripts.
+.TP
+.B \-f
+specify the package file to find packages in
+.TP
+.B \-h
+When setting a script, the script is taken as a hex encoded hash, rather
+than a path to a script.
+.TP
+.B \-q
+Run quietly.
+.SH EXAMPLES
+.TP
+zpm script -f foo-1.0-1.zpm foo
+Run the configure script for the foo package found in the foo-1.0-1.zpm
+file.
+.TP
+zpm script foo
+Run the configure script for the (most recent) foo package found
+in the local database.
+.SH EXIT STATUS
+0 on success non zero on failure
+.SH FILES
+/var/lib/zpm/local.db
+.SH ENVIRONMENT
+ZPMDB
+.SH AUTHOR
+Nathan Wagner
+.SH SEE ALSO
+.BR zpm (8)