---+!! The Simplified Guide To Compiling The Rockbox Source Code %TOC% --- %RED% *NOTE: This guide is badly out of date and should not be used until it is updated.* %ENDCOLOR% --- --- --- *NOTE:* This guide is for Windows users only! Linux users can read LinuxSimpleGuideToCompiling. --- ---++ Introduction %RED% *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.%ENDCOLOR% 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 :-) --- ---++ What You Will Need A build environment. See DevelopmentGuide --- ---++ Getting The Source Code The source can be downloaded from our SVN server at: svn://svn.rockbox.org/rockbox/trunk See[[http://www.rockbox.org/wiki/UsingSVN#How_to_check_out_the_source_code][Downloading 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 _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. ---+++ 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: <verbatim> 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) </verbatim> * 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 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! ---+++ 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. Now enjoy the fact that life has just got oh so much easier...... :)
r53 - 07 Dec 2013 - 04:28:58 -
Copyright © by the contributing authors.