dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > DocsIndex > SimpleGuideToCompiling

The Simplified Guide To Compiling The Rockbox Source Code

NOTE: This guide is badly out of date and should not be used until it is updated.

NOTE: This guide is for Windows users only! Linux users can read LinuxSimpleGuideToCompiling.


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 smile

What You Will Need

A build environment. See DevelopmentGuide

Getting The Source Code

The source can be downloaded from our SVN server at: svn://

SeeDownloading Code using SVN

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 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 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.


  • Download the patch file after following the links on the file should either end in .diff or .patch
  • This file can be opened by Wordpad - double click on the file and select Wordpad as the program
  • You can see what files this patch is going to edit... for example:

Index: apps/status.c
RCS file: /cvsroot/rockbox/apps/status.c,v
retrieving revision 1.72
diff -u -r1.72 status.c
--- apps/status.c   6 Jul 2005 22:57:54 -0000   1.72
+++ apps/status.c   1 Aug 2005 15:34:12 -0000
@@ -82,6 +82,13 @@
 +enum playmode status_get_ffmode(void)

  • 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\).


  • 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 advanced usage see the WorkingWithPatches page.

Keeping source up to date with SVN

If you downloaded the source using SVN you can use it to keep your source tree up to date:

  • First cd into the rockbox directory where the source was downloaded by typing cd rockbox
  • Now type svn update (or svn up) to update the files (this may take a few minutes depending on your internet connection and speed of your computer)
  • If you have modified any source files, SVN will try to merge any changes so you don't need to apply patches again after updating

Producing a diff of your changes with SVN

This will show you how your files differ from SVN:
  • First cd into the rockbox directory where the source was downloaded by typing cd rockbox
  • To make the diff type svn diff
  • You can also direct the output to a file to create a patch file by typing svn diff > my.patch (where my.patch is your chosen filename)
See WorkingWithPatches for more information about patches

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!


  • 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.

Now enjoy the fact that life has just got oh so much easier...... smile

r54 - 02 Apr 2021 - 20:46:07 - UnknownUser

Parents: DocsIndex
Copyright © by the contributing authors.