The Simple Guide To Compiling In Linux

---

Introduction

Welcome! This is our beginners' guide for people who want to build their own copy of Rockbox, but have little or no familiarity with Linux environments. We'll assume that you have some basic computer skills in place, of course.

While this guide will attempt to walk you through some checks, prerequisites, and the actual process of compiling Rockbox, this guide cannot substitute a proper Linux tutorial (that said, there's a link to one at the bottom), and instructions for edge cases, or issues that have nothing to do with getting/preparing/using the Rockbox source code, are beyond the scope of this document.

We will use a few notations and shortcuts in this guide, such as italics on variables, like your username in a shell (more on that in a bit), or bold for certain verbatim text. Bold text should be typed or copied exactly as shown, including punctuation marks; failure to do this may cause unexpected results. If something goes weird due to a typo, the best we can tell you to do is to back up and try again.

Preparation

You have a few options nowadays for setting up a Linux environment on your computer. Most of these are a little too involved to include in this guide, so unfortunately you will have to look elsewhere on the Internet if you want help with this part.

• If you run Windows 10, you can enable the Windows Subsystem for Linux(WSL) and install a preconfigured Linux distribution from the Microsoft Store.
• If you run an earlier version of Windows (or you have 10 but don't want to use WSL), you have the option of installing cygwin, or setting up a virtual machine (VM). The common preference is to use a VM.
• If you run macOS, you can try to do this via MacPorts, but a VM is likely the better choice.
• If you want to run Linux as a host operating system, you can either wipe out your existing OS (a very risky choice while you're learning) or dual boot. This editor advises installing Ubuntu in a dual boot setup while you're learning (this guide assumes you're using Debian or Ubuntu).

Once you have Linux up and running, open a Terminal (if you use WSL, just open the distro's "app"). You'll be presented with a simple prompt, reading something like "user@ubuntudesktop" We'll run a few checks to help you familiarize yourself with it, as well as to cover some basic prerequisites.

• First, let's make sure you have enough disk space. In your terminal, type df -h ~ and press Enter. (Assuming that you haven't done any fancy partitioning in your native or VM installation, you'll see the disk space stats for most of your hard drive.) Make sure it says you have at least 1 gigabyte (G) of available space.
• Type pwd and press Enter. You should get /home/username (except with your actual username, of course). If you don't, type cd and hit Enter.

Setting Up

Not much longer until we start on the fun stuff.

First, we need an easy way to download the Rockbox source code, from which you'll make your own build.

• Type sudo apt-get update; sudo apt-get -y install git and press Enter. You should be asked for your password (one that you set up during installation of your Linux environment); type that and press Enter. (You won't see your password, nor any symbols, as you type it.) Wait for all the text to go by.
  • If you get an error message about [package database lock], wait, or restart your environment, and try again.
• Once you see "user@ubuntudesktop" again, type (or copy and paste): git clone git://git.rockbox.org/rockbox . This is the part that actually downloads the Rockbox source code. It can take a while if your Internet is slow; the entire repository is about 150 MB. You can use the advanced tip below if you don't want to download that much.
  • Advanced usage: You can use the --depth N command in git to only check out the last N commits. If you only want to build the tip of the master branch, use --depth 1. If you also want to check out the tip of the other branches in the repository, use --no-single-branch as using --depth defaults to --single-branch.
• Once the source code is downloaded, we need to install a few more things, so run the following: sudo apt-get install automake bison build-essential ccache flex libc6-dev libgmp3-dev libmpfr-dev libsdl1.2-dev libtool-bin texinfo zip gawk wget libmpc-dev gettext . This may also take a while.

Done waiting? Well, there's more waiting ahead of you, but right now you get to do stuff!

• Type cd rockbox/tools (and press Enter; we'll stop reminding you).
• Type chmod +x rockboxdev.sh.
• Type sudo ./rockboxdev.sh.
• Cool, you just started a computer script! The script will ask you which platform(s) ("target arch") you want to compile for. Most people only want to compile for ARM devices, so just type a.
  • If you don't know for sure what devices you want to compile for, you can type m a i x y instead; this will prep your computer to compile for every possible Rockbox target. The catch is that it will take a long time to do this part. (You can stop to look up your target(s) if you need to. Just type the letter(s) that match once you know.)

Compiling

Almost there!

• Type cd ~/rockbox. This should put you in /home/username/rockbox (The tilde character ~ is a shortcut for /home/username .)
• Type mkdir build ("mkdir" makes a folder, or "directory", inside your current location).
• cd build
• pwd (means "print working directory", if you were wondering). You should get /home/username/rockbox/build .
• ../tools/configure (the two periods are important, so don't omit them).

If you did all that right, a table of every device Rockbox supports will appear. Each device has a number beside it; type the number that matches the device you want to make a build for.

• More choices will appear. For this guide, we'll make a normal build, so type n. After a few seconds, the terminal should say, "Created makefile".
• make -j (or just make if you have a really old machine). This is the actual build process! It will take a long time; the faster your CPU, the better. Go get a snack or something.
• Did it stop and there's no obvious sign of an error? Cool. Do make zip and finish your snack.
• If no error showed up, you should be able to see your build by typing ls rockbox.zip. It's all set to be installed on a real device, if you want, but right now it's exactly the same as a dev build from the website. Up to you. Congratulations on making your first build!
  • You can manually install your build by unzipping its contents to the root of your device, overwriting old Rockbox files if they exist).

Gitting it Together

By now, you're probably eager to start adding patches and rolling your own awesome copy of Rockbox! But contain yourself a little longer; adding many patches or esoteric code can make a cluttered situation that can be frustrating to get out of! If you want to make a safety net (or better yet, start one - or many - custom "branches" of Rockbox that get your patches while leaving your main copy intact), use this section. (Note: this section is not strictly required to build Rockbox, but again, it will ease frustrations down the road.)

First, let's see how to check which branch we're on:

• cd ~/rockbox
• git branch

Your source tree should be on "master" right now, but it's about to grow a branch.

• git checkout -b awesomebranch (you can, of course, substitute "awesomebranch" for a name you like)
• git will clone the "master" branch to your new "awesomebranch".

Go nuts! Change any file in your copy of the Rockbox code. Add all the patches you want. But if you want to make the most of this arrangement so far, you'll have to do some metaphorical accounting. When you make or change files, you must tell git about them to reap the best features of git.

• Tell git that you want to officially add a file to the record by typing git add filename (replace "filename" with the actual file's ... name).
  • You can view a list of changed files with git status
• When you feel like updating git's record of your new files and changes to files, do git commit.
• You'll be presented with a text editor screen - probably one called "nano". You'll need to type a message (leaving it blank will abort the commit process); it's best to include a brief yet descriptive sentence or two about the changes you've added.
• With your commit message written, press Ctrl and O to save, then Ctrl and X to exit nano.
• git will make your changes official! ... to your own offline repository. Keep in mind that you can't push changes to the official Rockbox repos without a developer account. But hey! You're starting to do things like a Real Developer.

You can freely switch which existing checkout you want to work on by using git checkout branchname ("branchname" can be "master" if you want to switch back to your original "master copy").

From time to time, you should update your copies of the code so that you have the latest official commits on hand.

• From the master branch, do git pull --rebase
  • If you're not sure which branch you're on, do cd ~/rockbox , then git status.
• A rebase only affects the current working branch; if you want to try to update other branches (like awesomebranch), you must switch to it first (again, by using git checkout branchname).
• With your master branch updated, you can create a new branch (git checkout -b testbranch) to fiddle with, without affecting your existing branch(es) (awesomebranch, for example), which may even remain on older versions of the Rockbox code.
• DO NOT switch branches haphazardly; failure to commit your changes in a branch will result in git erasing them when you switch to another branch.

Troubleshooting

If you see an error message like this:

   "ROCKBOXDEV: libtool is required for this script to work."
   "ROCKBOXDEV: Please install libtool and re-run the script."

Do this to fix it:

• sudo ln -s /usr/bin/libtoolize /usr/bin/libtool

Additional Info / Going Further

When you're ready to take these skills further and apply patches, take a look at https://www.rockbox.org/wiki/bin/view/Main/SimpleGuideToCompiling#Adding_Patches . Just be careful about which ones you add. Many patches break things.

You can consider compiling a simulator, too. Read more here: https://www.rockbox.org/wiki/bin/view/Main/UiSimulator

If you want, you can read the tutorial at http://www.linuxcommand.org/index.php and learn how to use the command line to the fullest.

Happy hacking!