How to use and make QuakeC patch files
by Jeff Epler <jepler@inetnebr.com>
3 August 1996

This is a draft, and probably isn't that great an explanation.  Please
mail me with questions about the directions, or suggestions on how to
improve this document.

Some parts of this document were contributed by Kyle R. Hofmann
<rhofmann@crl.com>, and various other changes were also suggested via email.

You should always be able to find the newest version of this
document at http://cse.unl.edu/~jepler/quakec/howpatch.txt.  If I
take the time to make a hypertext version of this file, it will be at
http://cse.unl.edu/~jepler/quakec/howpatch.html.  This file is also
uploaded to ftp.cdrom.com.

How to use QuakeC patch files
-----------------------------

   Get and install a version of patch suitable for your OS.  Under most
   unicies, (including Linux) this is already available.  For DOS, you
   want
    ftp://oak.oakland.edu/pub/simtelnet/gnu/djgpp/v2gnu/pat21b.zip
    ftp://ftp.simtelnet.com/pub/simtelnet/gnu/djgpp/v2gnu/pat21b.zip
   I don't know where a windows 95/nt version of patch resides, but the
   DOS version should execute just fine.  If you want to compile your own
   version of patch, get it from
     ftp://prep.ai.mit.edu/pub/gnu/diffutils-2.7.tar.gz

   Get a version of qcc suitable for your OS.  Look around at
    ftp://ftp.cdrom.com/pub/idgames/idstuff/source or
    ftp://ftp.cdrom.com/pub/idgames2/quakec or
    ftp://ftp.cdrom.com/pub/idgames2/utils for one.

   Get a patch file.  One such file will reside at
    ftp://ftp.cdrom.com/pub/idgames2/quakec/monsters/friend.zip
   Unzip it, and you'll get friend.pat.

   Put the patch.exe and qccdos.exe files in a directory in your PATH.

   Make a new directory and copy the unchanged files from v101qc to this
   new directory.  Change to the new directory.  Unzip the patch file
   (friend.zip) here, or move it from where you unzipped it. (If you are
   smart or willing to spend much time, you can add several patches to
   the same source, getting all the features.  However, there are likely
   to be rejects [see below] or unwanted side effects of putting several
   patches together)

     patch < friend.pat or
     type friend.pat | patch

   Inspect the directory for any "rejected" patches.  If there are some,
   you should use your favorite editor to inspect the reject file (named
   under unix whatever.qc.rej, and under DOS whatever.qc#) and make by
   hand the changes that are required.  + marks lines present in the
   new version but not in the old, and - marks lines present in the old
   but not in the new.  Ideally, you should have no rejected patches.
   If you have many rejected patches, your command-line may have been
   wrong for patch.  Files ending in ~ are backups of files changed by the
   patch, and can generally be deleted.

   Run qcc to compile a new progs.dat (depending on the setup, progs.dat
   may be created in the current directory or the parent directory.
   Change the first line in progs.src to move where progs.dat will be
   created), copy it to quake\whatever, and run quake -game whatever.
   You're done.

   To undo a patch, use the command

     patch -R < friend.pat

   Make sure you type an uppercase R.

Errors installing QuakeC patches
--------------------------------

  patch is not a perfect utility.  If the QuakeC source which you are
trying to patch is already modified, or if the file has had lines added
or subtracted to it, you may get errors.  In serious cases, you may get
"rejected hunks", patches which could not be applied at all.  Warning and
errors include:

  - Offsets.  Offsets are nothing much to be concerned about, usually.
    They indicate that patch did not place the patch on the exact line
    specified; instead, patch placed the patch several lines away.  This
    is usually indicative of previously changed QuakeC sources, and in
    most cases may be safely ignored.  However, if there is an
    excessively large offset, you should check to make sure the patch has
    been applied properly.

  - Fuzz factor.  Fuzz factor indicates that the exact context could not
    be found, and so context lines at the beginning or end of the patch
    were ignored.  Be suspicious of patches which have a fuzz factor.
    Though they may be a result of changed sources, they can also be a
    result of an improperly applied or created patch.  Be sure to check
    to ensure that the patch is properly applied.

  - Rejected hunks.  Rejected hunks are sections of a patch which could
    not be applied at all.  They will be named foo.qc.rej or foo.qc#
    (replace foo with the filename of the .qc file which could not be
    patched).  They may be hand applied by going to the lines specified
    at the start of the hunk and the entire hunk being copied in.  If the
    hunk is part of a context diff, be sure to install the second half;
    that's the changed version (you can use the first half of the hunk
    to determine where the patch should be applied).  If the hunk is part
    of a unified diff, be sure to remove the sections with as - prefixing
    them and remove the + prefixing other lines (but do not remove the
    lines with the +'s)  However, be *extremely careful* --- rejected
    hunks may be completely incompatible with the code you currently have
    installed.

Installing multiple patch files
-------------------------------

   Installing multiple patch files is easy and simple.  Simply get both
   patches, and install them using the procedure listed above.  You will
   most likely encounter some of the errors listed above.  In this case, do
   not worry if it's simply a case of a minor offset.  Most likely the file
   has been modified by both patches and you're seeing a side effect.  Worry
   more if a fuzz factor is needed; it might indicate that the same portion
   of code is being modified by two patches.  Worry most when a hunk is
   rejected --- that usually indicates that the exact same portion of code
   was modified by both patches.  It might make the two incompatible.
 

How to make QuakeC patch files
------------------------------

   Get and install a copy of diff for your machine.  For unix, again it's
   included.  For DOS, get
    ftp://oak.oakland.edu/pub/simtelnet/gnu/djgpp/v2gnu/dif271b.zip
    ftp://ftp.simtelnet.com/pub/simtelnet/gnu/djgpp/v2gnu/dif271b.zip
   Again, I don't know about w95/w32/wnt, except that the dos version
   should work in the dos box.

   Get a directory with your mods in it and a directory with v101qc source
   side by side.

   diff -ur --new-file v101qc yourdir > yourdir.pat

   zip or otherwise compress yourdir.pat

   Share with the world.

   You should probably always diff against v101qc sources unless you have
   a good reason not to.  When you diff against v101qc, anyone can use
   those files and your .pat file to get a replica of your sources.  One
   time to use a different set of 'old' files would be something like this:

     John Doe made code for a weapon that turned monsters into little dogs.
     The only problem is that his files don't quite work -- Ammo can be
     turned into a dog too.  You fix this up and want to let John know.  So
     you make a diff like this:

     diff -ur --new-file jdgun yourgun > yourgun.pat

     Now, John Doe can see the differences between his gun code and your
     gun code, and as a bonus the file is smaller.  You could also hand it
     out to people who have his original gun diff as well.

Other problems
--------------

If you get an error about being unable to create a file /tmp/paaaax
(For instance), just create a \TMP directory on the drive where you were
trying to run patch.  I don't know if having the TEMP or TMP environment
variable set to an existing directory will also help this.

If you get an error about DPMI, copy cwsdpmi.exe from the quake directory 
onto your path.
