DIST(7)

NAME
dist - introduction to dist

DESCRIPTION
The dist package is a set of tools meant to ease the construction and maintenance of portable software. There are four distinct parts in dist, and it is also meant to be used with two external products, which are publicly available: mailagent and patch.

The first component is the Configure script generator, which is a portability tool. It is automatically build up by metaconfig from your sources and a set of units. Ideally, the end-user receiving your source code will simply have to read your README file, run the Configure script (which is self-documented), and then run make. Your package should then build cleanly on every UNIX platform.

The second component is the Makefile.SH generator, which is a generic configured Makefile, reusing some of the information figured out by Configure. Although you may write your own Makefile and then use makeSH to transform it into a Makefile.SH, it is better to write a generic Jmakefile description, which does not rely on a particular position within the source tree, and then use jmake to recursively build your Makefiles.

The third component is the package generator, which is used when it's time to build up the shell archives used to distribute your program. Although you may use your own archiving mechanism, the one included here knows about RCS files and will properly check out the lattest revisions, leaving your working files alone. The makedist program will also perform Copyright expansion, an useful feature when you share source files among more than one program, placed under distinct Copyright information.

The fourth and latest component is the patch generator, used to make updates of your sources, which can later be applied on the original distribution by using the patch program.

Before using any of the dist programs, you should probably identify your package by running the packinit program, which will create a .package file in the top-level directory of your package.

COMMANDS
The dist package implements the following commands (those tagged as library commands are to be found in the dist library and should not be made publicly available in everyone's path):

bindex
    builds the Index file (library).
jmake
    a Makefile.SH generator.
jmkmf
    bootstraps top-level Makefile.SH file.
kitpost
    posts distribution kits made by makedist.
kitsend
    sends distribution kits made by makedist.
makeSH
    wraps existing scripts into a .SH file.
makedist
    builds up distribution kits.
makegloss
    builds the Glossary file (library).
manicheck
    checks MANIFEST.new accuracy
manifake
    makes MANIFEST.new out of an existing MANIFEST.
manilist
    builds MANIFEST.new reports.
metaconfig
    a Configure script generator.
metalint
    a metaconfig unit consistency checker.
metaxref
    a metaconfig cross-reference builder.
packinit
    initializes a package (creates a .package file).
pat main patch generator.
patbase
    resets patch base to current version.
patcil
    checks new version in.
patclean
    remove working version of up-to-date files.
patcol
    checks file out.
patdiff
    builds (contextual) diffs for the patch.
patftp
    copies patches to public ftp directory.
patindex
    builds a patch index.
patlog
    handles ChangeLog file updates.
patmake
    puts diffs together into a patch.
patnotify
    notifies users that new patches have been released.
patpost
    posts patch to some newsgroup.
patsend
    mails patch to some people.
patsnap
    builds a release snapshot with files and RCS revisions.

PROFILE
Commands having a set of meaningful options (other than -h or -V) can also take arguments from the ~/.dist_profile file, or whatever file the DIST environment variable points to. Each line of the file is in the format:

profile-component: value

with shell-style comments (#) allowed provided they start the line.

Each command looks for a profile component entry matching its name and loads the value as if it were arguments specified on the command line. Those arguments precede any other argument specified manually, in case order is meaningful.

Some commands may also be configured from within the profile, by setting a specific variable attached to the command by a profile entry looking like this:

cmdname-variable: value

For instance, assuming the variable c-files is recognized by the metaconfig program, its default value could be overwritten by this profile entry:

metaconfig-c-files: suitable value

Only the first '-' after the command name is part of the syntax, the other one used in the variable name is pure convention. Please refer to the manual page of each command for a list of valid profile variables which may be set.

FILES
.MT Temporary directory created by metaconfig and friends.
.newer
    A list of files newer than patchlevel.h, used by the patching tools.
.package
    Main configuration file used by most of the dist tools to make them smart.
ChangeLog
    The file where changes are recorded. Its name may be configured by running packinit, but this is the default "generic" name under which it is referred to within the documentation.
Configure
    The generated configuration script.
Glossary
    A list of all the known portability symbols known by metaconfig. This file is located in the dist library directory.
I.fui
    Cross-reference file generated by metaxref, sorted by file, unit, item.
I.uif
    Cross-reference file generated by metaxref, sorted by unit, item, file.
Index
    A list of all the rules known by jmake. This file is located in the dist library directory.
Jmakefile
    Generic makefile description used by jmake.
MANIFEST
    List of all the files to be included in the distribution. Usually a copy (not a link) of MANIFEST.new.
MANIFEST.new
    List of all the files to be taken into account by the dist tools.
Makefile.SH
    The generated configured makefile (via Jmakefile) or hand-generated Makefile making use of known metaconfig symbols.
Obsolete
    A list of obsolete symbol used and their new equivalents.
RCS Directory where RCS files are stored.
README
    Main file explaining how to build your package.
U   Private unit directory.
Wanted
    File used by metaconfig, listing all the symbols used by the sources.
bugs
    Directory where patches are stored.
check.extra
    Extra files present in MANIFEST.new, generated by manicheck.
check.want
    Missing files from MANIFEST.new, generated by manicheck.
config_h.SH
    Generated config.h template.
confmagic.h
    Magic symbol remapping, activated via metaconfig's -M option.
hints
    This directory lists all the configuration hints for your package.
patchlevel.h
    File recording your package patch level, should not be part of MANIFEST.new, but may be listed in MANIFEST, at your discretion.
users
    File recording the users of your package, generated by mailagent's package command (see the MailAuthor.U unit and mailagent 3.0).

ENVIRONMENT
The following environment variable is paid attention to:

DIST
    Location of the dist profile, defaults to ~/.dist_profile. This variable is subject to ~name substitution, even if your shell does not support it.

AUTHORS
By chronological order:

Larry Wall <lwall@netlabs.com> (dist 2.0 in 1988)
Harlan Stenn <harlan@mumps.pfcs.com> (worked on dist 3.0 1990-1992)
Raphael Manfredi <Raphael.Manfredi@pobox.com> (dist 3.0 and integration 1991-1995)

Please look at the Credits file in the distribution source tree for a list of all the known contributors.

SEE ALSO
jmake(1), metaconfig(1), pat(1).