Introduction

Note: 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 40 minutes.

This page aims to provide a simple step by step guide on how to apply patches to Rockbox and then compile the source code to give the final product. Instructions for doing are available in many forms throughout this website, but the majority of them have been written for those who know the basics of programming. To aid those who are attempting this for the first time and desperately want to customize their Rockbox software, I have decided to create this page. I hope it helps

Getting The Source Code

Compiling The Source Code

Some Simple Commands

Run Cygwin (if you are running from an unprivileged account, right click cygwin.exe, and choose "Run As Administrator").

Now in the cmd window that opens (the one with the black background and white/grey/green writing) type cd foldername, where foldername is the name of the folder where the extracted files went to, and then press Enter.

Pressing the Enter button on the keyboard executes any command.

Typing the command ls shows the contents of the current folder.

Typing the command cd followed by the name of a folder enters that folder.

Typing the command cd .. goes back out of the folder.

Configuring Build

Create a new folder for the compiling by typing mkdir folder, where folder is the name of the folder (I tend to call it build). This folder should be inside the Rockbox source folder.

Enter that folder by typing cd folder, where folder is the name you chose for the folder

In that folder type ../tools/configure which will bring up a list of all possible devices

Select your device by typing in the corresponding number

Next you will be given the option of the build type... just type N for Normal Build

Once that is completed, you should see the text Created Makefile

Finally Compiling

Now type make

Sit back and watch the files being compiled... this process's time will vary depending on your computer and build envirnment (depending on your build envirnment and computer this may take a long time)

Once it has compiled, type make zip

This will make the .rockbox folder, then zip it to create a file called rockbox.zip within the folder you made (in my case build). This stage is not optional, it does more than compress the compiled rockbox folder!

This zip file will be identical to the already compiled Rockbox software for the date of your source code, which you could have downloaded from this website

Well Done! If you have reached this far then you have successfully compiled your own source code. There is obviously no point in doing this if you are not going to modify the code in any way, so the next part looks at how to incorporate patches into the source code.

Adding Patches

Patches are modifications which have not yet been included in the daily builds by the developers. In many cases, the patches are not made by the regular Rockbox developers so there is a chance that they could contain bugs, but it is unlikely that they could actually harm your player. These patches can be downloaded from http://www.rockbox.org/patches.shtml. These patches easily allow you to edit certain source code files, but if these files have been updated by the developers, and the patch has not been modified for the new files, it is unlikely that it will work. Depending on what files a patch modifies, you may only be able to apply 1 patch, because if the first patch modifies a file, the contents of the file would then change and the second patch would have difficulty in updating it. However, if the patch you want to apply, is only going to patch a file that you have never patched before, then it should still work.

The above code is part of a patch file... you can see that this part of the patch is going to modify the file status.c in the apps folder.

A patch or diff file can contain many sections of code like this and modify many files in one go.

Move the .diff or .patch file to the source folder (eg C:\Rockbox\home\guest\rockbox-daily-XXXXXXXX\).

Patching

In the cmd window, go to the directory containing the patch (use the commands mentioned earlier on in this guide)

Type the command patch --binary -p0 < patchfilename where patchfilename is the name of the patch file you downloaded (eg jpeg.diff or stuff.patch)

The Patch program should then patch the file... if this fails then try patch --binary -p1 < patchfilename instead (increase the number each time, up to a maximum of 5)

After you have finished patching the files, simply continue with Configuring Build instructions above

Sometimes (if the patch file isn't correctly generated) having the patch file in the root of the source files does not work, so move the patch file to the location of the files to be patched and run continue the steps below from there. In addition to this, some patches may required patching files in different locations... so repeat the process at all the different locations, until all the files have been patched ( Note: first try all the patching attempts below before resorting to this)

If this fails too, then it is most likely because the patch was not designed for that particular version of the file you are patching, if this is the case then you will usually see messages telling you that a HUNK has failed eg. HUNK #2 failed at line 345 or something similar. Unless you like programming there isn't much you can do about this

If you wish to remove a patch then you just need to add a -R switch eg. patch --binary -p0 -R < patchfilename. As you can see this is identical to the command used for applying the patch but with a -R before the <

For more information on using SVN see the Accessing source code via SVN section at UsingSVN.

Building the Simulator

If you are fed up with creating your WPS's, loading them onto your machine, unplugging machine, running wps file, checking them, plugging machine back in, editing them on your computer, and round and round and on and on..... (You know what I mean), or even if you just want to test the patches without actually loading them onto your machine, then you will find the simulator a godsend!

Compiling

Create a new folder called sim (type mkdir sim) and move into it (type cd sim).

Now you are in the sim directory. Create the make file as usual using configure but select ( S)imulator build instead of ( N)ormal build.

Now type make and wait for it to compile

Then type make fullinstall. It will tell you that it is installing a full setup in your simdisk directory.

Setting up the simulator

Have a look in sim/simdisk. You should see the .rockbox folder there full of all the usual rockbox stuff.

The sim/simdisk folder acts in exactly the same way as the folder in the root of your player, so fill it with all the stuff you would usually have there!

Now, run the simulator by typing ./rockboxui.exe

NOTE: Double clicking the icon from within Windows explorer will fail with an error "This application has failed to start because SDL.dll was not found. Re-Installing the application may fix this problem" - If you really need this "double click" method to work, copy the SDL.DLL file from cygwin\usr\local\bin to the same folder that rockboxui.exe is located in...

The simulator will open. Use the number pad on your keyboard to control the simulator in the same way as the player.