dist-3.0at70b/dist.man

   1 ''' $Id: dist.man,v 3.0.1.6 1995/05/12 11:57:53 ram Exp $
   2 '''
   3 '''  Copyright (c) 1991-1993, Raphael Manfredi
   4 '''
   5 '''  You may redistribute only under the terms of the Artistic Licence,
   6 '''  as specified in the README file that comes with the distribution.
   7 '''  You may reuse parts of this distribution only within the terms of
   8 '''  that same Artistic Licence; a copy of which may be found at the root
   9 '''  of the source tree for dist 3.0.
  10 '''
  11 ''' $Log: dist.man,v $
  12 ''' Revision 3.0.1.6  1995/05/12  11:57:53  ram
  13 ''' patch54: updated my e-mail address
  14 '''
  15 ''' Revision 3.0.1.5  1994/10/29  15:46:03  ram
  16 ''' patch36: mentions new patlog script and ChangeLog file
  17 '''
  18 ''' Revision 3.0.1.4  1994/05/06  13:54:17  ram
  19 ''' patch23: extended copyright notice to 1994
  20 ''' patch23: new script kitpost
  21 '''
  22 ''' Revision 3.0.1.3  1994/01/24  13:55:41  ram
  23 ''' patch16: documents profile and its components
  24 '''
  25 ''' Revision 3.0.1.2  1993/11/10  17:31:03  ram
  26 ''' patch14: added mention for new confmagic.h file
  27 '''
  28 ''' Revision 3.0.1.1  1993/08/24  12:12:00  ram
  29 ''' patch3: added entries for patnotify and patsnap
  30 '''
  31 ''' Revision 3.0  1993/08/18  12:04:07  ram
  32 ''' Baseline for dist 3.0 netwide release.
  33 '''
  34 '''
  35 .de Ex          \" Start of Example
  36 .sp
  37 .in +5
  38 .nf
  39 ..
  40 .de Ef          \" End of Example
  41 .sp
  42 .in -5
  43 .fi
  44 ..
  45 .TH DIST 1 ram
  46 .SH NAME
  47 dist \- introduction to dist
  48 .SH DESCRIPTION
  49 The \fIdist\fR package is a set of tools meant to ease the construction and
  50 maintenance of portable software. There are four distinct parts in \fIdist\fR,
  51 and it is also meant to be used with two external products, which are
  52 publicly available: \fImailagent\fR and \fIpatch\fR.
  53 .PP
  54 The first component is the \fIConfigure\fR script generator, which is a
  55 portability tool. It is automatically build up by \fImetaconfig\fR from your
  56 sources and a set of units. Ideally, the end-user receiving your source code
  57 will simply have to read your README file, run the \fIConfigure\fR script
  58 (which is self-documented), and then run \fImake\fR. Your package should then
  59 build cleanly on every UNIX platform.
  60 .PP
  61 The second component is the \fIMakefile.SH\fR generator, which is a generic
  62 configured Makefile, reusing some of the information figured out by
  63 .I Configure.
  64 Although you may write your own Makefile and then use \fImakeSH\fR to transform
  65 it into a \fIMakefile.SH\fR, it is better to write a generic \fIJmakefile\fR
  66 description, which does not rely on a particular position within the source
  67 tree, and then use \fIjmake\fR to recursively build your Makefiles.
  68 .PP
  69 The third component is the package generator, which is used when it's time
  70 to build up the shell archives used to distribute your program. Although you
  71 may use your own archiving mechanism, the one included here knows about RCS
  72 files and will properly check out the lattest revisions, leaving your working
  73 files alone. The \fImakedist\fR program will also perform Copyright expansion,
  74 an useful feature when you share source files among more than one program,
  75 placed under distinct  Copyright information.
  76 .PP
  77 The fourth and latest component is the patch generator, used to make updates
  78 of your sources, which can later be applied on the original distribution by
  79 using the \fIpatch\fR program.
  80 .PP
  81 Before using any of the \fIdist\fR programs, you should probably identify your
  82 package by running the \fIpackinit\fR program, which will create
  83 a \fI.package\fR file in the top-level directory of your package.
  84 .SH COMMANDS
  85 The \fIdist\fR package implements the following commands (those
  86 tagged as \fIlibrary\fR commands are to be found in the dist
  87 library and should not be made publicly available in everyone's path):
  88 .TP 15
  89 bindex
  90 builds the \fIIndex\fR file (library).
  91 .PD 0
  92 .TP
  93 jmake
  94 a Makefile.SH generator.
  95 .TP
  96 jmkmf
  97 bootstraps top-level Makefile.SH file.
  98 .TP
  99 kitpost
 100 posts distribution kits made by \fImakedist\fR.
 101 .TP
 102 kitsend
 103 sends distribution kits made by \fImakedist\fR.
 104 .TP
 105 makeSH
 106 wraps existing scripts into a .SH file.
 107 .TP
 108 makedist
 109 builds up distribution kits.
 110 .TP
 111 makegloss
 112 builds the \fIGlossary\fR file (library).
 113 .TP
 114 manicheck
 115 checks MANIFEST.new accuracy
 116 .TP
 117 manifake
 118 makes MANIFEST.new out of an existing MANIFEST.
 119 .TP
 120 manilist
 121 builds MANIFEST.new reports.
 122 .TP
 123 metaconfig
 124 a Configure script generator.
 125 .TP
 126 metalint
 127 a metaconfig unit consistency checker.
 128 .TP
 129 metaxref
 130 a metaconfig cross-reference builder.
 131 .TP
 132 packinit
 133 initializes a package (creates a  .package file).
 134 .TP
 135 pat
 136 main patch generator.
 137 .TP
 138 patbase
 139 resets patch base to current version.
 140 .TP
 141 patcil
 142 checks new version in.
 143 .TP
 144 patclean
 145 remove working version of up-to-date files.
 146 .TP
 147 patcol
 148 checks file out.
 149 .TP
 150 patdiff
 151 builds (contextual) diffs for the patch.
 152 .TP
 153 patftp
 154 copies patches to public ftp directory.
 155 .TP
 156 patindex
 157 builds a patch index.
 158 .TP
 159 patlog
 160 handles ChangeLog file updates.
 161 .TP
 162 patmake
 163 puts diffs together into a patch.
 164 .TP
 165 patnotify
 166 notifies users that new patches have been released.
 167 .TP
 168 patpost
 169 posts patch to some newsgroup.
 170 .TP
 171 patsend
 172 mails patch to some people.
 173 .TP
 174 patsnap
 175 builds a release snapshot with files and RCS revisions.
 176 .PD
 177 .SH PROFILE
 178 Commands having a set of meaningful options (other
 179 than \fB\-h\fR or \fB\-V\fR) can also take arguments from
 180 the \fI~/.dist_profile\fR file, or whatever file the \fIDIST\fR
 181 environment variable points to. Each line of the file is in the
 182 format:
 183 .Ex
 184 profile-component: \fIvalue\fR
 185 .Ef
 186 whith shell-style comments (#) allowed provided they start the line.
 187 .PP
 188 Each command looks for a profile component entry matching its
 189 name and loads the \fIvalue\fR as if it were arguments specified
 190 on the command line. Those arguments precede any other argument
 191 specified manually, in case order is meaningful.
 192 .PP
 193 Some commands may also be configured from within the profile, by setting
 194 a specific \fIvariable\fR attached to the command by a profile
 195 entry looking like this:
 196 .Ex
 197 cmdname-\fIvariable\fR: \fIvalue\fR
 198 .Ef
 199 For instance, assuming the variable \fIc-files\fR is recognized by the
 200 \fImetaconfig\fR program, its default value could be overwritten by
 201 this profile entry:
 202 .Ex
 203 metaconfig-c-files: \fIsuitable value\fR
 204 .Ef
 205 Only the first '-' after the command name is part of the syntax, the
 206 other one used in the variable name is pure convention. Please refer to the
 207 manual page of each command for a list of valid profile variables
 208 which may be set.
 209 .SH FILES
 210 .PD 0
 211 .TP 15
 212 \&.MT
 213 Temporary directory created by \fImetaconfig\fR and friends.
 214 .TP
 215 \&.newer
 216 A list of files newer than \fIpatchlevel.h\fR, used by the patching tools.
 217 .TP
 218 \&.package
 219 Main configuration file used by most of the dist tools to make them smart.
 220 .TP
 221 ChangeLog
 222 The file where changes are recorded. Its name may be configured by
 223 running \fIpackinit\fR, but this is the default "generic" name under
 224 which it is referred to within the documentation.
 225 .TP
 226 Configure
 227 The generated configuration script.
 228 .TP
 229 Glossary
 230 A list of all the known portability symbols known by \fImetaconfig\fR. This
 231 file is located in the dist library directory.
 232 .TP
 233 I.fui
 234 Cross-reference file generated by \fImetaxref\fR, sorted by file, unit, item.
 235 .TP
 236 I.uif
 237 Cross-reference file generated by \fImetaxref\fR, sorted by unit, item, file.
 238 .TP
 239 Index
 240 A list of all the rules known by \fIjmake\fR. This file is located in the
 241 dist library directory.
 242 .TP
 243 Jmakefile
 244 Generic makefile description used by \fIjmake\fR.
 245 .TP
 246 MANIFEST
 247 List of all the files to be included in the distribution. Usually a copy (not
 248 a link) of MANIFEST.new.
 249 .TP
 250 MANIFEST.new
 251 List of all the files to be taken into account by the dist tools.
 252 .TP
 253 Makefile.SH
 254 The generated configured makefile (via Jmakefile) or hand-generated Makefile
 255 making use of known metaconfig symbols.
 256 .TP
 257 Obsolete
 258 A list of obsolete symbol used and their new equivalents.
 259 .TP
 260 RCS
 261 Directory where RCS files are stored.
 262 .TP
 263 README
 264 Main file explaining how to build your package.
 265 .TP
 266 U
 267 Private unit directory.
 268 .TP
 269 Wanted
 270 File used by \fImetaconfig\fR, listing all the symbols used by the sources.
 271 .TP
 272 bugs
 273 Directory where patches are stored.
 274 .TP
 275 check.extra
 276 Extra files present in MANIFEST.new, generated by \fImanicheck\fR.
 277 .TP
 278 check.want
 279 Missing files from MANIFEST.new, generated by \fImanicheck\fR.
 280 .TP
 281 config_h.SH
 282 Generated config.h template.
 283 .TP
 284 confmagic.h
 285 Magic symbol remapping, activated via metaconfig's \fB\-M\fR option.
 286 .TP
 287 hints
 288 This directory lists all the configuration hints for your package.
 289 .TP
 290 patchlevel.h
 291 File recording your package patch level, should not be part of MANIFEST.new,
 292 but may be listed in MANIFEST, at your discretion.
 293 .TP
 294 users
 295 File recording the users of your package, generated by mailagent's \fIpackage\fR
 296 command (see the MailAuthor.U unit and mailagent 3.0).
 297 .PD
 298 .SH ENVIRONMENT
 299 The following environment variable is paid attention to:
 300 .TP 15
 301 DIST
 302 Location of the dist profile, defaults to ~/.dist_profile. This variable is
 303 subject to ~name substitution, even if your shell does not support it.
 304 .SH AUTHORS
 305 By chronological order:
 306 .sp
 307 Larry Wall <lwall@netlabs.com> (dist 2.0 in 1988)
 308 .br
 309 Harlan Stenn <harlan@mumps.pfcs.com> (worked on dist 3.0 1990-1992)
 310 .br
 311 Raphael Manfredi <ram@hptnos02.grenoble.hp.com> (dist 3.0 and
 312 integration 1991-1995)
 313 .sp
 314 Please look at the \fICredits\fR file in the distribution source tree for a
 315 list of all the known contributors.
 316 .SH "SEE ALSO"
 317 jmake(1), metaconfig(1), pat(1).