Making patches and diffs for ioquake3 on Windows

From ioquake3 wiki
Jump to: navigation, search


Return to Building ioquake3

This is based off of these instructions: http://www.ioquake.org/forums/viewtopic.php?f=12&t=110

Thanks to kevlarman for providing feedback and helping to finetune this process!

This will work for Win2K, XP, and Vista.


Prerequisites:

1) you have to have your compiling environment set up akin to how I outlined it in one of the other "compiling for dummies" tutorials.
2) if you already have your own setup and it works, this how-to might alert you to one or two issues you didn't know or think about so it might be worth a read.


Problem:

1) Windows platforms insert extra linefeed characters on text files they edit. The ioquake3 source is based on the unix standard of text files which doesn't have this extra linefeed character.
2) when making a patch or diffing files, because the "end of line" determination for windows is different than unix, the patch/diff utility will find EVERY SINGLE LINE in the source file as "different" and put that into a patch. This means that your patch file will have a bunch of "-" lines to remove the ENTIRE old file and then a bunch of "+" to add the ENTIRE new Windows-linefeeded file. This means your patch file is twice the size of the original source file you want to patch! That's just poor.
3) this also means that when diffing files, if you cut and paste, the diff utility will potentially find "differences" in lines that are identical except for the end of line differences. While technically correct, that's functionally useless. You're looking for that change in "clc.voipTarget1 = clc.voipTarget2 = clc.voipTarget3 = 0;", not for some stupid whitespace at the end of a line.
4) as a final kick to the pants, when you run a diff/patch program on windows, while your code might still be unix-style (if you edited and saved the .c files in Visual Studio or vi or notepad++, etc.), when the diff/patch program generates the patch, it writes the header part of the resulting file with windows-style newlines even though it then writes the code part with unix-style newlines. So to get your patch consistent with its own newlines, you still should run it through a newline conversion/stripping tool.


Solution workflow:

1) edit the source files however you want.
2) run a "dos2unix" type tool on the source file in order to revert to the the original unix-style format.
3) run your diff/patch utility on that resulting file to get a proper patch made.
4) run a "dos2unix" type tool on the resulting patch file.


Installing a DOS 2 Unix converter:

1) download this utility: http://sysd.org/stas/node/34
2) extract it to somewhere logical, like in your Program Files folder.
3) for Windows 2000 and Windows XP, simply double-click the "install.bat" file.
4) for Windows Vista, click Start, then Programs, then Accessories, then right-click Command Prompt and select "Run as Administrator". Navigate to the folder you installed ToFroWin into and type "install.bat" and hit Enter.
5) to verify that the utility has installed properly, right-click any straight text file (like readme.txt) and click on "Convert text mode" to see your options. Convert it from DOS to Unix. This program converts the files IN PLACE, so don't be stupid about what you convert. Back up the file to a different name first if you're really paranoid. Open the resulting file in notepad and it should look all horribly unformatted. Convert it back from Unix to DOS and check it again in notepad and it should look fine again.
6) pretty much every other dos2unix util I looked at was more of a pain to use, i.e. command line only or you had to compile the thing yourself.


Using TortoiseSVN to generate a patch:

1) edit any .c file in the ioquake3 source and save your changes.
2) right-click the file and convert it from DOS to Unix.
3) right-click the ROOT FOLDER OF YOUR SOURCE and choose "TortoiseSVN" and then "Create patch..."
4) click the Ok button and choose a name to save the patch to. If you edit q3asm.c you might want to name the patch "q3asm". The patch tool will automatically append .patch to the end of the name.
5) you should see the resulting patch file displayed for review. If you did it correctly from the ROOT FOLDER OF YOUR SOURCE, the path at the top should be something like "Index: code/tools/asm/q3asm.c" and NOT something like "Index: q3asm.c". If the patch looks fine, close the window displaying it.
6) right-click the resulting patch file and convert it from DOS to Unix. TortoiseSVN's patch creation tool adds some windows-specific linefeeds in the file so we have to get rid of those before submitting the patch file.


Using "svn diff" to generate a patch:

1) edit any .c file in the ioquake3 source and save your changes.
2) right-click the file and convert it from DOS to Unix.
3) open a command prompt (or msys window if you are using that) and navigate to the ROOT FOLDER OF YOUR SOURCE and type the command "svn diff > ioq3patch.patch"
4) this will create a patch of all the changes you made to the source. You can name the file anything you want; ioq3patch.patch, q3asm.patch, etc. to indicate the nature of the patch.
5) open the resulting patch file in your favorite text editor to review it. If you did it correctly from the ROOT FOLDER OF YOUR SOURCE, the path at the top should be something like "Index: code/tools/asm/q3asm.c" and NOT something like "Index: q3asm.c". If the patch looks fine, close your text editor.
6) right-click the resulting patch file and convert it from DOS to Unix. Using "svn diff" on the Windows platform adds some windows-specific linefeeds in the file so we have to get rid of those before submitting the patch file.


Using your .patch files:

1) if you are submitting a patch for a new ability or to fix a new bug, go to https://bugzilla.icculus.org/enter_bug.cgi?product=ioquake3
2) if you are submitting a patch for an existing bug, you probably already know where to go.
3) ...
4) profit!