Provided by: dist_3.5-30-3_all bug

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

                                      ram                              DIST(7)