.TH PKGADD 8
.SH NAME
pkgadd, pkgrm, pkgclean \- Manage optional packages
.SH SYNOPSIS
.B pkgadd
.RB [ \-x
.IR distpkg ]
.I name
.br
.B pkgrm
.RB [ \-f ]
.I name
.br
.B pkgclean
.RB [ \-b ]
.I name
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
These programs manage optional software packages.  Optional software is
installed in
.BR /opt .
Only a few symlinks in
.BR /usr/bin ,
.BR /usr/lib ,
or
.B /usr/man
are used to make the package work, no other mysterious changes are made to
the
.B /usr
tree.
.PP
.B Pkgadd
adds a package in
.B /opt
to the system.
A new package is distributed as a directory tree, or a (compressed) tar
file.  It is named on the command line with the
.B \-x
option.  It may be in one of four formats:
.PP
.RS
A directory that is or that contains the package.  (You can omit the name
now if
.I distpkg
ends in the package name.)
.PP
.RS
A tar file, if the name ends in
.BR .tar ,
otherwise a compressed tar file.
.RE
.PP
.RS
A device.  It is assumed to be a compressed tar file on floppy or tape.
.RE
.PP
.RS
From standard input if the name is a dash (\-).  It is also assumed to be
a compressed tar file.  See
.BR vol (1)
for a program to read a multivolume file from a device.
.RE
.PP
.B Pkgadd
copies or extracts the directory
.I name
from
.I distpkg
in
.BR /opt ,
makes symlinks in
.B /usr
to binaries, library files and manual pages, runs make if the package has a
.B src
directory,
runs an installation script to tie up a
few loose ends, and starts daemons that will normally be started by
.B /etc/rc
at boot time.
.B pkgadd
may be rerun (without the
.B \-x
option) if the package did not install properly or if you want to recompile
the package.
.PP
.B Pkgrm
undoes
.BR pkgadd 's
actions, removing the symlinks and also the package if called with
.BR \-f .
.PP
.B Pkgclean
removes compiler temporaries and the build tree to free up disk space.  The
binaries and other files needed to use the package stay in place, so that
the package keeps working.
.PP
Both
.B pkgadd
and
.B pkgrm
must be run by
.BR bin .
.SH OPTIONS
.TP
.B \-x "\fIdistpkg"
Either a directory that is or that contains the package, a file in
(compressed) tar format that contains the package, or a tape or floppy
device that contains the packages as a (multivolume) compressed tar file.
(Note that this is just a convenience option, you can put the package in
.B /opt
yourself if you want to.)
.TP
.B \-f
Fully deinstall a package.  After removing the symlinks the package is also
removed from
.BR /opt .
.TP
.B \-b
Makes
.B pkgclean
remove the source tree too, transforming the package into a binary package.
This action is destructive, it may free up a lot of diskspace, but the
sources are lost.  Make sure you can retrieve them somehow.
.SH "PACKAGE LAYOUT"
The internal layout of a package is free except for the files used for
installation or removal.  They are:
.TP
.BI /opt/ name /etc/symlinks
This file must exist and contain entries of two filenames, say
.I optfile
and
.IR usrfile ,
that are used to make links with the call:
.SP
.RS
.B ln \-s
.I optfile
.I usrfile
.RE
.SP
Both names must be full pathnames allowing one to make symlinks into other,
earlier installed packages.
.TP
.BI /opt/ name /src
If this directory exists then it will be cloned to the directory
.BI /opt/ name /build
and
.B make install
will be called there to compile and install the package.
.B Pkgrm
runs
.B make uninstall
in the source tree and removes the build tree restoring the package to its
original state.  This means that files installed within the package but
outside the source tree must be removed.
.B Pkgclean
runs
.B make clean
instead before removing the build tree.  This should leave installed files
intact.
.TP
.BI /opt/ name /etc/install
If it exists then it is run after the make.
.TP
.BI /opt/ name /etc/rc
If it exists then it is run after install and on reboot by
.B /etc/rc
with the single argument
.BR start .
It is run with the argument
.B stop
on package removal, to kill daemons.
.TP
.BI /opt/ name /etc/daily
If it exists then it is run once per day by
.BR /usr/etc/daily .
.TP
.BI /opt/ name /etc/uninstall
If it exists then it is run as the first thing on a removal.
.TP
.BI /opt/ name /etc/info
This file must exist.  It contains one or more headers, an empty line, and
some information that the package writer wants to convey.  The headers are
words followed by a colon, followed by a parameter.  Two headers are defined
as yet, a
.B \&"Title:"\&
header, that contains a one line description to be put in
.BR /usr/lib/packages ,
and a
.B \&"Requires:"\&
header, that is a comma or space separated list of names
of packages that this package depends on.  These required packages must be
installed before this package is installed, and this package must be removed
before the packages it requires can be removed.  More "keyword:" lines may be
invented in the future.
The complete info file is shown to the installer after installation, or by
.B pkginfo
if called with just one package name.
.TP
.BI /opt/ name /{bin,lib,man}
A package creator is advised to make these directories if needed and to fill
them with the apropriate files.  Use symlinks from (files in) these
directories in the symlinks file.  Do not make symlinks from the build tree,
because the build tree may be cleaned out.  Also do not place manual page
files into a manual page tree in
.BR /usr ,
because they are not listed in the
.B whatis
file.  Make a man directory, even if it only contains one file, and make a
single symlink from the man directory into
.BR /usr/man .
.PP
Most files in a package should be owned by
.BR bin ,
only files that must be owned by some other id, like set-uid binaries,
can be owned by another id.  Installation and removal of the package is
done as
.BR root ,
including the install, rc, daily and uninstall scripts.
Compilation and cleanup of the source and build directory is done as
.BR bin .
.SH FILES
.TP 25n
.B /usr/lib/packages
List of installed packages.
.SH "SEE ALSO"
.BR pkginfo (1),
.BR tar (1),
.BR compress (1),
.BR gzip (1),
.BR man (1),
.BR vol (1).
.SH BUGS
This used to be a done by a simple script in its first incantation.  What is
it about packages that makes things increasingly more complex?
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)