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

Search | Go
Wiki > Main > VMwareDevelopmentPlatform

VMware Development Platform for Rockbox

This page is historical and should not be used for rockbox development


The VMware development platform for Rockbox is a quick way to get involved with Rockbox. VMware is virtualization software that you can run in Windows that enables you to run other operating systems (such as Linux) at the same time in a virtual machine.

VMware Player is relatively new software that allows this for free. VMware also recently released the VMware Server, which is also free. VMware Player is a limited version of the VMware system. It allows you to run VMware images, but not to create them. For the purposes of compiling Rockbox, this is all that's necessary. For Mac OS X users, VMware Fusion 3 works very well to run the Rockbox development platform.

We've created a image that contains a small Linux installation along with all needed tools to compile Rockbox for the different targets. It even comes with the anonymous CVSROOT configured.

Using VMware is not only simpler, compiling is a lot faster than using cygwin. The only downside is the boot-time, cygwin is up and running immediately, while you have to "boot" the VMware image. One workaround for this is to "pause" the virtual machine instead of "power off".

Quick start guide

Updated image (debian 5.0.4) made from a clean download of the above one at the time of the EABI switch: debian-5.0.4 Rockbox VMWare Image page

Note: Not everything works correctly (USB for example) but it can be used to make builds. Sound works. Prepare for a large download (~540MB). More details are on the page at the link.


Checking out and compiling is as easy as in this example for a iriver H120/140:
git clone git://
cd rockbox
mkdir build_h120
cd build_h120
The directory you create in the mkdir command doesn't really matter, but it's better to be descriptive.

To export the file, type:
make zip

More development information:

If you log in as user you will most probably encounter a "file permission" error when you attempt to configure. A quick dirty work around:
su (it will ask for root password)
rockbox (root password)
chmod 777 * -R (This will give full permissions for all files and folders, under the current directory)
exit (exit root mode)

ALERT! WARNING: Input these commands (chmod) in your source tree, not in the '/'.

Good luck!

Username and passwords

Console and SSH login:

  • username: root
  • password: rockbox

  • username: user
  • password: rockbox
The username (account) root is for the system administrator account on the system. This is the most powerful account the system has and if you are not careful, actions performed here can ruin the system (for example, if you issue a file delete command and delete all the files in a system directory)

The username (account) user is a standard account, with limited permissions related to system files. You will not damage the system accidently with this account.

Normally, you will want to use the user account, leaving the root account for system affecting tasks, like setting the system timezone (see the Time zone configuration section below)

File sharing

To make it easy to access the files in the virtual Linux operating system, we have included Samba. We've configured the user's home directory as a file share.

This means that you can edit the source in your favorite Windows editor (that supports UNIX formatted files!) and compile in the virtual machine.

  • Share name: \\debian\user
  • Share username: user (or root if you want to have file permission)
  • Share password: rockbox

Keyboard layout configuration

The Rockbox Debian image is set to US keyboard layout.

To change this run (as root):

  • xf86cfg for the X-related settings and
  • kbdconfig for the pre-X console system
I had problems running xf86cfg, but was able however to edit the file /etc/X11/XF86Config-4, it's quite self-explaining.

Mouse button configuration

By default the mouse buttons are set for right-hand use. To reconfigure for left-hand use, you need to change 2 files in your home directory.

For a standard wheel mouse you can use the following. (If your mouse has more (or less) buttons, you will need to adjust the �pointer� line accordingly.)

First create a file named .Xmodmap ( notice that there is a period before the X) in our home directory (this is the directory you are in when you start Eterm).

.Xmodmap contains the following on a line by itself:
pointer = 3 2 1 4 5

Next, create or edit the .xsession file. Add to it the following on a line by itself:
xmodmap ~/.Xmodmap

The next time you login, the buttons will be switched.

If you are wondering why there are 5 buttons in the "pointer" line, it is because a standard wheel mouse has what is considered as 5 buttons: 1 on the left, 1 on the right, the wheel can be pressed, and scrolling up and down both count as buttons.

Time zone configuration

After installing, it is a good idea to check that the image is set to the correct time and timezone.

If you are not logged in with the root account, then either login as root or from a Eterm or XTerm window type:
su (you will be prompted for the root password)
rockbox (root password) 

To set the timezone, run: tzconfig from a system shell (Eterm or XTerm) and follow the prompts.

If you became root using the su method, finish by typing exit to return from the root account.

The following is probably not needed since the VMware tools program always synchronizes the clock between guest and host computer, but is provided if you don't wish to run VMware tools.

Use date to show the time.

To change the hardware clock (actually the virtual hardware clock):
  • date MMDDhhmmCCYY
  • hwclock --utc --systohc
  • hwclock --show
This will set system and hardware time to MM/DD hh:mm, CCYY. Times are displayed in local time but hardware time uses UTC.

An example of the date command is as follows: date 013013102008 for January 31, 2008 1:10pm)


  • Debian 3.1 sarge
  • Linux kernel 2.4.27

  • VMware tools
  • XFree86 (X11)
  • fluxbox window manager
  • Eterm
  • ssh
  • samba
  • zip, bzip2, unzip, tar
  • cvs, cvsutils
  • svn
  • tetex-base, tetex-extra (for the manual, maybe you will need latex-ucs too)
  • (texlive and/or tex4ht for html manual builds)
  • libsdl-dev (for the simulator)

  • If you need any other package try: "apt-get install <name>"

  • Compilers
arm-elf-gcc 4.0.3 Ipod, gigabeat, sansa, m:robe, ifp-700, H10
m68k-elf-gcc 3.4.6 Iriver, Iaudio
sh-elf gcc 4.0.3-rockbox-1 Archos
x86 gcc 3.3.5 Simulators


Problems with accessing the Samba server

If you have problems accessing the virtual PC through the SMB protocol, you should check if your network card settings in VMWare are set to Bridged and not to NAT; this way Debian will directly connect to your network (do this only if there is a DHCP server running on your network as it will request an IP).

Using the VMware 'pause' functionality can sometimes leave the Samba server unresponsive when the image is re-started. The Samba server can be restarted by issuing the following command as root:
/etc/init.d/samba restart

Problems with physical memory

If you don't have enough physical memory to run the image as downloaded (ie. you can't even start the image to change the memory usage from the player's GUI), open your "Rockbox.vmx" file in a text editor and change memsize = "XXX" to something smaller where "XXX" denoted the amount of physical ram in megabytes. NOTE: Some have found as little 48MB to be sufficient to run the image with tolerable performance using the provided Debian installation as a build tool only though at least 64MB is recommended for it to run acceptably.

Problems with audio playback in the simulator

'user' is not a member of the 'audio' group so it doesn't have permissions to access audio hardware. This causes the simulator to segfault when it tries to play back music. Running the following command as root fixes this:

usermod -G audio user

Additional Tips

Copy and Paste between host and guest operating system

To be able to copy and paste between the host and guest operating system (windows-linux) and vice versa, you have to have "vmware-toolbox&" running while you do it. From the command line type "vmware-toolbox&" and hit enter. A window will appear, don't close it. Minimize it and then proceed with normal operation.

  • To paste to the linux terminal press the middle mouse button or "shift+insert".
  • To copy from the linux terminal just select the text (by holding left-click) just like you do on some IRC clients.
You can make vmware-toolbox program autostart by adding the following in .xsession file that you may have to create in your home directory:
vmware-toolbox &
Eterm &

Change the resolution

To change resolution, run "" as a super user. If you want to use Qemu, you can use xrandr (man xrandr for details) to get a smaller resolution on-the-fly with non-permanent effects (rollback after a X-restart). Configuration of X-Server with /etc/X11/XF86Config-4 file is also a good (but dangerous) way to configure your virtual debian system with permanent issues ;).

Run Windows applications

I always disliked the fact that I couldn't use my favorite text editor (Notepad2) with the VMware Development Platform. The only option I had was to use samba and edit the files I wanted with Notepad2 from Windows but I would prefer not having to switch desktops. So I decided to install Wine on the VMware Debian image and try to enhance the Notepad2 application into the menu. Here's a quick guide on how to do this.

  • Step1: Install Wine

    With the virtual machine already running, right click in desktop and select Xshells > Eterm (or Xterm). The console window will show up. From there simply type:
    "*apt-get install wine*" (without the quotes)
    to begin the installation of the wine package. That's it!

  • Step2: Install the application you want to run with Wine

    You can use samba to copy files from your host computer to the virtual machine. Simply open windows explorer and type:
    "\\debian\user" (or root)

    You can now copy-paste the files needed from the application you want to run in the virtual machine. In my case I just had to copy "notepad2.exe" and "notepad2.reg". I placed them both in a directory I made here: "/usr/bin/winapps/notepad2/". Of course you can choose a different directory if you like.

  • Step 3: Add your application into the menu

    The Debian VMware image uses fluxbox as a windows manager. This is mostly because it's lightweight and highly customizable. Fluxbox uses simple text files to customize the menu (among other things like keyboard shortcuts). All you have to do is to edit this file here:

    In my case I placed this:
    [exec] (Notepad2) {wine /usr/bin/winapps/notepad2/notepad2.exe}

    under "Editors" submenu.

    The general format is:
    [exec] ("name to be displayed in menu") {wine "path of application's .exe"}

    Now you are able to load your application from the menu by right clicking in the desktop. Notice that many windows applications may not run or even crash. For instance I tried to run mIRC but at least for me it freezes on startup.

Use PuTTY and Xming with X11 forwarding

If you want to develop RBUtility, the simulators or WPS editor and don't want to work in the emulator's virtual window (and you're on Windows), but still want to have the power of Linux you can try running Xming and forward X11 through SSH.

  1. Download PuTTY and Xming
  2. Start Xming (run XLaunch with the default settings)
  3. Start PuTTY and connect to the IP address/host name of your virtual machine and enable Connection->SSH->X11->'Enable X11 forwarding'
  4. Now you'll need to login with your username and password
  5. Run any X11 program you like! (HINT: try running them like this xterm &, that'll make them run in background and will let you still get to the SSH shell)

Using Qemu instead of VMware Player

You are maybe a linux user and you don't want to install a non-free and closed part of software (who said vmware ??) in your smart free gnu/linux distro... Qemu can handle vmware's vmdk virtual disks for you !

Assuming you have qemu up and running in your box, and you are in the directory where you have unpacked 7zip archive, you can boot the rockbox's virtual machine with the command:
qemu -hda rockbox-flat.vmdk

The first time you run this system, you will fall back on text console, this is simply because of VMware's configuration of X server. You can fix this replacing "vmware" by "cirrus" in /etc/X11/XF86Config-4 file (Section "Device") and then launch xdm again. (You must login as root to do this.)

Using the VMware image with VirtualBox

VirtualBox is another open-source virtualization solution. If you have an (older) existing VirtualBox setup and want to use the VWware .vmdk image you can convert it to a VirtualBox .vdi image by following the instructions in this tutorial.

As of version 2.1.0 VirtualBox can read .vmdk images, so you should be able to create a new virtual system and associate it with the .vmdk image directly.

Suggestions for improvement

If you have any ideas for improving the VMware image, please write them down here!

The following suggestions have been submitted:

  • To build the pdf manuals latex-ucs is needed. Run "apt-get install latex-ucs" as root to install it. (This should probably be added to a future v5)
  • libmtp, libmtp-dev, and all needed libraries for MTP-only devices should be preinstalled.
  • add MIPSel GCC and binutils?
from EddyComan:
  • Add the necessary packages to build HTML manuals as well as the PDF one.
  • Include a window-based file manager (because I'm a lazy Windows user and I still struggle with finding files and devices without a treeview)
  • Include a cross-compiler, so I can make Windows simulators from VMWare
  • Include Festival, eSpeak or Flite to enable voice building

  • The image should be prepared for everything with rockbox. This includes having the 7zip (debian package p7zip) preinstalled, since the Rockbox sourcecode is in a 7z archive.



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

Copyright © by the contributing authors.