Creating Patches (Was: Re: http://gcc.gnu.org/java/done.html)

[Ranjit Mathew]

Erik Poupaert wrote:
> By the way, does anybody know a tutorial for dummies on the "patch" and "diff"
> utilities? Next time, I'll try to use these.

Google for "creating patch".

Or read the "patch" manual pages (or "patch --help") and
the "diff" manual pages (or "diff --help").

Or use CVS.

Or read below :-)

This is the method *I* follow to create and submit patches.

I do not use CVS and veterans might frown or even
cringe at some of these steps, but it works for me and
no one seems to have noticed - at least not to the extent
of actually complaining about it. :-)

I assume you are on Linux or at least a system where
Larry Wall's "patch" program and the GNU "diff" utility
are available and are in your PATH. (On Windows for
example, CygWin and MSYS are such environments.)

To make my job easier, I use a couple of scripts that
you can get from:

http://ranjitmathew.tripod.com/phartz/gcj/getdiff.sh
http://ranjitmathew.tripod.com/phartz/gcj/makepatch.sh

You might want to download them and put them in your PATH.

To create and submit a patch (assuming of course that you
have tested out your changes thoroughly):

0. Find out where the relevant ChangeLog file is - patches
   should be made relative to this folder. For example,
   the "libjava" folder contains the ChangeLog file for
   almost all the Java runtime classes provided by libgcj.
   Let's say you want to submit a patch that affects
   the "getClasses( )" method in "java/lang/Class.java".

1. Copy the *original unmodified copies* of all the affected
   files *maintaining the folder structure* to a temporary
   folder, say, "/tmp/mypatch". In our example, you should
   now have an unmodified "/tmp/mypatch/java/lang/Class.java".

2. Create a dummy ChangeLog (and its dummy backup) by
   executing "touch ChangeLog ChangeLog.orig" in the
   temporary folder - in our example "/tmp/mypatch".

3. Edit "ChangeLog" to describe your change. For example:

   2003-07-09  Erik Poupaert  <erik.poupaert@skynet.be>

       * java/lang/Class.java (getClasses): Fix something.

   More info on ChangeLogs and ChangeLog entries can be
   found at: http://www.gnu.org/prep/standards_40.html.

   Read the other ChangeLog entries to get an idea of how
   to write them. Note that there's a TAB before the '*'
   and every line in the description following it. Be
   careful to use an editor that doesn't act too smart
   with TABs and/or spaces.

4. Now *before applying your changes*, back up the original
   files *in their respective folders* with an ".orig"
   extension. In our example, you should now have
   "/tmp/mypatch/java/lang/Class.java.orig" in addition to
   the original file.

5. Now apply your changes to the source files. In our
   example, make the changes to the
   "/tmp/mypatch/java/lang/Class.java" file.

6. Execute "makepatch.sh" in the "/tmp/mypatch" folder to
   get the complete patch - redirect the output of this
   script to a file, say, "mypatch.txt".

7. This step is optional, but is highly recommended for
   "portable" ChangeLog entries in the patches - get the
   "clcleanup" and "fixpatch" scripts from:

   http://savannah.gnu.org/cgi-bin/viewcvs/cvs-utils/cvs-utils/

   Once again, put them in a place that's in your PATH.

   Run your patch through "clcleanup" thus:

       clcleanup mypatch.txt > patch.txt

8. Verify that your patch does indeed apply cleanly to
   an *unpatched source tree* by running it like this in
   the "libjava" folder:

       patch --dry-run -p0 < /tmp/mypatch/patch.txt

9. If you are satisfied with your patch, submit it to
   the relevant mailing list. In our example, that would
   be java-patches@gcc.gnu.org.

10. Cross your fingers and hope that the maintainers
    review and approve your patch - if not, lather, rinse,
    repeat. :-)

Step #8 can also be used to also apply your changes to
an unmodified source tree so that you can test it out.
In this case, you need to execute:

   patch -p0 -b -z .orig </tmp/mypatch/patch.txt

This backs up all the original files with a ".orig"
extension in their respective folders before applying
the changes.

If your changes SNAFU things up, you can easily retract
your changes by executing:

   patch -R -p0 </tmp/mypatch/patch.txt

Hope this helps.

Ranjit.

-- 
Ranjit Mathew          Email: rmathew AT hotmail DOT com

Bangalore, INDIA.      Web: http://ranjitmathew.tripod.com/