.Dd November 17, 1998
.Dt PUBLISH 8
.Os NetBSD 1.4T
.Sh NAME
.Nm publish
.Nd make a software package accessible to the world
.Sh SYNOPSIS
.Nm publish
.Op Fl q
.Op Fl n
.Op Fl a
.Op Fl u
.Op Fl r
.Op Fl p
.Op Fl k
.Op Fl L
.Op Fl D
.Op Fl h
.Ar pkg-ver
.Sh DESCRIPTION
.Sy pkg
is the name of a package, such as emacs or publish;
.Sy ver
is the version number, such as 19.36 or 19960622.
.Sy pkg
may contain dashes;
.Sy ver
must not.  The
.Ar pkg-ver
argument can also be a lone
.Sq \&. ,
in which case
.Nm
will look for a file called
.Pa WHERE_I_CAME_FROM
(the actual name can be changed at compile time).  If it finds it, it
will read it, looking for lines beginning
.Sq package:
and
.Sq version: .
If it finds exactly one of each, and the
.Sq version:
line does not contain a dash, it will take the rest of those two lines,
paste them together with a dash in between, and use that.  Otherwise
(if the file isn't found or doesn't contain such lines), it will
effectively use `basename \e`pwd\e`` (though without actually running
either
.Xr basename 1
or
.Xr pwd 1 ) .
.Pp
.Nm
is the last step in the installation of a new version of a local
software package.  It assumes that the package has already been built
and installed in the appropriate versioned subdirectories; it creates
symbolic links from the generally-accessible directories into the
versioned subdirectories.
.Pp
Options quick summary (see below for full details):
.Bl -tag -width indent
.It Fl q
Quiet mode, print only errors.
.It Fl n
Dry-run mode, don't actually do anything.
.It Fl a
Auto-run mode, never create a do-not-publish file.
.It Fl u
Unpublish mode, undo a previous publish.
.It Fl r
Republish mode, install a new version.
.It Fl p
Publish mode, overriding a previous
.Fl u
or
.Fl r
(explicit or implicit).
.It Fl k
Keep mode, don't remove stuff when republishing.
.It Fl L
Data-library mode; see description of actions.
.It Fl D
Debug mode, spit out various debugging messages.
.It Fl h
Help mode, print a short list of options and exit.
.El
.Pp
If
.Nm
is invoked as
.Dq unpublish
(the actual name can be changed at compile time), it runs as if the
.Fl u
flag were given; if as
.Dq republish ,
as if
.Fl r
were given.  (This is why
.Fl p
exists.)
.Pp
In the following, LOCALBIN, LOCALMAN, LOCALINC, and LOCALLIB refer to
directories that get versioned subdirectories into which packages are
told to install themselves.  For example, if LOCALBIN is
.Pa /local/.bin ,
then emacs-19.36 (for example) would have been configured with
.Pa /local/.bin/emacs-19.36
as its directory to install binaries into.  LOCALPKG is intended for
packages that expect to be given a single directory and then have their
way with the tree rooted there, instead of having separate
configuration paths for binaries, man pages, etc.  If emacs-19.36 were
such a package, it would be found in
.Pa /local/pkg/emacs/emacs-19.36 ,
or (if it were part of a larger collection, say
.Dq gnu ) ,
.Pa /local/pkg/gnu/emacs/emacs-19.36 .
LOCALPATHBIN, LOCALPATHMAN, LOCALPATHINC, and LOCALPATHLIB are the
directories that users' PATH, MANPATH, etc, point to.  They are where
the symlinks into the LOCALBIN, etc, directories, that
.Nm
manages, exist.  Typical values for a few of these might be
.Dl LOCALPKG: /local/pkg
.Dl LOCALBIN: /local/.bin
.Dl LOCALPATHBIN: /local/bin
See the section below titled
.Sq "LOCAL PATHS"
for more on these.
.Pp
In what follows, when something
.Dq must
be some way, this means that if it isn't,
.Nm
simply prints a complaint and exits.  Also, throughout this, whenever
an action is described that is permanent in its effects (creating or
removing a file, for example), the action is not actually taken if
.Fl n
is in effect.
.Pp
When publishing a package
.Pf ( Fl p
mode):
.Pp
.Nm
looks for
.Pa LOCALMAN/pkg-ver ;
this directory must exist.  Call this directory MD for short.
It also looks for
.Dl LOCALBIN/pkg-ver
.Dl LOCALPKG/pkg/pkg-ver
.Dl LOCALPKG/*/pkg/pkg-ver
No more than one of these three must exist.  Call the one that does SD,
or if none does, consider SD undefined.  Also let ID be
.Pa LOCALINC/pkg-ver
and LD be
.Pa LOCALLIB/pkg-ver .
.Pp
.Nm
looks for files matching
.D1 Pa MD/*.{0,[1-9lL]*,man,n}
.D1 Pa MD/{cat,man}?/*.{0,[1-9lL]*,man,n}
At least one such file must exist.  Also, if SD is defined,
.Pa SD/.DO_NOT_PUBLISH
must not exist.  If SD is defined and is under LOCALPKG, then
.Pa SD/.BINARIES
must exist; it contains, one per line, a list of pathnames.  If a
relative pathname occurs in the file, it is taken to be relative to the
directory the
.Pa .BINARIES
file is found in.
.Pp
If SD is defined and is under LOCALPKG, then let BINS be the pathnames
listed therein; if SD is defined and not under LOCALPKG, let BINS be a
list of the contents of SD (except \&.PUBLISH, if present); if SD is
not defined, let BINS be empty.
.Pp
If ID exists, let INCS be a list of all plain files in the hierarchy
under ID; otherwise, let INCS be empty.
.Pp
If LD exists, let LIBS be a list of all files matching
.Pa LD/lib*.* ,
or if
.Fl L
was specified,
.Pa LD/* ;
otherwise, let LIBS be empty.
.Pp
Let MANS be a list of the files in MD matching the patterns described
above (at least one such file must exist).  Note that below, when links
are made or being checked, if the manpage file has a
.Pa .man
extension, the link made or checked for will have an extension based on
the section it appears in (or is assumed to appear in), rather than
being also called
.Pa .man .
.Pp
.Nm
checks for conflicts between MANS and existing files in LOCALPATHMAN,
between BINS and existing files in LOCALPATHBIN, between INCS and
existing files in LOCALPATHINC, and between LIBS and existing files in
LOCALPATHLIB.  (Note that when checking LOCALPATHMAN, proper care is
taken to consider both formatted and unformatted manpages.)  If any
conflicts are found, they are listed and
.Nm
exits; if
.Fl a
is not in effect,
.Pa SD/.DO_NOT_PUBLISH
is created, listing the conflicts.  (If SD is not defined,
.Pa LOCALBIN/pkg-ver
is created and the
.Pa .DO_NOT_PUBLISH
file is created there.)
.Pp
Otherwise, symlinks are created in LOCALPATHMAN pointing to the files
in MANS, in LOCALPATHBIN to BINS, in LOCALPATHINC to INCS, and in
LOCALPATHLIB to LIBS.  Subdirectories are created as needed in
LOCALPATHINC.  For each symlink created, a line is printed to stdout;
if
.Fl a
is not in effect, the output printed to stdout is also copied into
.Pa SD/.PUBLISH
(if SD is not defined,
.Pa LOCALBIN/pkg-ver
is created and the
.Pa \&.PUBLISH
file is created there).
.Pp
When unpublishing a package
.Pf ( Fl u
mode):
.Pp
.Pa SD
is determined as above; in this case, it must not be undefined, and
.Pa SD/.PUBLISH
must exist.
.Nm
reads the
.Pa \&.PUBLISH
file, looking for lines indicating symlinks, as written by the
.Nm
run that created the file (specifically, it looks for lines containing
.Dq \-\*(Gt
with whitespace on either side).  Each symlink is checked to make sure
it points to where the
.Pa \&.PUBLISH
file indicates it should, and if so, it's removed.  If it doesn't
exist, isn't a symlink, or points somewhere else, a complaint is
printed and the line is skipped.  After all this, the
.Pa \&.PUBLISH
file is removed; if that leaves
.Pa SD
empty, it too is removed.
.Pp
When republishing a package
.Pf ( Fl r
mode):
.Pp
.Nm
operates as if in publishing mode, except that when figuring out
.Pa SD ,
it also looks for the other possibilities with the same
.Sy pkg
but a different
.Sy ver ;
if it finds any, it unpublishes them first.  Unless
.Fl k
is given, it also removes the
.Sy pkg Ns No \&- Ns Sy ver
subdirectories that would be MD, SD, ID, and LD for them according to
the rules described for publishing.
.Sh "LOCAL PATHS"
The actual paths used are determined by checking environment variables
and constructing the paths from them.  The procedure is the same for
each of the paths; only the default strings and the names checked for
in the environment differ.  When constructing
.No LOCAL Ns Em foo
(eg,
.Em foo Ns No =BIN
when computing LOCALBIN), the procedure followed is as follows, with
the additional overall note that if the resulting string is longer than
a compiled-in limit, it is truncated.
.Bl -dash
.It
Check for
.Pf \&$ Ev PUBLISH_LOCAL Ns Em foo .
If this exists, its value is used unchanged.
.It
Check for
.Pf \&$ Ev LOCAL Ns Em foo .
If this exists, its value is used unchanged.
.It
Check for
.Pf \&$ Ev LOCALROOT .
If it exists, call the resulting string PREFIX below; otherwise, let
PREFIX be a compiled-in default.
.It
Check for
.Pf \&$ Ev PUBLISH_ Ns Em foo .
If it exists, append it to PREFIX; otherwise, append the compiled-in
default for
.Em foo
to PREFIX.  In any case, the result is used.  (Note that no slash is
supplied when concatentating; however, the compiled-in default suffix
strings all begin with slashes.)
.El
.Pp
At this writing, the compiled-in defaults are:
.Bl -tag -width indent
.It "Overall length limit"
511 characters (512, including the terminating NUL).
.It "Default PREFIX"
.Pa /local
.It "Default suffix for"
.Bl -tag -compact -width "PATHXXXxx"
.It PKG
.Pa /pkg
.It BIN
.Pa /.bin
.It MAN
.Pa /.man
.It INC
.Pa /.include
.It LIB
.Pa /.lib
.It PATHBIN
.Pa /bin
.It PATHMAN
.Pa /man
.It PATHINC
.Pa /include
.It PATHLIB
.Pa /lib
.El
.El
.Sh AUTHOR
C version by der Mouse
.Aq mouse@rodents.montreal.qc.ca ,
after the shell script by Steven Winikoff, as modified by Anne Bennett.