dist-3.0at70b/pat/README

   1 This is the root directory for pat tools.
   2
   3 This directory contains an automatic patch generator.  You must have RCS
   4 to use this.  You must also have run packinit in the top level directory
   5 of your package to create a .package file.
   6
   7 When you've modified a file in your package, the pat program is used to
   8 control the whole process.  The other programs can be called by hand, but
   9 usually needn't be.  Run pat from the top level directory of your package.
  10
  11 The pat, patcil, patdiff, and patbase programs take a list of filenames as
  12 arguments.  Alternately, a -a means all files listed in MANIFEST.
  13
  14 Patcil will create an RCS directory if necessary.  However, it may not check in
  15 things which require special initializaton properly.  For example, if you
  16 want to check in a shell script, you'd better make your RCS directory yourself
  17 and then say
  18
  19         rcs -i -c'# ' blurfl.xsh
  20
  21 before running pat or patcil.  Otherwise the RCS log may not be commented
  22 properly.  Unless of course you are using a standard extension (like .c for
  23 a C file) or have placed the proper comments in front of the $Log marker
  24 within the file itself--patcil will then correctly guess the type of
  25 comment required.
  26
  27 Patdiff will create a bugs directory in your top level directory, and will want
  28 to find a patchlevel.h file in that same directory.  Everything is done from
  29 that top level directory--don't put any patchlevel.h or bugs directories in
  30 your subdirectories.  Each subdirectory has its own RCS directory though.
  31
  32 Patpost, patsend and patftp may be used to post to Usenet, mail to someone,
  33 or copy patches to your ftp directory.  They take a destination and a list
  34 of patches to process.
  35
  36 Those pat tools are an hopefully enhanced version of the tools that
  37 came with Larry Wall's dist 2.0. There are however a few new scripts:
  38
  39     - patclean, which checks in the mods and removes the working files.
  40     - patcol, which restores the files removed by a patclean.
  41     - patname, which sets a symbolic version number.
  42
  43 Here is the way I am using the pat tools...
  44
  45 First, I set up a MANIFEST.new file. If you are converting an existing
  46 distribution to use dist, the manifake script will convert a MANIFEST
  47 into a MANIFEST.new (removing the possible archive number column).
  48
  49 Then I run packinit to modify the version number and set up things
  50 correctly. The package is then ready to be placed under pat control.
  51 I make sure the file patchlevel.h is correctly set and I run:
  52
  53         patcil -f -a -s
  54         touch patchlevel.h
  55         find . -name "*~" -exec /bin/rm -f {} \; -print
  56
  57 There is a prototypical patchlevel.h file in this directory, so you
  58 might want to have a look at it.
  59
  60 [If you are planning on using the mailagent to send the patches (and sort
  61 your mail -- that's its primary goal now), the you must make sure
  62 the patchelevel.h file is locatated in the root directory of your package.
  63 The mailagent program is available separately, and was posted on the
  64 comp.sources.misc newsgroup]
  65
  66 Now everything is ready. The distribution is frozen, the bugs directory
  67 has been created. I issue a makedist -v to create the distribution kits.
  68 Eventually I set up the mailagent so that people can request for the
  69 distribution automatically. If I want to create a directory containing
  70 the lattest sources (to be able to `kit' them to someone using the kit
  71 program -- posted to comp.sources.unix), I use:
  72
  73         makedist -c <package>-<version>@<patchlevel>
  74
  75 for instance, for dist 2.9 at PL26
  76
  77         makedist -c dist-2.9@26
  78
  79 which I can then send to people directly with kit (which is NOT part
  80 of this release).
  81
  82 As I receive patches or find some bugs, I edit the files and make the
  83 modifications. When I want to issue an official patch, I run:
  84
  85         pat -n
  86
  87 and one or more patches are issued. You can compress the patches in the
  88 bugs subdirectory, since the mailpatch program knows about that. Also
  89 patindex will correctly uncompress them.
  90
  91 When I need to clean up the distribution directory, I use:
  92
  93         patclean -a
  94
  95 which checks in every changes and removes the working files. The whole
  96 set of working files can then be restored by:
  97
  98         patcol -a
  99
 100 Sometimes, I made a couple of modification and I don't want to issue
 101 a patch right now. I then run:
 102
 103         patcil -a
 104
 105 which checks in the changes. You can run this as many times as you want,
 106 because patcil will skip unchanged file and remembers the last time you
 107 issued a patch.
 108
 109 If you are still using RCS 4.3, be sure you use makedist and not your
 110 own shell archiver, as the $Locker symbol has an annoying expansion
 111 which makes patch to fail when applyed. I'm not sure this was correctly
 112 fixed with RCS 5.5 as I am not using it yet for various reasons.
 113
 114 In any case, if you are using the copyright expansion feature (i.e. the
 115 stuffing of the COPYRIGHT token surrounded by '@' -- can't do it here
 116 or it will get expanded...), then you must use makedist to make sure
 117 the copyright is properly written in all your files. Distributing files
 118 with an un-expanded COPYRIGHT token in them would be a disaster, since
 119 the patching system will also expand them before building a patch and
 120 some of your hunks may not apply correctly.