Patchable Nethack
------------------------------------------------------------------------------

There are a number of lists in the Nethack source code which are
commonly updated by patches.  If you apply 2 patches which both add an
item to the same list, the second won't apply cleanly and you'll have to
add its item to the list by hand.  This patch, which I've been thinking
of as patchable Nethack, is an attempt to make this better.

This patch is available at http://www.argon.org/~roderick/nethack/.



For Users (people applying patches and compiling the code)
------------------------------------------------------------------------------

You'll only want to apply this patch if another patch you want to use is
based on it.  The description of the patch should tell you that's so.

Apply this patch in the normal manner

    $ cd nethack-3.4.1
    $ patch -p1 < ../nethack-3.4.1-patchable.1

and then apply the other patches you want to use as you otherwise would
have.



For Patch Authors
------------------------------------------------------------------------------

Here's an example which demonstrates the problem and the fix.  Take this
section of util/makedefs.c:

    #ifdef ZEROCOMP
		    "zero-compressed save files",
    #endif
		    "basic NetHack features"
	    };

    static const char *window_opts[] = {

This is the list of compiled-in options you see with the #version
command.  It's a good idea for patches to add themselves to this list.

Say you had patch.grue which included this hunk:

    --- makedefs.c.orig	2003-03-13 18:55:04.000000000 -0500
    +++ makedefs.c.grue	2003-03-13 18:56:19.000000000 -0500
    @@ -1,6 +1,7 @@
     #ifdef ZEROCOMP
		    "zero-compressed save files",
     #endif
    +		    "patch: GRUE repellant 3.4.1-1",
		    "basic NetHack features"
	    };

and patch.froboz-wand which included this one:

    --- makedefs.c.orig	2003-03-13 18:55:04.000000000 -0500
    +++ makedefs.c.f-w	2003-03-13 18:58:55.000000000 -0500
    @@ -1,6 +1,9 @@
     #ifdef ZEROCOMP
		    "zero-compressed save files",
     #endif
    +#ifdef FROBOZ_WAND
    +		    "patch: the Froboz wand (v1)",
    +#endif
		    "basic NetHack features"
	    };

They conflict, so you'd have to apply one of them by hand.  If instead
of the regular makedefs.c you started with this:

    #ifdef ZEROCOMP
                    "zero-compressed save files",
    #endif
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
                    "basic NetHack features"
            };

    static const char *window_opts[] = {

The technique is for each patch to add its new code between the 2 blocks
of comment lines, then duplicate the second block.  Eg, the source
from the Grue code would look like:

    #ifdef ZEROCOMP
                    "zero-compressed save files",
    #endif
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
                    "patch: GRUE repellant 3.4.1-1",
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
                    "basic NetHack features"
            };

    static const char *window_opts[] = {

When you diff these 2 versions, the only context is the patch point
comment above and below the new code:

    --- makedefs-patchable.c        2003-03-18 18:29:06.000000000 -0500
    +++ makedefs-patchable.c.grue   2003-03-18 18:29:40.000000000 -0500
    @@ -4,6 +4,10 @@
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
    +               "patch: GRUE repellant 3.4.1-1",
    +               /*
    +                * patch list patch point; see $top/README.patchable
    +                */
                    /*
                     * patch list patch point; see $top/README.patchable
                     */

When you apply this diff, patch will look for a place in the source which
has 2 of the patch point comments right next to each other.  There's only
one place like that, so it updates the code at that point.  Because the
patch contained a new patch point comment at the end, the resulting code
still has only 1 place where there are 2 patch point comments right next
to each other, so if you apply another similar patch, such as

    --- makedefs-patchable.c        2003-03-18 18:29:06.000000000 -0500
    +++ makedefs-patchable.c.f-w    2003-03-18 18:29:25.000000000 -0500
    @@ -4,6 +4,12 @@
                    /*
                     * patch list patch point; see $top/README.patchable
                     */
    +#ifdef FROBOZ_WAND
    +               "patch: the Froboz wand (v1)",
    +#endif
    +               /*
    +                * patch list patch point; see $top/README.patchable
    +                */
                    /*
                     * patch list patch point; see $top/README.patchable
                     */

it will also apply cleanly.  Any number of patches like this can be
applied without hand editing.

Suggestions:

  - Add your patch to the patch list patch point in util/makedefs.c.
    Include a version number.

  - If inclusion of your code is conditional based on a #define, add it
    to the options patch point in include/config.h.  Have the patch add
    it in a #defined state, since if somebody is applying the patch
    they'll probably want it turned on.

  - Let me know if you need a new patch point added.

Roderick Schertler <roderick@argon.org>