DosBox – From GitHub to Your PlayBook

DosBox is one of the Open Source ports we announced at DevCon America 2011.  The port (by Jeremy’s team) reinforces the richness of the PlayBook platform and made it to Engadget.  Below are updated instructions on how to build and install DosBox from GitHub to your PlayBook.

Disclaimer – questions on specific games belong elsewhere.  CrackBerry has two active threads on the topic: DosBox and DosBox Games.


The host for these instructions is a Mac laptop running MacOS and I deployed on a consumer (i.e. secure) PlayBook Tablet, running a recent build of PlayBook OS 2.0.  I used the latest NDK 2 SDK beta 2.  I believe the instructions apply equally well to a 1.0 release, except for the issue mentioned below.

I used a debug-token to avoid having to sign the applications during the “development” cycle.

Building DosBox

DosBox requires a number of dependencies.  For the most part the build steps are pretty easy, but there are a couple of places that Jeremy indicated he wanted to improve.

We will end-up creating and building 5 projects, with DosBox being the top one, and the one we will deploy:

Let’s get started

Downloading Sources

Download DosBox, SDL, TouchControlOverlay and OggVorbis from GitHub.  You can either git clone them, or download a ZIP and unzip them.  Use the default (master) branches.

Rename SDL into SDL12.  This is because some of the projects have a dependency on that name; Jeremy says he will remove the need for this.

Download SDL_sound from  I used version 1.0.3.  Unzip it into DosBox/3rdparty/SDL_sound/src.  The SDL_sound directory should look like:

bash-3.2$ pwd
bash-3.2$ ls -p -a -1 . src


As shown by the .cproject and .project files, this project will be imported into the IDE.

Build OggVorbis

Currently OggVorbis needs to be build from the command line.  Instructions are at OggVorbis/vorbis/README, but you just need to set the environment variables from the NDK (via bbndk-env), then go to vorbis/qnx and execute a make.

Import Projects into Momentics

Import the 5 projects into your IDE workspace.  DosBox, SDL and TouchControlOverlay are top projects.  Vorbis is at OggVorbis/vorbis and SDL_sound is at DosBox/3rdparty/SDL_sound.

You cannot copy the vorbis sources – same reason why it needs to be compiled via make.

You need to adjust one property of SDL_sound.  Open the properties dialog

Now go to C/C++Build > Settings > QCC Compiler > PreProcessor.  Select “All Configurations” and change the include path ${workspace_log:/vorbis/ogg/include} to ${workspace_loc:/vorbis}/../ogg/include.

Almost ready.  Now just make sure all the projects have set the same build configuration.  Since I’m using an actual PlayBook, it is a Device-* configuration; I used Device-Debug.

Finally, right-click on DosBox and Build Project.  There will be some warnings that you can ignore for now (we will encounter libbps shortly).

Package and Deploy DosBox

As part of package and deploying we will need to specify the target and ensure that the debug token is deployed appropriately.  The target can be Window->Show View->Target Navigator.  Momentics will also ask you for details if necessary; for example, it asks how to configure the debug-token via a popup:

I selected the second option because I had previously created a debug token – already uploaded to my PlayBook.

Libbps.So and PlayBook 2

Trying to package DosBox generates the following error:

The problem is that blackberry-tablet.xml descriptor is designed for PlayBook 1, and requires the bundling of a (new, 1.0) copy of that is not present in 1.0. Incidentally, this is the same message you get if you try to run the Samples from NDK1.0 on a PlayBook 2.0 build. The solution is to remove that line in blackberry-tablet.xml, rebuild, and redeploy, this time successfully.

Run DosBox

Next is to try to mount a PlayBook directory as a DOS disk so we can run applications (like Games) from there. The first thought would be to use the shared download directory, at /accounts/1000/shared, but PlayBook OS does not give default access to this directory to applications:

Rather, what’s needed is to request this access via the application description.  You can manually edit the blackberry-tablet.xml file, or you can use the IDE to do so.  Using the IDE you request the permission and the IDE will insert the correct XML element:

Rebuild DosBox and redeploy and rerun, and this time around the mount will succeed.

Running a Game

I further tested DosBox with one of the games from BestOldGames.netPrince of Persia.

The IDE includes a File Explorer that can be used to explore and manipulate the Target.  I copied the ZIP for PoP in a /accounts/1000/shared/downloads/DOS/ directory, and later unzipped it using unzip natively via an ssh connection.

To run the game, I just mounted the above directory in a DOS disk (C:), navigated on directory down and ran the main command (Prince):

If you want to use DosBox for actual game playing you may want to adjust some of its settings – they are at /accounts/1000/appdata/<DOSBOXAPP>/data/.dosbox/dosbox-0.74.conf; I changed none as I just wanted to test the application.

Enjoy!  An internet search quickly finds instructions for other games ([1], [2])

About these ads

About pelegri

Sr. Director for Open Source at Research in Motion.
This entry was posted in Native and tagged , . Bookmark the permalink.

8 Responses to DosBox – From GitHub to Your PlayBook

  1. Pingback: Elsewhere… Mar 9, 2012 | Open BB News

  2. Rus Langdon says:


    THis looks really good. I only just purchased a Playbook, and I have downloaded and installed the current DOSBox app available from RIM on the App site.

    It is good, and allows me to run a sophisticated interpreter for the APL language, that provides me handheld access to a bunch of code I built that I still use. (I run it on Linux inside a DOSemu box, and on Windows-XP in a Cmd window – but minor problems exist in both those environments). It is on the Blackberry Playbook that everything – such as the code to access APL direct-access files (.ie APL database files), and the mouse support on top of the graphics window – all works correctly. For me, this is a big result, and allows the Playbook a very valuable general-purpose device. I earlier bought an iPad, with a view to doing something like this, and was stopped cold by Apple’s direct suppression of any interpreters or local language support for their product.

    I put a short note on the “Crackberry” site about this, along with two photos of some of APL results running interactive graphics & analytics. I will try to build the DOSbox environment for my own use, from your guidelines here.

    Thanx for posting this information.

    - Rus

  3. Rus Langdon says:

    Oh,. I meant to leave this link to the post on the “” website, as it has two photos of what the APL interpreter can do – ie. interactive graphics generated directly from APL database files resident on the Playbook. I use the WiFi link, and the Samba code running on the Playbook, accessed from a Windows-XP box, to easily set up the environment on the Playbook, and transfer the datafiles over to a directory “\accounts\1000\shared\misc\market\data”, while the interpreter and workspaces reside in: “\accounts\1000\shared\misc\aplv5″. It all works quite well, given that you use DOSBox to mount the \accounts\1000\shared\misc\ directory as your DOS “c:\” disk. All tests so far show all floating point calculations being done and reported on the PB display correctly.

    Title: DOSBox does APL on the Playbook!

    At the bottom of the post, are two photos taken by me using a Kodak digital camera of what is possible. The APL interpreter running on the Playbook, inside the DOSBox enviroment, and accessing only data resident on the PB, can generate the interactive graphic images.

  4. Pingback: Elsewhere… Mar 25, 2012 | Open BB News

  5. steve says:

    can you help me, I followed what you said but I get this, “C:\development\bbndk-2.0.1\host\win32\x86\usr\bin\ntoarm-ld: cannot find -lSDL_sound”

    Can you explain in detail what you mean about renaming SDL to SDL12? The project imports as SDL12 but the folder in the filesystem is SDL.


  6. Jerry says:

    I’m having trouble compiling this. I used Import, Existing Projects to workspace. I followed the instructions. I’m getting 87 errors, things like : ‘bmp’ undeclared (first use in this function) bbutil.c /dosbox/src. Any ideas

    • pelegri says:

      Most likely the instructions and the makefiles need to be adjusted to most recent releases. Where are you compiling on? PlayBook? BB10? And against which specific version?

      We should do a pass through all the samples – as a community – and try to get them all to compile against the latest BB10 release.

  7. Jerry says:

    Thank you for your help. It turned out I tried to build some of the projects without adding all of them. I deleted the whole project folder, imported from the archive, set all the Build-Configurations to Release, then Build All. Sucessful Build. I’m using Momentics 2.1.0.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s