]>
Commit | Line | Data |
---|---|---|
754c7976 JJ |
1 | |
2 | Applying Patches To The Linux Kernel | |
3 | ------------------------------------ | |
4 | ||
90f2447d JJ |
5 | Original by: Jesper Juhl, August 2005 |
6 | Last update: 2005-12-02 | |
754c7976 JJ |
7 | |
8 | ||
9 | ||
10 | A frequently asked question on the Linux Kernel Mailing List is how to apply | |
11 | a patch to the kernel or, more specifically, what base kernel a patch for | |
12 | one of the many trees/branches should be applied to. Hopefully this document | |
13 | will explain this to you. | |
14 | ||
15 | In addition to explaining how to apply and revert patches, a brief | |
16 | description of the different kernel trees (and examples of how to apply | |
17 | their specific patches) is also provided. | |
18 | ||
19 | ||
20 | What is a patch? | |
21 | --- | |
22 | A patch is a small text document containing a delta of changes between two | |
23 | different versions of a source tree. Patches are created with the `diff' | |
24 | program. | |
25 | To correctly apply a patch you need to know what base it was generated from | |
26 | and what new version the patch will change the source tree into. These | |
27 | should both be present in the patch file metadata or be possible to deduce | |
28 | from the filename. | |
29 | ||
30 | ||
31 | How do I apply or revert a patch? | |
32 | --- | |
33 | You apply a patch with the `patch' program. The patch program reads a diff | |
34 | (or patch) file and makes the changes to the source tree described in it. | |
35 | ||
36 | Patches for the Linux kernel are generated relative to the parent directory | |
37 | holding the kernel source dir. | |
38 | ||
39 | This means that paths to files inside the patch file contain the name of the | |
40 | kernel source directories it was generated against (or some other directory | |
41 | names like "a/" and "b/"). | |
42 | Since this is unlikely to match the name of the kernel source dir on your | |
43 | local machine (but is often useful info to see what version an otherwise | |
44 | unlabeled patch was generated against) you should change into your kernel | |
45 | source directory and then strip the first element of the path from filenames | |
46 | in the patch file when applying it (the -p1 argument to `patch' does this). | |
47 | ||
48 | To revert a previously applied patch, use the -R argument to patch. | |
49 | So, if you applied a patch like this: | |
50 | patch -p1 < ../patch-x.y.z | |
51 | ||
52 | You can revert (undo) it like this: | |
53 | patch -R -p1 < ../patch-x.y.z | |
54 | ||
55 | ||
56 | How do I feed a patch/diff file to `patch'? | |
57 | --- | |
58 | This (as usual with Linux and other UNIX like operating systems) can be | |
59 | done in several different ways. | |
60 | In all the examples below I feed the file (in uncompressed form) to patch | |
61 | via stdin using the following syntax: | |
62 | patch -p1 < path/to/patch-x.y.z | |
63 | ||
64 | If you just want to be able to follow the examples below and don't want to | |
65 | know of more than one way to use patch, then you can stop reading this | |
66 | section here. | |
67 | ||
68 | Patch can also get the name of the file to use via the -i argument, like | |
69 | this: | |
70 | patch -p1 -i path/to/patch-x.y.z | |
71 | ||
72 | If your patch file is compressed with gzip or bzip2 and you don't want to | |
73 | uncompress it before applying it, then you can feed it to patch like this | |
74 | instead: | |
75 | zcat path/to/patch-x.y.z.gz | patch -p1 | |
76 | bzcat path/to/patch-x.y.z.bz2 | patch -p1 | |
77 | ||
78 | If you wish to uncompress the patch file by hand first before applying it | |
79 | (what I assume you've done in the examples below), then you simply run | |
80 | gunzip or bunzip2 on the file - like this: | |
81 | gunzip patch-x.y.z.gz | |
82 | bunzip2 patch-x.y.z.bz2 | |
83 | ||
84 | Which will leave you with a plain text patch-x.y.z file that you can feed to | |
85 | patch via stdin or the -i argument, as you prefer. | |
86 | ||
87 | A few other nice arguments for patch are -s which causes patch to be silent | |
88 | except for errors which is nice to prevent errors from scrolling out of the | |
89 | screen too fast, and --dry-run which causes patch to just print a listing of | |
90 | what would happen, but doesn't actually make any changes. Finally --verbose | |
91 | tells patch to print more information about the work being done. | |
92 | ||
93 | ||
94 | Common errors when patching | |
95 | --- | |
96 | When patch applies a patch file it attempts to verify the sanity of the | |
97 | file in different ways. | |
98 | Checking that the file looks like a valid patch file, checking the code | |
99 | around the bits being modified matches the context provided in the patch are | |
100 | just two of the basic sanity checks patch does. | |
101 | ||
102 | If patch encounters something that doesn't look quite right it has two | |
103 | options. It can either refuse to apply the changes and abort or it can try | |
104 | to find a way to make the patch apply with a few minor changes. | |
105 | ||
106 | One example of something that's not 'quite right' that patch will attempt to | |
107 | fix up is if all the context matches, the lines being changed match, but the | |
108 | line numbers are different. This can happen, for example, if the patch makes | |
109 | a change in the middle of the file but for some reasons a few lines have | |
110 | been added or removed near the beginning of the file. In that case | |
111 | everything looks good it has just moved up or down a bit, and patch will | |
112 | usually adjust the line numbers and apply the patch. | |
113 | ||
114 | Whenever patch applies a patch that it had to modify a bit to make it fit | |
115 | it'll tell you about it by saying the patch applied with 'fuzz'. | |
116 | You should be wary of such changes since even though patch probably got it | |
117 | right it doesn't /always/ get it right, and the result will sometimes be | |
118 | wrong. | |
119 | ||
120 | When patch encounters a change that it can't fix up with fuzz it rejects it | |
121 | outright and leaves a file with a .rej extension (a reject file). You can | |
90f2447d | 122 | read this file to see exactly what change couldn't be applied, so you can |
754c7976 JJ |
123 | go fix it up by hand if you wish. |
124 | ||
125 | If you don't have any third party patches applied to your kernel source, but | |
126 | only patches from kernel.org and you apply the patches in the correct order, | |
127 | and have made no modifications yourself to the source files, then you should | |
128 | never see a fuzz or reject message from patch. If you do see such messages | |
129 | anyway, then there's a high risk that either your local source tree or the | |
130 | patch file is corrupted in some way. In that case you should probably try | |
90f2447d | 131 | re-downloading the patch and if things are still not OK then you'd be advised |
754c7976 JJ |
132 | to start with a fresh tree downloaded in full from kernel.org. |
133 | ||
134 | Let's look a bit more at some of the messages patch can produce. | |
135 | ||
136 | If patch stops and presents a "File to patch:" prompt, then patch could not | |
137 | find a file to be patched. Most likely you forgot to specify -p1 or you are | |
138 | in the wrong directory. Less often, you'll find patches that need to be | |
139 | applied with -p0 instead of -p1 (reading the patch file should reveal if | |
140 | this is the case - if so, then this is an error by the person who created | |
141 | the patch but is not fatal). | |
142 | ||
143 | If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a | |
144 | message similar to that, then it means that patch had to adjust the location | |
145 | of the change (in this example it needed to move 7 lines from where it | |
146 | expected to make the change to make it fit). | |
147 | The resulting file may or may not be OK, depending on the reason the file | |
148 | was different than expected. | |
149 | This often happens if you try to apply a patch that was generated against a | |
150 | different kernel version than the one you are trying to patch. | |
151 | ||
152 | If you get a message like "Hunk #3 FAILED at 2387.", then it means that the | |
153 | patch could not be applied correctly and the patch program was unable to | |
154 | fuzz its way through. This will generate a .rej file with the change that | |
155 | caused the patch to fail and also a .orig file showing you the original | |
156 | content that couldn't be changed. | |
157 | ||
158 | If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" | |
159 | then patch detected that the change contained in the patch seems to have | |
160 | already been made. | |
161 | If you actually did apply this patch previously and you just re-applied it | |
162 | in error, then just say [n]o and abort this patch. If you applied this patch | |
163 | previously and actually intended to revert it, but forgot to specify -R, | |
164 | then you can say [y]es here to make patch revert it for you. | |
165 | This can also happen if the creator of the patch reversed the source and | |
166 | destination directories when creating the patch, and in that case reverting | |
167 | the patch will in fact apply it. | |
168 | ||
169 | A message similar to "patch: **** unexpected end of file in patch" or "patch | |
170 | unexpectedly ends in middle of line" means that patch could make no sense of | |
171 | the file you fed to it. Either your download is broken or you tried to feed | |
172 | patch a compressed patch file without uncompressing it first. | |
173 | ||
174 | As I already mentioned above, these errors should never happen if you apply | |
175 | a patch from kernel.org to the correct version of an unmodified source tree. | |
176 | So if you get these errors with kernel.org patches then you should probably | |
177 | assume that either your patch file or your tree is broken and I'd advice you | |
178 | to start over with a fresh download of a full kernel tree and the patch you | |
179 | wish to apply. | |
180 | ||
181 | ||
182 | Are there any alternatives to `patch'? | |
183 | --- | |
90f2447d JJ |
184 | Yes there are alternatives. |
185 | ||
186 | You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to | |
187 | generate a patch representing the differences between two patches and then | |
188 | apply the result. | |
754c7976 JJ |
189 | This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single |
190 | step. The -z flag to interdiff will even let you feed it patches in gzip or | |
191 | bzip2 compressed form directly without the use of zcat or bzcat or manual | |
192 | decompression. | |
193 | ||
194 | Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: | |
195 | interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 | |
196 | ||
197 | Although interdiff may save you a step or two you are generally advised to | |
198 | do the additional steps since interdiff can get things wrong in some cases. | |
199 | ||
200 | Another alternative is `ketchup', which is a python script for automatic | |
201 | downloading and applying of patches (http://www.selenic.com/ketchup/). | |
202 | ||
90f2447d | 203 | Other nice tools are diffstat which shows a summary of changes made by a |
754c7976 JJ |
204 | patch, lsdiff which displays a short listing of affected files in a patch |
205 | file, along with (optionally) the line numbers of the start of each patch | |
206 | and grepdiff which displays a list of the files modified by a patch where | |
207 | the patch contains a given regular expression. | |
208 | ||
209 | ||
210 | Where can I download the patches? | |
211 | --- | |
212 | The patches are available at http://kernel.org/ | |
213 | Most recent patches are linked from the front page, but they also have | |
214 | specific homes. | |
215 | ||
216 | The 2.6.x.y (-stable) and 2.6.x patches live at | |
217 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ | |
218 | ||
219 | The -rc patches live at | |
220 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ | |
221 | ||
222 | The -git patches live at | |
223 | ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ | |
224 | ||
225 | The -mm kernels live at | |
226 | ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ | |
227 | ||
228 | In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a | |
229 | country code. This way you'll be downloading from a mirror site that's most | |
230 | likely geographically closer to you, resulting in faster downloads for you, | |
231 | less bandwidth used globally and less load on the main kernel.org servers - | |
232 | these are good things, do use mirrors when possible. | |
233 | ||
234 | ||
235 | The 2.6.x kernels | |
236 | --- | |
237 | These are the base stable releases released by Linus. The highest numbered | |
238 | release is the most recent. | |
239 | ||
240 | If regressions or other serious flaws are found then a -stable fix patch | |
241 | will be released (see below) on top of this base. Once a new 2.6.x base | |
242 | kernel is released, a patch is made available that is a delta between the | |
243 | previous 2.6.x kernel and the new one. | |
244 | ||
245 | To apply a patch moving from 2.6.11 to 2.6.12 you'd do the following (note | |
246 | that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the | |
247 | base 2.6.x kernel - if you need to move from 2.6.x.y to 2.6.x+1 you need to | |
248 | first revert the 2.6.x.y patch). | |
249 | ||
250 | Here are some examples: | |
251 | ||
252 | # moving from 2.6.11 to 2.6.12 | |
253 | $ cd ~/linux-2.6.11 # change to kernel source dir | |
254 | $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch | |
255 | $ cd .. | |
256 | $ mv linux-2.6.11 linux-2.6.12 # rename source dir | |
257 | ||
258 | # moving from 2.6.11.1 to 2.6.12 | |
259 | $ cd ~/linux-2.6.11.1 # change to kernel source dir | |
260 | $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch | |
261 | # source dir is now 2.6.11 | |
262 | $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch | |
263 | $ cd .. | |
90f2447d | 264 | $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir |
754c7976 JJ |
265 | |
266 | ||
267 | The 2.6.x.y kernels | |
268 | --- | |
269 | Kernels with 4 digit versions are -stable kernels. They contain small(ish) | |
270 | critical fixes for security problems or significant regressions discovered | |
271 | in a given 2.6.x kernel. | |
272 | ||
273 | This is the recommended branch for users who want the most recent stable | |
274 | kernel and are not interested in helping test development/experimental | |
275 | versions. | |
276 | ||
277 | If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is | |
278 | the current stable kernel. | |
279 | ||
280 | These patches are not incremental, meaning that for example the 2.6.12.3 | |
281 | patch does not apply on top of the 2.6.12.2 kernel source, but rather on top | |
282 | of the base 2.6.12 kernel source. | |
283 | So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel | |
284 | source you have to first back out the 2.6.12.2 patch (so you are left with a | |
285 | base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. | |
286 | ||
287 | Here's a small example: | |
288 | ||
289 | $ cd ~/linux-2.6.12.2 # change into the kernel source dir | |
290 | $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch | |
291 | $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch | |
292 | $ cd .. | |
293 | $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir | |
294 | ||
295 | ||
296 | The -rc kernels | |
297 | --- | |
298 | These are release-candidate kernels. These are development kernels released | |
299 | by Linus whenever he deems the current git (the kernel's source management | |
300 | tool) tree to be in a reasonably sane state adequate for testing. | |
301 | ||
302 | These kernels are not stable and you should expect occasional breakage if | |
303 | you intend to run them. This is however the most stable of the main | |
304 | development branches and is also what will eventually turn into the next | |
305 | stable kernel, so it is important that it be tested by as many people as | |
306 | possible. | |
307 | ||
308 | This is a good branch to run for people who want to help out testing | |
309 | development kernels but do not want to run some of the really experimental | |
310 | stuff (such people should see the sections about -git and -mm kernels below). | |
311 | ||
312 | The -rc patches are not incremental, they apply to a base 2.6.x kernel, just | |
313 | like the 2.6.x.y patches described above. The kernel version before the -rcN | |
314 | suffix denotes the version of the kernel that this -rc kernel will eventually | |
315 | turn into. | |
316 | So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 | |
317 | kernel and the patch should be applied on top of the 2.6.12 kernel source. | |
318 | ||
319 | Here are 3 examples of how to apply these patches: | |
320 | ||
321 | # first an example of moving from 2.6.12 to 2.6.13-rc3 | |
322 | $ cd ~/linux-2.6.12 # change into the 2.6.12 source dir | |
323 | $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch | |
324 | $ cd .. | |
325 | $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir | |
326 | ||
327 | # now let's move from 2.6.13-rc3 to 2.6.13-rc5 | |
328 | $ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir | |
329 | $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch | |
330 | $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch | |
331 | $ cd .. | |
332 | $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir | |
333 | ||
334 | # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 | |
335 | $ cd ~/linux-2.6.12.3 # change to the kernel source dir | |
336 | $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch | |
337 | $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch | |
338 | $ cd .. | |
339 | $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir | |
340 | ||
341 | ||
342 | The -git kernels | |
343 | --- | |
344 | These are daily snapshots of Linus' kernel tree (managed in a git | |
345 | repository, hence the name). | |
346 | ||
347 | These patches are usually released daily and represent the current state of | |
348 | Linus' tree. They are more experimental than -rc kernels since they are | |
349 | generated automatically without even a cursory glance to see if they are | |
350 | sane. | |
351 | ||
352 | -git patches are not incremental and apply either to a base 2.6.x kernel or | |
353 | a base 2.6.x-rc kernel - you can see which from their name. | |
354 | A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch | |
355 | named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. | |
356 | ||
357 | Here are some examples of how to apply these patches: | |
358 | ||
359 | # moving from 2.6.12 to 2.6.12-git1 | |
360 | $ cd ~/linux-2.6.12 # change to the kernel source dir | |
361 | $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch | |
362 | $ cd .. | |
363 | $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir | |
364 | ||
365 | # moving from 2.6.12-git1 to 2.6.13-rc2-git3 | |
366 | $ cd ~/linux-2.6.12-git1 # change to the kernel source dir | |
367 | $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch | |
368 | # we now have a 2.6.12 kernel | |
369 | $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch | |
370 | # the kernel is now 2.6.13-rc2 | |
371 | $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch | |
372 | # the kernel is now 2.6.13-rc2-git3 | |
373 | $ cd .. | |
374 | $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir | |
375 | ||
376 | ||
377 | The -mm kernels | |
378 | --- | |
379 | These are experimental kernels released by Andrew Morton. | |
380 | ||
381 | The -mm tree serves as a sort of proving ground for new features and other | |
382 | experimental patches. | |
383 | Once a patch has proved its worth in -mm for a while Andrew pushes it on to | |
384 | Linus for inclusion in mainline. | |
385 | ||
386 | Although it's encouraged that patches flow to Linus via the -mm tree, this | |
387 | is not always enforced. | |
388 | Subsystem maintainers (or individuals) sometimes push their patches directly | |
389 | to Linus, even though (or after) they have been merged and tested in -mm (or | |
390 | sometimes even without prior testing in -mm). | |
391 | ||
392 | You should generally strive to get your patches into mainline via -mm to | |
393 | ensure maximum testing. | |
394 | ||
395 | This branch is in constant flux and contains many experimental features, a | |
396 | lot of debugging patches not appropriate for mainline etc and is the most | |
397 | experimental of the branches described in this document. | |
398 | ||
399 | These kernels are not appropriate for use on systems that are supposed to be | |
400 | stable and they are more risky to run than any of the other branches (make | |
401 | sure you have up-to-date backups - that goes for any experimental kernel but | |
402 | even more so for -mm kernels). | |
403 | ||
404 | These kernels in addition to all the other experimental patches they contain | |
405 | usually also contain any changes in the mainline -git kernels available at | |
406 | the time of release. | |
407 | ||
408 | Testing of -mm kernels is greatly appreciated since the whole point of the | |
409 | tree is to weed out regressions, crashes, data corruption bugs, build | |
410 | breakage (and any other bug in general) before changes are merged into the | |
411 | more stable mainline Linus tree. | |
412 | But testers of -mm should be aware that breakage in this tree is more common | |
413 | than in any other tree. | |
414 | ||
415 | The -mm kernels are not released on a fixed schedule, but usually a few -mm | |
416 | kernels are released in between each -rc kernel (1 to 3 is common). | |
417 | The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels | |
418 | have been released yet) or to a Linus -rc kernel. | |
419 | ||
420 | Here are some examples of applying the -mm patches: | |
421 | ||
422 | # moving from 2.6.12 to 2.6.12-mm1 | |
423 | $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir | |
424 | $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch | |
425 | $ cd .. | |
426 | $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately | |
427 | ||
428 | # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 | |
429 | $ cd ~/linux-2.6.12-mm1 | |
430 | $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch | |
431 | # we now have a 2.6.12 source | |
432 | $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch | |
433 | # we now have a 2.6.13-rc3 source | |
434 | $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch | |
435 | $ cd .. | |
436 | $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir | |
437 | ||
438 | ||
90f2447d JJ |
439 | This concludes this list of explanations of the various kernel trees. |
440 | I hope you are now clear on how to apply the various patches and help testing | |
441 | the kernel. | |
442 | ||
443 | Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, | |
444 | Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have | |
445 | forgotten for their reviews and contributions to this document. | |
754c7976 | 446 |