Ubuntu Manpage: dist - introduction to dist

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

       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.

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