Manually Applying patches (HowTo)
by Stephen Zepp · in Technical Issues · 01/03/2005 (3:26 am) · 5 replies
NOTE: This post came about as a result of questions in a different thread, but it makes more sense to give it it's own thread with an appropriate title. It is based on part on Ben Garney's resource How to make Patches (Cygwin/Unix).
Patch files are broken down into sections, which is loosely defined as:
File header
1 or more "hunks"
(possibly more file headers with their own hunks)
Here is a structured example:
File description header ( 2 lines): the source of the patch is indicated by "---" and the target indicated by "+++".
(Note: All that really matters to you is the file name itself, and where it is in your dir structure).
Example:
a "locater" line, indicated by "@@", which is uses to find out roughly where the code to be changed by this hunk is:
For general knowledge, what you have is two points of information, one for the original file, and one for the target file. The first number in each point (the 54) indicates a location line number, and the second number (20 for the "-" datapoint, 24 for the "+" datapoint) is the +/- offset that the code can be found in. In other words, to find the code for this hunk:
in the source file ("-"): go to line 54, and look within +/- 20 lines (could be 10, or half the number, I honestly don't remember) to find it.
in the target file ("+"): go to line 54, and look within +/- 24 lines.
"Reference" code: These are actual lines of code from the file being changed, but do not have a "+" or "-" in front of them. They are used by the automated process to lock down the exact place to change the code, and should be used the same way in a manual patch application. Most of the time, you can use "search" on the entire line to find the right place to modify code, just sanity check it before blindly applying changes.
- : delete whatever line in your file is shown after the -
+ : add whatever line is shown in the patch file to your file.
(cont)
Patch files are broken down into sections, which is loosely defined as:
File header
1 or more "hunks"
(possibly more file headers with their own hunks)
Here is a structured example:
File description header ( 2 lines): the source of the patch is indicated by "---" and the target indicated by "+++".
(Note: All that really matters to you is the file name itself, and where it is in your dir structure).
Example:
--- RTSKit/engine/terrain/terrData.cc 2004-11-26 10:45:59.120822000 -0500 +++ rts-engine/engine/terrain/terrData.cc 2004-11-26 11:16:08.821706632 -0500
a "locater" line, indicated by "@@", which is uses to find out roughly where the code to be changed by this hunk is:
@@ -54,20 +54,24 @@NOTE: This locator is used by the automated patch application to find the general location of the code that is to be changed. While you can use it to get started, it can be very difficult to use in a long patch that is applied manually, since they are running line numbers that can change as each patch is applied. Most people that apply patches manually do not use this, or only use it very loosely.
For general knowledge, what you have is two points of information, one for the original file, and one for the target file. The first number in each point (the 54) indicates a location line number, and the second number (20 for the "-" datapoint, 24 for the "+" datapoint) is the +/- offset that the code can be found in. In other words, to find the code for this hunk:
in the source file ("-"): go to line 54, and look within +/- 20 lines (could be 10, or half the number, I honestly don't remember) to find it.
in the target file ("+"): go to line 54, and look within +/- 24 lines.
"Reference" code: These are actual lines of code from the file being changed, but do not have a "+" or "-" in front of them. They are used by the automated process to lock down the exact place to change the code, and should be used the same way in a manual patch application. Most of the time, you can use "search" on the entire line to find the right place to modify code, just sanity check it before blindly applying changes.
//--------------------------------------
void TerrainBlock::setFile(Resource<TerrainFile> terr)
{"Change" lines: These are the actual changes to your code. They operate on an "entire line" basis, and have two types:- : delete whatever line in your file is shown after the -
+ : add whatever line is shown in the patch file to your file.
- mChunkMap = mFile->mChunkMap; - materialMap = mFile->mMaterialMap; - heightMap = mFile->mHeightMap; - flagMap = mFile->mFlagMap; + mChunkMap = mFile->mChunkMap; + materialMap = mFile->mMaterialMap; + heightMap = mFile->mHeightMap; + flagMap = mFile->mFlagMap;NOTE: In this particular example, if you analyze what's really changed, all you will see is that we add some whitespace between the variable name and the = sign. Due to the nature of automated patching, that requires you to delete the entire line, and then copy in the new line. A bit overkill in this particular case, but it's for automated processing of the patch.
(cont)
#2
01/03/2005 (3:57 am)
Thanks!
#3
01/04/2005 (8:15 am)
Thank you for the explanation! I also read the link you posted on doing it automatically via diff and patch. I downloaded patch but it didn't come as an executable. I tried to compile it under VC++ 7.1 but being very new at programming, it didn't work. So, is there a way to get diff and patch that is compiled and ready to run?
#4
What that means is that you either need an editor that can automatically process patch files, or an environment (minsys, cygwin for windows) that has patch as a command. you don't directly "compile" a patch file, but you can of course compile the patch program itself if you have access to the source code. In general though, this is not the way to go for that--you want to install an environment or IDE/standalone editor that can process patch files.
Edit: I missed your comment about how you downloaded "patch" but it didn't come with an executable. I would probably suggest searching the web a bit more, it's doubtless out there. It may also be something that either VC itself either can do, or has a plugin somewhere for, but I don't use it so I do not know.
01/04/2005 (8:20 am)
Patch files themselves are not "code", but simply an input file to the patch application/executable in your environment. What that means is that you either need an editor that can automatically process patch files, or an environment (minsys, cygwin for windows) that has patch as a command. you don't directly "compile" a patch file, but you can of course compile the patch program itself if you have access to the source code. In general though, this is not the way to go for that--you want to install an environment or IDE/standalone editor that can process patch files.
Edit: I missed your comment about how you downloaded "patch" but it didn't come with an executable. I would probably suggest searching the web a bit more, it's doubtless out there. It may also be something that either VC itself either can do, or has a plugin somewhere for, but I don't use it so I do not know.
#5
01/04/2005 (8:39 am)
Thanks - I'll keep on searching!
Torque 3D Owner Stephen Zepp
Within a hunk, you may have many lines that get added/subtracted, interspersed with "reference lines". Manually applying a patch correctly requires attention to detail, so do it slowly. You can not simply cut/past an entire hunk directly into your file, remove the +/- signs at the front, and expect it to work.
Experienced developers (both in general, and also experienced with the code that is being patched) may be able to "optimize" their work by analyzing the changes being made as they go and simply making that change, but unless you are pretty experienced, I suggest following the process of "delete line if a -, add line if a +" blindly.
Disclaimer: Purists will note that the above description of the use and functionality of the sections of a patch are not "strict", but written to provide basic understanding of what is happening/is there.