summaryrefslogtreecommitdiff
path: root/dist.man
diff options
context:
space:
mode:
authorManoj Srivastava <srivasta@debian.org>2008-05-30 12:42:47 -0700
committerManoj Srivastava <srivasta@debian.org>2008-05-30 12:42:47 -0700
commitceb3507a8fca872770b3dcd7e5c5b36179ab95b0 (patch)
treeb46b4e25cfff5f4c13a330b8428ceed343e3796c /dist.man
Import dist_3.5-236.orig.tar.gz
[dgit import orig dist_3.5-236.orig.tar.gz]
Diffstat (limited to 'dist.man')
-rw-r--r--dist.man317
1 files changed, 317 insertions, 0 deletions
diff --git a/dist.man b/dist.man
new file mode 100644
index 0000000..bfee179
--- /dev/null
+++ b/dist.man
@@ -0,0 +1,317 @@
+''' $Id$
+'''
+''' Copyright (c) 1991-1997, 2004-2006, Raphael Manfredi
+'''
+''' You may redistribute only under the terms of the Artistic Licence,
+''' as specified in the README file that comes with the distribution.
+''' You may reuse parts of this distribution only within the terms of
+''' that same Artistic Licence; a copy of which may be found at the root
+''' of the source tree for dist 4.0.
+'''
+''' $Log: dist.man,v $
+''' Revision 3.0.1.6 1995/05/12 11:57:53 ram
+''' patch54: updated my e-mail address
+'''
+''' Revision 3.0.1.5 1994/10/29 15:46:03 ram
+''' patch36: mentions new patlog script and ChangeLog file
+'''
+''' Revision 3.0.1.4 1994/05/06 13:54:17 ram
+''' patch23: extended copyright notice to 1994
+''' patch23: new script kitpost
+'''
+''' Revision 3.0.1.3 1994/01/24 13:55:41 ram
+''' patch16: documents profile and its components
+'''
+''' Revision 3.0.1.2 1993/11/10 17:31:03 ram
+''' patch14: added mention for new confmagic.h file
+'''
+''' Revision 3.0.1.1 1993/08/24 12:12:00 ram
+''' patch3: added entries for patnotify and patsnap
+'''
+''' Revision 3.0 1993/08/18 12:04:07 ram
+''' Baseline for dist 3.0 netwide release.
+'''
+'''
+.de Ex \" Start of Example
+.sp
+.in +5
+.nf
+..
+.de Ef \" End of Example
+.sp
+.in -5
+.fi
+..
+.TH DIST 1 ram
+.SH NAME
+dist \- introduction to dist
+.SH DESCRIPTION
+The \fIdist\fR package is a set of tools meant to ease the construction and
+maintenance of portable software. There are four distinct parts in \fIdist\fR,
+and it is also meant to be used with two external products, which are
+publicly available: \fImailagent\fR and \fIpatch\fR.
+.PP
+The first component is the \fIConfigure\fR script generator, which is a
+portability tool. It is automatically build up by \fImetaconfig\fR 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 \fIConfigure\fR script
+(which is self-documented), and then run \fImake\fR. Your package should then
+build cleanly on every UNIX platform.
+.PP
+The second component is the \fIMakefile.SH\fR generator, which is a generic
+configured Makefile, reusing some of the information figured out by
+.I Configure.
+Although you may write your own Makefile and then use \fImakeSH\fR to transform
+it into a \fIMakefile.SH\fR, it is better to write a generic \fIJmakefile\fR
+description, which does not rely on a particular position within the source
+tree, and then use \fIjmake\fR to recursively build your Makefiles.
+.PP
+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 \fImakedist\fR program will also perform Copyright expansion,
+an useful feature when you share source files among more than one program,
+placed under distinct Copyright information.
+.PP
+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 \fIpatch\fR program.
+.PP
+Before using any of the \fIdist\fR programs, you should probably identify your
+package by running the \fIpackinit\fR program, which will create
+a \fI.package\fR file in the top-level directory of your package.
+.SH COMMANDS
+The \fIdist\fR package implements the following commands (those
+tagged as \fIlibrary\fR commands are to be found in the dist
+library and should not be made publicly available in everyone's path):
+.TP 15
+bindex
+builds the \fIIndex\fR file (library).
+.PD 0
+.TP
+jmake
+a Makefile.SH generator.
+.TP
+jmkmf
+bootstraps top-level Makefile.SH file.
+.TP
+kitpost
+posts distribution kits made by \fImakedist\fR.
+.TP
+kitsend
+sends distribution kits made by \fImakedist\fR.
+.TP
+makeSH
+wraps existing scripts into a .SH file.
+.TP
+makedist
+builds up distribution kits.
+.TP
+makegloss
+builds the \fIGlossary\fR file (library).
+.TP
+manicheck
+checks MANIFEST.new accuracy
+.TP
+manifake
+makes MANIFEST.new out of an existing MANIFEST.
+.TP
+manilist
+builds MANIFEST.new reports.
+.TP
+metaconfig
+a Configure script generator.
+.TP
+metalint
+a metaconfig unit consistency checker.
+.TP
+metaxref
+a metaconfig cross-reference builder.
+.TP
+packinit
+initializes a package (creates a .package file).
+.TP
+pat
+main patch generator.
+.TP
+patbase
+resets patch base to current version.
+.TP
+patcil
+checks new version in.
+.TP
+patclean
+remove working version of up-to-date files.
+.TP
+patcol
+checks file out.
+.TP
+patdiff
+builds (contextual) diffs for the patch.
+.TP
+patftp
+copies patches to public ftp directory.
+.TP
+patindex
+builds a patch index.
+.TP
+patlog
+handles ChangeLog file updates.
+.TP
+patmake
+puts diffs together into a patch.
+.TP
+patnotify
+notifies users that new patches have been released.
+.TP
+patpost
+posts patch to some newsgroup.
+.TP
+patsend
+mails patch to some people.
+.TP
+patsnap
+builds a release snapshot with files and RCS revisions.
+.PD
+.SH PROFILE
+Commands having a set of meaningful options (other
+than \fB\-h\fR or \fB\-V\fR) can also take arguments from
+the \fI~/.dist_profile\fR file, or whatever file the \fIDIST\fR
+environment variable points to. Each line of the file is in the
+format:
+.Ex
+profile-component: \fIvalue\fR
+.Ef
+whith shell-style comments (#) allowed provided they start the line.
+.PP
+Each command looks for a profile component entry matching its
+name and loads the \fIvalue\fR as if it were arguments specified
+on the command line. Those arguments precede any other argument
+specified manually, in case order is meaningful.
+.PP
+Some commands may also be configured from within the profile, by setting
+a specific \fIvariable\fR attached to the command by a profile
+entry looking like this:
+.Ex
+cmdname-\fIvariable\fR: \fIvalue\fR
+.Ef
+For instance, assuming the variable \fIc-files\fR is recognized by the
+\fImetaconfig\fR program, its default value could be overwritten by
+this profile entry:
+.Ex
+metaconfig-c-files: \fIsuitable value\fR
+.Ef
+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.
+.SH FILES
+.PD 0
+.TP 15
+\&.MT
+Temporary directory created by \fImetaconfig\fR and friends.
+.TP
+\&.newer
+A list of files newer than \fIpatchlevel.h\fR, used by the patching tools.
+.TP
+\&.package
+Main configuration file used by most of the dist tools to make them smart.
+.TP
+ChangeLog
+The file where changes are recorded. Its name may be configured by
+running \fIpackinit\fR, but this is the default "generic" name under
+which it is referred to within the documentation.
+.TP
+Configure
+The generated configuration script.
+.TP
+Glossary
+A list of all the known portability symbols known by \fImetaconfig\fR. This
+file is located in the dist library directory.
+.TP
+I.fui
+Cross-reference file generated by \fImetaxref\fR, sorted by file, unit, item.
+.TP
+I.uif
+Cross-reference file generated by \fImetaxref\fR, sorted by unit, item, file.
+.TP
+Index
+A list of all the rules known by \fIjmake\fR. This file is located in the
+dist library directory.
+.TP
+Jmakefile
+Generic makefile description used by \fIjmake\fR.
+.TP
+MANIFEST
+List of all the files to be included in the distribution. Usually a copy (not
+a link) of MANIFEST.new.
+.TP
+MANIFEST.new
+List of all the files to be taken into account by the dist tools.
+.TP
+Makefile.SH
+The generated configured makefile (via Jmakefile) or hand-generated Makefile
+making use of known metaconfig symbols.
+.TP
+Obsolete
+A list of obsolete symbol used and their new equivalents.
+.TP
+RCS
+Directory where RCS files are stored.
+.TP
+README
+Main file explaining how to build your package.
+.TP
+U
+Private unit directory.
+.TP
+Wanted
+File used by \fImetaconfig\fR, listing all the symbols used by the sources.
+.TP
+bugs
+Directory where patches are stored.
+.TP
+check.extra
+Extra files present in MANIFEST.new, generated by \fImanicheck\fR.
+.TP
+check.want
+Missing files from MANIFEST.new, generated by \fImanicheck\fR.
+.TP
+config_h.SH
+Generated config.h template.
+.TP
+confmagic.h
+Magic symbol remapping, activated via metaconfig's \fB\-M\fR option.
+.TP
+hints
+This directory lists all the configuration hints for your package.
+.TP
+patchlevel.h
+File recording your package patch level, should not be part of MANIFEST.new,
+but may be listed in MANIFEST, at your discretion.
+.TP
+users
+File recording the users of your package, generated by mailagent's \fIpackage\fR
+command (see the MailAuthor.U unit and mailagent 3.0).
+.PD
+.SH ENVIRONMENT
+The following environment variable is paid attention to:
+.TP 15
+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.
+.SH AUTHORS
+By chronological order:
+.sp
+Larry Wall <lwall@netlabs.com> (dist 2.0 in 1988)
+.br
+Harlan Stenn <harlan@mumps.pfcs.com> (worked on dist 3.0 1990-1992)
+.br
+Raphael Manfredi <Raphael.Manfredi@pobox.com> (dist 3.0 and
+integration 1991-1995)
+.sp
+Please look at the \fICredits\fR file in the distribution source tree for a
+list of all the known contributors.
+.SH "SEE ALSO"
+jmake(1), metaconfig(1), pat(1).