www/docs/patch.t

   1 #define _PAGE_ How To Work With Patches
   2 #include "head.t"
   3 <p>
   4  When we speak of 'patches' in the Rockbox project, we mean a set of changes
   5  to one or more source files.
   6
   7 <h2>Tools Of The Trade</h2>
   8 <p>
   9 Use the tools 'diff' and 'patch'. Preferably the GNU versions. They're readily
  10 available for all imaginable platforms.
  11 <p>
  12 Try one of these:
  13 <ul>
  14 <li> <a href="http://www.fsf.org/software/patch/patch.html">http://www.fsf.org/software/patch/patch.html</a>
  15 <li> <a href="http://www.gnu.org/directory/diffutils.html">http://www.gnu.org/directory/diffutils.html</a>
  16 <li> <a href="http://gnuwin32.sourceforge.net/packages/patch.htm">http://gnuwin32.sourceforge.net/packages/patch.htm</a> - patch for Windows
  17 <li> <a href="http://gnuwin32.sourceforge.net/packages/diffutils.htm">http://gnuwin32.sourceforge.net/packages/diffutils.htm</a> - diff for Windows
  18 </ul>
  19
  20 <h2>Newlines</h2>
  21 <p>
  22  These tools will assume and operate on "unix-style" newlines. That means all
  23 files that you're diffing and patching etc must have LF newlines only, and
  24 <b>not</b> the Windows/DOS standard CRLF newlines,
  25 <p>
  26  Not complying to this simple fact will cause you grief. Mark my words.
  27
  28 <h2>Creating A Patch</h2>
  29 <p>
  30  We generate diffs (often called patches) using 'diff' in a manner similar to
  31 this:
  32 <pre>
  33   diff -u oldfile newfile > patch
  34 </pre>
  35 <p>
  36  People who have checked out code with CVS can do diffs using cvs like this:
  37 <pre>
  38   cvs diff -u file > patch
  39 </pre>
  40 <p>
  41  'diff' can also be used on a whole directory etc to generate one file with
  42 changes done to multiple:
  43 <pre>
  44   diff -u olddir newdir > patch
  45 </pre>
  46 <p>
  47  The -u option means the output is using the 'unified diff' format. Older
  48  diff programs don't have that, and then -c (for 'context diff') is OK.
  49
  50 <h2>Submitting A Patch</h2>
  51
  52 <p>All patches that are meant for inclusion in the sources should follow the
  53 format listed on the <a href="contributing.html">Contributing to Rockbox</a>
  54 page, and be posted to the <a
  55 href="http://sourceforge.net/tracker/?group_id=44306&atid=439120">patch
  56 tracker</a>.  Patches sent to the mailing list are quickly lost in the traffic
  57 of the list itself.
  58
  59 <p>
  60  Please keep in mind that not all submitted patches will be accepted.
  61
  62 <h2>Applying A Patch</h2>
  63 <p>
  64  Applying a 'patch' (output from diff -u) is done with the 'patch' tool:
  65 <pre>
  66   cd to/source/root
  67   patch < patchfile
  68 </pre>
  69 <p>
  70  patch knows that the patchfile is a set of changes on one or more files, and
  71 will do those to your local files. If your files have changed too much for the
  72 patch to work, it will save the sections of the patch that aren't possible to
  73 apply in a file called "filename.rej" (filename being the name of the file for
  74 which the failing section was intended for). Then you must take care of them
  75 manually.
  76
  77 <p>
  78  If there is path information in the patchfile that you want to cut off
  79  from the left, tell patch how many directory levels to cut off to find the
  80  names in your file system:
  81 <pre>
  82   patch -p0 < patchfile
  83   patch -p1 < patchfile
  84   patch -p2 < patchfile
  85 </pre>
  86  ... each example line removes one extra level of dir info from the left.
  87 <p>
  88  You can use the --dry-run option to patch to make sure that the patch applies
  89 clean. It doesn't actually apply the patch, only prints what would happen if
  90 you run it.
  91 <h2>Removing A Patch</h2>
  92 <p>
  93  You can remove a patch again from the sources by doing the reverse action of
  94 a specific patch. You do this with the -R (or --reverse) options, such as:
  95 <pre>
  96   patch -p1 -R < patchfile
  97 </pre>
  98
  99 #include "foot.t"