The Simplified Guide To Compiling The Rockbox Source Code

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

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.

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 :-)

What You Will Need

A build environment. Follow the instructions at any of the following pages: CygwinDevelopment, VMwareDevelopmentPlatform, or CoLinuxDevelopmentPlatform.

Getting The Source Code

There are two ways to get the source. From SVN and manually downloading from the Daily Build page.

From SVN

Check out source -

• Run the following command
• svn co svn://svn.rockbox.org/rockbox/trunk rockbox
• A rockbox folder will be created in your current directory and all the source files will be placed there. Note: Depending on your connection speed, this process could take a LONG time - wait for the output from the svn command to stop scrolling before doing anything else

For more information see the Accessing source code via SVN page at UsingSVN.

From Daily Build page

Usually there are two different versions of the source code available... the Daily Build and the Bleeding Edge Build. Both of these builds are available at http://www.rockbox.org/daily.shtml The Bleeding Edge build contains the latest changes made by the Developers whereas the Daily Build is produced automatically at the same time every day. If you are new to Rockbox I would recommend downloading the Daily Build, because the Bleeding Edge build could contain bugs that the Developers are not aware of yet. In addition to this, older builds can also be downloaded, so all in all, its pretty much up to you what you decide to download.

• Once the source code file has been downloaded, you should have a file called rockbox-XXXXXXXX.7z (where XXXXXXXX is the date) or _rockbox.7z
• Make your way back to C:\Rockbox\, open the folder called Home and the folder called guest within that. Move your newly downloaded file into this folder (C:\Rockbox\home\guest)
• Run Cygwin
• Use the cd command to change directories into whichever one the source code has been placed.
• Once that is open, type dir and it should show the name of the file you have just copied into the folder (if this doesn't work, don't worry too much... you can just copy the filename from elsewhere)
• When typing in the filename, just start of with the first few letters and then press the Tab key, which will autocomplete the name for you
• Now, type daily filename.7z, where filename is the name of the file... obviously
• You should notice the command working away, before it comes back to the prompt
• Note: Some people have had some problems with the dir and daily commands, so if that is the case, you can manually extract the file by using 7zip, WinRAR, or any other extractor that supports the 7zip format.
• If you go back into the folder where you placed the file in the first place, you should see a new folder containing all the extracted files

Compiling The Source Code

Some Simple Commands

• Now back in the cmd window (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 dir 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 should not take more than 5 minutes (may take a little more if you have a slow computer)
• 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. The patches are not made by the 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.

Preparation

• Download the patch file after following the links on http://www.rockbox.org/patches.shtml... 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 @@
     status_draw(false);
 }
 +enum playmode status_get_ffmode(void)

• The above code is part of a patch file... you can see that this part of the code 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)
• 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 <

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!

If you haven't already downloaded the source code using SVN then do that now by typing the following

svn co svn://svn.rockbox.org/rockbox/trunk rockbox in home/guest

Note: You need to have libsdl (dev) installed (debain package libsdl1.2-dev).

Compiling

• Create a new folder called sim (type mkdir sim) and 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 archos directory.

Setting up the simulator

• Have a look in sim/archos. You should see the .rockbox folder there full of all the usual rockbox stuff.
• The sim/archos 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...... :)

Feedback & Thanks

If you have any comments or ideas on how to improve this guide, please feel free to email me at rockbox [at] hirenshah [dot] co [dot] uk

Thanks also goes to the following people for helping me correct the mistakes and improve this page (I apologize if I missed your name out): LinusN, rasher, ENWOD, ally, Mikerman and Mmmm

Thanks to Tucoz, Bigbambi, Daniel Stenberg and especially Lear for helping me with the simulator. -- Mmmm