How To Work With Patches

---

Introduction

When we speak of "patches" in the Rockbox project, we mean a set of changes to one or more source files. Before you begin, be aware that this process can require a decent amount of time and technical knowledge and should not be attempted by a casual user, but rather by those intending to invest time in development. But, most people (especially those with some familiarity with Unix shells) should be able to learn to apply the patches in no more than 30 minutes.

---

Setup the Rockbox Development Environment

DevelopmentGuide

---

Patch Tracker

The Flyspray Patch Tracker - where all patches not yet committed to the source code live.

---

Tools Of The Trade

Use the tools 'diff' and 'patch'. Preferably the GNU versions. They're readily available for all imaginable platforms. You can also make diffs directly from Subversion, as described in UsingSVN.

Try one of these:

• http://www.gnu.org/software/patch/patch.html
• http://www.gnu.org/directory/diffutils.html
• http://gnuwin32.sourceforge.net/packages/patch.htm - patch for Windows
• http://gnuwin32.sourceforge.net/packages/diffutils.htm - diff for Windows

---

Applying A Patch

Applying a 'patch' (output from diff -u) is done with the 'patch' tool inside the Bash Shell (i.e.Cygwin). It is best to put the patch files in the same directory as the source code and will make it easier for you when you have to apply them.

  cd to/source/root
  patch < patchfile

patch knows that the patchfile is a set of changes on one or more files, and will do those to your local files. If your files have changed too much for the patch to work, it will save the sections of the patch that aren't possible to apply in a file called "filename.rej" (filename being the name of the file for which the failing section was intended for). Then you must take care of them manually.

If there is path information in the patchfile that you want to cut off from the left, tell patch how many directory levels to cut off to find the names in your file system:

  patch -p0 < patchfile
  patch -p1 < patchfile
  patch -p2 < patchfile

... each example line removes one extra level of dir info from the left.

You can use the --dry-run option to patch to make sure that the patch applies clean. It doesn't actually apply the patch, only prints what would happen if you run it.

---

Removing A Patch

You can remove a patch again from the sources by doing the reverse action of a specific patch. You do this with the -R (or --reverse) options, such as:

  patch -p1 -R < patchfile

---

Newlines

These tools will assume and operate on "unix-style" newlines. That means all files that you're diffing and patching must have LF newlines only, and not the Windows/DOS standard CRLF newlines.

Do you have a newline problem? You might want to try Dos2unix or unix2dos.

  dos2unix -d filename

To change Dos CRLF to Unix LF newline style.

  dos2unix -u filename

To change Unix LF to Dos CRLF newline style.

both commands will change and save the specific file. You can put an asterisk (*) instead of filename to go through a library, or

  find -exec dos2unix -U {} \;

To run recursively on every subdirectory and file.

---

Problems with Windows Patch

For some users, the Windows patch program above malfunctions. If patch doesn't output anything, set up a build environment as described on this page.

---

Creating A Patch

We generate diffs (often called patches) using 'diff' in a manner similar to this:

  diff -u oldfile newfile > patch

People who have checked out code with SVN can do diffs using svn like this:

  svn diff file > patch

'diff' can also be used on a whole directory etc to generate one file with changes done to multiple:

  diff -u -r olddir newdir > patch

The -u option means the output is using the 'unified diff' format. Older diff programs don't have that, and then -c (for 'context diff') is OK.

The -r option recursively runs diff command on every subdirectory and file.

Include New Files

Newly created files can be included with the help of 'svn add'.

First add the files like this:

  svn add file

after adding the files they can be included in the patch:

  svn diff [files] > patch

---

Submitting A Patch

All patches that are meant for inclusion in the sources should follow the format listed on the Contributing to Rockbox page, and be posted to the patch tracker. Patches sent to the mailing list or posted to the forums are quickly lost in the traffic of the list itself.

Please keep in mind that not all submitted patches will be accepted. The better you make the patch, the better is the chance that it will get applied.

Notes on better patches:

• Restrict your patch to one functionality or fix, don't create big patches that change multiple things at the same time.
• Non-functional formatting changes should not be mixed with functional changes. This makes the patch harder to read and harder to apply.
• Patches should be based from the root dir of Rockbox, or the dir above it. eg.

  "svn diff thread.c"

  becomes

  "svn diff firmware/thread.c"

  .
• When another patch is applied to SVN that conflicts with your patch, perform the merge, then recreate and resubmit your patch. It is up to you to maintain the patch in an applicable state until a developer applies it to SVN.
• Follow the Rockbox source code style in regard to names, comments and indenting.
• Make sure the patch doesn't break any build.
• Post your patch in the patch tracker.

It is okay to gently remind the developer crowd after a while in case you feel your good patch seems to have been forgotten or wrongly put aside.

---