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.
SEE ALSO¶
jmake(1),
metaconfig(1),
pat(1).