DIST(7)                Miscellaneous Information Manual                DIST(7)

       dist - introduction to dist

       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.

       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.

       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

            profile-component: value

       whith 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.

       .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
       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
       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 Xa link) of
       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
       Obsolete       A list of obsolete symbol used and their new
       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
       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
       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).

       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.

       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 <ram@hptnos02.grenoble.hp.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.

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

                                      ram                              DIST(7)