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

Wed Jul 9 05:36:00 GMT 2003

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/