Marmalade SDK Mobile Game Development Essentials

5 (1 reviews total)
By Sean Scaplehorn
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Getting Started with Marmalade

About this book

Modern mobile devices are capable of supporting video games of amazing quality but there are so many different devices and platforms how can you support them all?  The answer is to use the Marmalade SDK to write your code once and deploy it to all popular mobile platforms at the touch of a button.

Marmalade SDK Mobile Game Development Essentials will provide you with everything you need to know to transfer your existing C++ videogame programming knowledge to mobile devices.  From graphics and sound to input methods and actual deployment to device, this book covers the lot.Learn how to make use of keys, touch screen and accelerometer inputs for controlling your game.Take the pain out of supporting a varied range of target devices, both across multiple platforms and multiple specifications.

Step by step from “Hello World” to a complete game, this book will show how to use the Marmalade SDK to develop games for mobile devices.

Learn how to make dazzling 2D and 3D games complete with fully animated characters, music and sound effects that can be deployed to all the leading mobile platforms, whilst ensuring it can run on a wide range of possible devices, from low specification to high end.

If you want to join the exciting world of mobile videogames then Learning Mobile Game Development with Marmalade will show you how to do so, fast!

Publication date:
November 2012


Chapter 1. Getting Started with Marmalade

In this chapter, we will first be learning how to get the Marmalade SDK set up for development. While Marmalade is available in both Windows and Mac versions, the Windows version is the most developed of the two and is what we shall be primarily covering in this book. By the end of this chapter, we will know how to do the following:

  • Set up a Windows PC for development using the Marmalade SDK

  • Create and build a "Hello World" project

  • Deploy and run the "Hello World" project on several mobile platforms

So without further ado, let's get started!


Installing the Marmalade SDK

The following sections will show you how to get your PC set up for development using Marmalade, from installing a suitable development environment through to licensing, downloading, and installing your copy of Marmalade.

Installing a development environment

Before we can start coding, we will first need to install a version of Microsoft's Visual C++, which is the Windows development environment that Marmalade uses. If you don't already have a version installed, you can download a copy for free. At the time of writing, the Express 2012 version had just been released but the most recent, free version directly supported by Marmalade was still Visual C++ 2010 Express, which can be downloaded from the following URL:

Follow the instructions on this web page to download and install the product.


For the Apple Mac version of Marmalade, the supported development environment is Xcode, which is available as a free download from the Mac App Store. In this book, we will be assuming that the Windows version of Marmalade will be used, unless specifically stated otherwise.

Choosing your Marmalade license type

With a suitable development environment in place, we can now get on to downloading Marmalade itself. First, you need to head over to the Marmalade website using the following URL:

At the top of the website are two buttons labeled Buy and Free Trial. Click on one of these (it doesn't matter which, as they both go to the same place!) and you'll see a page explaining the licensing options, which are also described in the following table:

License type



This is free to use but is time limited (currently 45 days), and while you can deploy it to all supported platforms, you are not allowed to distribute the applications built with this version.


This is the cheapest way of getting started with Marmalade, but you are limited to only being able to release it on iOS and Android, and your application will also feature a Marmalade splash screen on startup.


This version removes the limitations of the basic license, with no splash screen and the ability to target any supported platform.


This version adds dedicated support from Marmalade should you face any issues during development, and provides early access to the new versions of Marmalade.

When you have chosen the license level, you will first need to register with the Marmalade website by providing an e-mail address and password.


The e-mail address you register will be linked to your license and will be used to activate it later. Make sure you use a valid e-mail address when registering.

Once you are registered, you will be taken to a web page where you can choose the level of license you require. After confirming payment, you will be sent an e-mail that allows you to activate your license and download the Marmalade installer.

Downloading and installing Marmalade

Now that you have a valid license, head back to the Marmalade website using the same URL we used earlier.

  1. If you are not already logged on to the website, do so using the Login link at the top-right corner of the web page.

  2. Click on the Download button, and you will be taken to a page where you can download both the most recent and previous releases of the Marmalade installer. Click on the button for the version you require, to start downloading it. Once the download is complete, run the installer and follow the instructions. The installer will first ask you to accept the End User License Agreement by selecting a radio button, and will then ask for an installation location.

  3. Next, enter the file location you want to install to. The default installation directory drops the minor revision number (so version 6.1.1 will be installed into a subdirectory called 6.1). You may want to add the minor revision number back in, to make it easier to have multiple versions of Marmalade installed at the same time.

  4. Once the installer has finished copying the files to your hard drive, it will then display the Marmalade Configuration Utility, which is described in greater detail in the next section. Once the Configuration Utility has been closed, the installer will then offer you the option of launching some useful resources, such as the SDK documentation, before it exits.


    It is possible to have more than one version of the Marmalade SDK installed at a time and switch between versions as you need, hence the advice regarding the installation directory. This becomes very useful when device-specific bugs are fixed in a new version of Marmalade, but you still need to support an older project that requires a different version of Marmalade.

Using the Marmalade Configuration Utility

The Marmalade Configuration Utility window appears at the end of the installation process, but it can also be launched from its shortcut icon:


When launching the Marmalade Configuration Utility on Windows Vista or Windows 7, you should right-click on the icon and select the Run as administrator option, otherwise any changes that you make might not be applied.

The most important element is the License Information box. Below this is a button labeled Activate License... that allows you to activate your Marmalade installation. Follow these steps to get activated:

  1. Click on the Activate License... button to display a dialog box that asks you to enter the e-mail address and password you used when obtaining your license.

  2. The dialog box also has a drop-down box labeled Machine ID (Ethernet MAC address), which you should make sure is set to the MAC address of an Ethernet port that will always be present on your computer. Normally you won't need to change this.

  3. Click on the OK button to connect to the Marmalade licensing server. You will be asked to select the license you want to install. (Normally there will only be a single option available.) Do so and click on OK.

  4. A summary of the End User License Agreement (EULA), appropriate to the type of license you are using, will be displayed, so click on OK to accept it. A reference to the full EULA is also provided in the dialog box.

  5. You should now see a message confirming successful license installation. At this point Marmalade is ready to go!

Before we finish here though, let's look at the other available options. The first is labeled Marmalade System (S3E) Base and consists of a drop-down box that allows you to select the version of the Marmalade SDK you want to use, if you have more than one installed of course!


S3E is short for Segundo Embedded Execution Environment and this is the lowest layer of the Marmalade SDK. This naming convention was adopted by the SDK during its early days of development, and it remains to this day. As you will see later in this book, there are a great many APIs that are prefixed with this name.

The Default Build Environment lets you choose which development environment you wish to use, assuming you have more than one supported version of Visual C++ installed.

The drop-down box labeled RVCT ARM Compiler allows you to change the compiler that will be used when making a device build. (Most mobile devices contain an ARM CPU, so we must compile our code for this processor type.) Marmalade ships with the GCC compiler and uses this by default, but it can also make use of the RVCT C++ compiler from ARM, which is an additional purchase and can produce better optimized code. We normally do not need to change this setting and can leave it on the first option labeled Do not use RVCT.

The Advanced Options... button provides access to a more verbose project-building option and also some experimental parts of the SDK. You will not normally need to make any changes here.

Managing your Marmalade account and licenses

Before we get on to doing some actual coding, it is worth mentioning how you can manage your Marmalade license and account. If you head back to the Marmalade website and log on, you'll notice a link at the top-right corner of the site labeled My Account.

Hover your mouse pointer over this link, and a menu of options that allow you to change your account details and license usage will appear. The following sections provide further information on each of these options.

Viewing an overview of your account

The menu option called Overview takes you to a page where you can see your personal details along with a summary of the number of licenses and users you have set up under your account. From this screen, there are buttons that allow you to update your profile, modify registered user information, buy new licenses, and manage existing ones.

Updating your profile information

Clicking the Profile option in the My Account menu or clicking on the Update Profile Information button on the profile overview screen will display a page that allows you to alter information such as your name, contact information, address, and account login password. There is also a checkbox that allows you to sign up for e-mail news updates from Marmalade.

Managing your licenses

Clicking the Licenses link in the My Account menu or clicking on the button labeled Manage on the overview screen will take you to a page where you can upgrade the level of your license or buy further licenses for new team members.

The Manage Licenses section at the bottom of this page shows all the currently active licenses in your account, and also allows you to release a license that is currently in use so that it can be transferred to another computer.

Releasing a license is useful if you need to work on a different computer for some reason, or if you have a new development computer that you wish to transfer your license to. You can release a license as often as you like, but a single license can only be used on a single computer at a time.

Managing your user list

If you are working in a team then you will obviously need more than one Marmalade license, but you also need to manage who has access to those licenses. Clicking on the Users option in the My Account menu or clicking on the Manage Users button on the overview page allows you to do this.

This page shows a list of all the users assigned to your account, and also has an Invite Users section that allows you to add new users to your account. Enter their e-mail addresses in the boxes provided, and click the Send invite button to send them a mail telling them how to activate their own Marmalade account.


Creating a Marmalade project

With Marmalade installed, we can now get down to doing some coding, and what better place to start than with the classic example of a "Hello World" program.

Creating the "Hello World" project

To begin a new project, we must first create an MKB file, which is Marmalade's own project file format. We use MKB files to specify all the source files, libraries, and build options needed to build our project.

The MKB file is actually used to generate a Visual C++ project file, but whenever we want to add or remove a source file to our project, we must do so by editing the MKB file and regenerating the Visual C++ project file from it using Marmalade's make file builder script, which we'll be looking at in just a moment.

In addition to source files, the MKB file also allows you to list all the other datafiles and resource files that your application will need in order to run, as this information will be needed when it comes to deploying your application on different mobile platforms.

Marmalade does come with a small tool called the LaunchPad, which can be used to create a new project, but in the interest of learning how a Marmalade project is put together, we will go about creating everything from scratch instead.


Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at If you purchased this book elsewhere, you can visit and register to have the files e-mailed directly to you.

The MKB file for the "Hello World" project

Let's make a start on our "Hello World" project. Create a new directory to hold the project files, and then create a file called Hello.mkb in this directory and enter the following into it:

# Main MKB file for Hello project

# Modules used by this project
# The files that make up the project (source, data etc.)


# Settings to configure the deployment process 
  caption="Hello World"

The first section of Hello.mkb is the subprojects section, which lists all the additional code modules used by our application. In this instance, a code module is a library that can be added to our project either as a group of C or C++ source files or, alternatively, as pre-compiled, linkable object files accompanying header files. In the previous example, there is just one, iwgx, which is the Marmalade code module responsible for rendering graphics.

All the higher level modules within Marmalade are referenced in this manner, and you can also use this system to create your own modules to enable code re-use across projects. To create a subproject module we use an MKF file, which amounts to a little more than an MKB file with a different file extension! When we add an entry to the subprojects list, the Marmalade makefile builder script will search for a suitable MKF file that describes each subproject. We'll see detailed examples of how to do this later in the book.

The next section is labeled files, and this is where we list all the source code files for our project. It is possible to split your source files up into different directories. To make it easy, you simply put the directory name in brackets ((source) in our example) and then list all the source files in the directory below.

It is also possible to group the related files together into subsections, which we do using square brackets ([SourceCode] in our example). Any source files below this will be added to that section and will then appear in a separate folder in the Visual C++ Solution Explorer. There is no need for the directory and group names to match, and indeed you can have more than one directory in a group if you so wish.

Finally we have the deployments section, which is where various settings are made that control the process of deploying our application to different device types.

In our example we are making two settings. The name setting provides the filename of our final executable and is also used in file and directory names created for us by Marmalade, while caption sets the name that will appear under the application's icon when installed on a device.

Both the aforementioned settings are examples of general settings that apply across all device types, but there are also a great many other settings available, which are specific to particular platforms, such as iOS or Android. A full list of these can be found in the Marmalade Documentation help file that is installed as part of the Marmalade SDK, and we'll also be looking at this in Chapter 8, Supporting a Wide Range of Devices, of this book along with the additional sections of the MKB file that have not yet been shown for this example.

The use of whitespace in the MKB file is pretty much up to your own personal preference. Though most of the Marmalade examples tend to indent entries within blocks, tabs or spaces can also be used.

Comments can also be added using the hash (#) character. Everything after the hash character till the end of the current line is then considered a comment.

The source file for the "Hello World" project

We may now use the MKB file for our project but we still can't do anything with it yet, as we've told Marmalade that there is a source file called Main.cpp, which doesn't exist yet. If we were to try and use the MKB file to build the project, we would get an error reported about this missing file, so let's create it.

You will recall that we said that our Main.cpp file would reside in a directory called source in the MKB file, so first create this new subdirectory in the project directory. Now, create a file called Main.cpp in the source directory and enter the following into it:

// Learning Mobile Game Development with Marmalade
// Chapter 1 - Hello
// Marmalade SDK includes
#include "IwGx.h"
#include "s3eConfig.h"
#include "s3eDevice.h"
// Main entry point
int main()
  // Initialise Marmalade modules
  // Set a default message, then check the ICF file to see if
  // a proper message has been specified
  char lMessage[S3E_CONFIG_STRING_MAX] = "Hello!";
  s3eConfigGetString("APP", "Message", lMessage);

  // Set screen clear colour to black
  IwGxSetColClear(0, 0, 0, 255);

  // Draw text at double default size
  // Loop until we receive a quit message
  while (!s3eDeviceCheckQuitRequest())
    // Allow device to process its internal events
    // Clear the screen
    // Display our message on screen
    IwGxPrintString(10, 10, lMessage);
    // Flush IwGx draw buffers to screen
    // Swap screen double buffer
  // Terminate Marmalade modules

  return 0;

The code should be fairly simple to follow, but here is a quick breakdown.

First we reference the include files to allow us to use the parts of Marmalade that are necessary for our application, and then we create our main entry point function main. This is equivalent to the main() function in a standard C or C++ program, except that it takes no parameters as Marmalade does not accept command-line parameters. It's quite hard to specify command-line parameters on mobile devices, so there really isn't any need!

The first thing our application needs to do is initialize Marmalade's rendering module with a call to IwGxInit(), which will initialize the screen and set up standard behavior such as double buffering of the display.

Next we allocate a character buffer that will contain the message that we will be displaying on screen. We initialize it to a default message to make sure that there is something to be shown, but we then use a call to the s3eConfigGetString function to see if another message has been specified in the application's configuration file, which will be explained in more detail shortly.

The following call to IwGxSetColClear sets the desired screen background color to black, and then the call to IwGxPrintSetScale tells Marmalade to display text using its built-in font (which is quite small in size) at double its default resolution.

We now enter our main processing loop that will continue until the s3eDeviceCheckQuitRequest function returns a true value, which will happen if the user quits the application or if the device sends a quit request to the application for any reason.

The first line of our main loop is a call to s3eDeviceYield. This is a very important function that must be called at regular intervals during our application, to allow the device's OS to perform important tasks such as handling events—user inputs, incoming phone calls, and so on. Under most circumstances, a single call to this function in the main loop is sufficient.

The value passed to s3eDeviceYield is the maximum time (in milliseconds) that our application will yield to the OS for. Normally this value is set to zero, which yields long enough for the device to process the events, but will return control to our application as soon as all the events have been processed.

Next, we call IwGxClear to clear the screen and then use IwGxPrintString to display a message on the screen. IwGxFlush causes the Marmalade engine to then process all our drawing requests to yield a final screen image that we can then display to the world using IwGxSwapBuffers.

Finally, outside the main loop, we call IwGxTerminate to shut down Marmalade's rendering engine, and finally return zero to indicate that our application was completed without any errors.

Building the "Hello World" project

Now that we have set up our project and written the necessary code, it is finally time to build it. To do this open a Windows Explorer window and navigate to the folder containing Hello.mkb, and then just double-click on the file. You might see a brief flash of a command-prompt window, but after a short delay, Visual C++ should automatically start up with our project.

The act of double-clicking the MKB file actually causes the Marmalade makefile builder script to be executed. This is actually a script written in the Python language, which takes the MKB file and outputs a Visual C++ solution file and other required elements. A file association is automatically set up when installing Marmalade, so you can either double-click the file, or alternatively use the command prompt to create your project by changing to the project directory and entering Hello.mkb.

Before we go on to compile and run the project though, let's take a quick look at what Marmalade has created for us.

If you look in the project directory, there should be two new directories, which are described in the following sections.

The build directory

One of the directories created by the MKB file will be named build_hello_vcxx, where the "xx" part is dependent on the version of Visual C++ you are using.

This directory is Marmalade's working directory and is where all the object files created during building are stored. It will also be the home to our deployment packages when it comes to making device builds.

A Visual C++ solution file created from the MKB file also lives in this directory, and while you can use these files to switch between projects, you should never add files or change project settings using the options in the Visual C++ IDE.


Always make project changes to the MKB file, then either close Visual C++ and double-click the MKB file to rebuild the solution, or alternatively perform a build inside Visual C++ to update the solution file with any changes. You should not make changes directly within the Visual C++ IDE as they will be lost the next time that the MKB file is used to recreate the project file.

The data directory

The MKB file will also generate a directory called data, and this is where Marmalade requires you to place any files that your application will need to load, such as images, 3D model data, sound files, and others. While you can create this directory and these files yourself, and it will not cause a problem, we might as well let the makefile builder do it for us!

If you take a look inside the data directory, you will see that the build process has also created two more files called app.icf and app.config.txt. These files are used to configure your application and are explained in the following sections.

The app.config.txt file

This file provides a list of all the application-specific settings that can be made in the app.icf file, along with a description of what each setting does and how it is used. There are two reasons for using this file:

  1. Adding entries to this file keeps your project settings documented in a single place, so other coders can check this file to see what a particular setting does.

  2. Any setting contained in the app.icf file that is not documented in the app.config.txt file will generate a runtime error message when you try to specify or access it in your program.

Additionally, the app.config.txt file also requires you to define a group name for your settings, which is specified by using square brackets.

If you look at the s3eConfigGetString function call in the "Hello World" project code, you will see an example of this. This call is trying to access a setting called Message from the group APP, so let's add this into the app.config.txt file now, to stop any asserts from firing when running our application. Edit the file and add the following lines to the bottom of it:

Message      The message we want to display on screen
The app.icf file

The app.icf file is used to add the configuration settings to your application, and as already stated these must be either documented in your project's app.config.txt file or must alternatively be defined in a similar file within one of the subprojects used by your application.

Adding a configuration setting is simply a matter of adding the setting name followed by an equals sign and then the value you wish to use. You must also ensure that you add the setting to the correct group, using the same square bracket notation used in the app.config.txt file. Here's an example:

Message="Hello World"

The settings made in the app.icf file can then be accessed in code using the s3eConfigGetInt and s3eConfigGetString functions.

The app.icf file also has another couple of tricks up its sleeve, as settings can also be made that are specific to a certain platform or even specific to an individual device. Here's how you achieve this:

  • To limit the application to a particular platform add the line {OS=platform}, and any settings following this will only apply to that device platform. The value used for platform is normally just the name of the operating system, for example, ANDROID, BADA, or WINDOWS, although it is worth mentioning that you should use IPHONE to refer to iPhones, iPods, and iPads! If in doubt, you can use a call to s3eDeviceGetString(S3E_DEVICE_OS) to discover the value that you need to use for a particular operating system.

  • To limit the application to a particular device or devices, add the line {ID=platform id}, and any following settings will only be applied when run on the specified device. The platform value is the same as that used previously, while the id is an identifier for a particular device. The format of the id value depends on the operating system, but you can discover what value to use for a particular device by calling s3eDeviceGetString(S3E_DEVICE_ID). It is also possible to provide a comma-separated list of id values if you need the settings to apply to more than one device.

Note that both of these settings will continue to take effect until a new OS or ID value is specified. If you wish to return to applying all the settings globally, just add {} after your last OS- or ID-specific setting.


It is good practice to ensure that your OS- or ID-specific sections always terminate with {}, as not doing so can lead to a major head-scratching session when you deploy to device and find that some setting you have just changed doesn't appear to be taking effect.

To illustrate the use of {} , let's add some settings to the "Hello World" project app.icf file. Open the file and add the following lines to the bottom of it:

Message="Hello Android!"
Message="Hello Bada!"
Message="Hello iOS!"

Message="Hello BlackBerry!"
Message="Hello Windows!"

You should be able to see from this that we have specified a different message string for each different platform type that we wish to support.

Building and running in the Windows simulator

Now it's time for us to see the "Hello World" project in action. It is just a simple matter of compiling the code in Visual C++ and running it.

To compile the code, simply select Build | Build Solution or press the F7 key. Visual C++ will compile and link the Main.cpp file.

Now we can execute the program. Select Debug | Start Debugging or simply press F5. The Marmalade Windows Simulator will be launched, which will in turn load and execute our program. The following image shows what the "Hello World" project should look like when run in the Windows Simulator:

You will notice that the Windows Simulator contains a number of menu options. These allow you to make the Windows Simulator run in as close a manner to any device you choose as possible. The best way to see what you can change is to explore the menu options yourself, but here are a few of the more useful things you can do:

  • Accelerometer: Testing accelerometer inputs on Windows would be impossible without Configuration | Accelerometer.... This brings up a dialog box that allows you to use the mouse to rotate a 3D image of a phone, to simulate the accelerometer input.

  • OpenGL ES version: The Windows Simulator option Configuration | GL... allows you to emulate different versions of OpenGL ES, which makes it easy to see what your game may look like on different types of hardware. It also allows you to disable OpenGL ES support entirely, which will then force Marmalade to use its built-in software renderer.

  • Screen resolution: Mobile devices have a wide range of supported screen resolutions, so Configuration | Surface... allows you to select any size for the screen that you desire.

  • Emulation of device suspend and resume: It is easy to forget that the primary function of many devices is actually that of a telephone rather than of a gaming platform, which means your application could potentially be interrupted at any time by an incoming call. Marmalade takes care of most of the fiddly details of handling this automatically, but there may still be situations when you need to do something special under such circumstances. The Windows Simulator allows you to test whether your application responds correctly by way of Events | Simulate Suspend and Events | Simulate Resume.


Deploying a Marmalade project

We have now managed to create and run our first Marmalade application, but running it on Windows isn't our ultimate goal. The whole reason for the Marmalade SDK is to make it easy for us to develop our application once and then deploy it on a whole range of mobile device platforms.

Of course we might need to alter some of our assets, for example, because we are targeting a wide range of different screen resolutions and want our application to look its best at all times, the code itself should need no modification in order to run successfully.

To illustrate this, we will now take the "Hello World" project and get it running on a number of different mobile device platforms.

Compiling the "Hello World" project for the ARM CPU

Running our project in Windows meant we were compiling our code using the standard Visual C++ compiler and therefore generating Intel x86 code. However, it is a fact that the vast majority of mobile devices available today contain some version or other of the ARM processor, so the first thing we need to do is compile our code for ARM.

Luckily, Marmalade has made this incredibly easy for us. At the top of the Visual C++ window, you should see a drop-down box that defaults to a setting called (x86) Debug.

If you open the drop-down box, you will see several build types pre-configured for us, but the one we are interested in is the GCC (ARM) Release option. Select this and build the solution again (Build | Build Solution or press F7), and Visual C++ will use the GCC compiler to create an ARM version of our application.

Now we just need to get the code onto a device!

Deploying the "Hello World" project

Now that we have an ARM-compiled version of our code, we need to create an install package so we can test it on a real mobile device. To do this we need to use Marmalade System Deployment Tool. Follow these steps to go through the deployment process:

  1. To launch the tool, make sure the GCC (ARM) Release build type is selected and the code has been compiled. Select Debug | Start Debugging (or press F5). Instead of running the code in the debugger (which would make little sense given that the Visual C++ debugger can only debug an Intel x86 executable), Marmalade System Deployment Tool will be launched instead.

  2. The program will first ask us to select the build type we wish to deploy and will have a number of radio buttons for the types available. Only those build types that are currently built will be selectable. In our case, we need to select the ARM GCC Release radio button and then click on the button labeled Next Stage >, to proceed to the next step.

  3. The next page asks us to select a deployment configuration. We can specify the directory where we want our deployed package files to be created, and we also have a list of checkboxed items for the available deployment configurations that we can choose from. Marmalade allows us to create different configurations, which means we can deploy different resource packages to different devices. For now we won't concern ourselves with any of this, so just ensure that the Default setting is checked and then click on the Next Stage > button again.

  4. We are now presented with a page listing all the device types that we can deploy to. Use the checkboxes to select which platforms to deploy to, and then click on Next Stage > once more to be taken to the final page.

  5. At the top of this last page, we can see a brief description of the different deployment types we are about to make, with drop-down boxes for each, to specify whether we should just generate the necessary package files, ignore that build type completely, or optionally install and run the package as well.


    The Package and Install options available in the Marmalade System Configuration Tool often rely on your system being set up with extra third-party software that isn't automatically installed as part of the Marmalade SDK. For this reason in this book, we will generally keep to using the Package option and install and run our deployment packages using manual methods.

  6. Now that we have configured the type of deployment we want, just press the Deploy All button and Marmalade will make packages for all the different targets we selected.

The default location for the deployment packages is within the Marmalade Build directory. If you use Windows Explorer to look into this directory, you will see that a new directory called deployments has been created. In turn, this directory contains a folder called default, which comes from the deployment configuration we used.


It is possible to open Windows Explorer to the deployment folder by clicking on the Explore… button on the final page of the deployment utility.

The default directory contains subdirectories for each of our selected deployment platforms, and each of these will contain a release directory since it was the release build that we created the deployments from. Note that it is also possible to deploy a debug build, which can be useful when debugging. Go into the release folder and there you will find our freshly made deployment package.

All that is left to do now is to install and run it on a device.

Installing on Android devices

Let's start by looking at how to install an Android build.


Before being able to make an Android deployment with the deployment tool, there is a prerequisite that the Java JDK must be installed. You can download this from the following web page:

The Android package file for the "Hello World" project is called Hello.apk, and to install it we first need to copy it to an Android device. This can be done by copying the file to an SD card, or if your device has built-in storage memory, copying the file into that.

Before we can install our package, we first need to make sure that the Android device will allow us to do so. Go into your device's Settings program and select the Applications option. Here there is an Unknown sources option, which allows us to install our own packages. Make sure this option is ticked.

Next find the file manager application on your device. Different devices may have different names for this application, but it often has an icon with a picture of a filing cabinet folder on it. Navigate the directories to find the location where you copied the Hello.apk file, then tap on the file's entry in the list.

The screen will change to show a big list of things that the application is asking to access, along with the Install and Cancel buttons. Click on the Install button and the package will be installed. You can then choose the Open button to start your application, or the Done button if you don't want to run it now. Click on Open and we should then be greeted with our Hello Android! message.


By installing the Android SDK, it is also possible to speed up testing on the device by allowing the deployment tool to automatically package, install, and run the deployed package. Instructions on setting up the Android SDK so this will work can be found in Chapter 10, Extending Marmalade with the Extensions Development Kit (EDK) of this book.

Installing on iOS devices

If you've tried to create an iOS build of the "Hello World" project, you will have noticed that it currently fails to complete with a signing error. This is because you will need to provide Marmalade with some certificate files, which can only be generated by becoming a registered Apple developer.

Joining the iOS Developer Program currently costs $99 per year, and you can find more details about it at the following web page:

Once you've signed up, you'll be able to access the iOS Dev Center that will then allow you to create the required certificates. Normally you would require an Apple Mac to generate these certificates, but, handily, Marmalade provides a small utility called the iPhone Sign Request Tool that gets around this issue. Here is what you need to do:

  1. Launch the Marmalade iPhone Sign Request Tool and fill in the fields as follows:

    1. Certificate Request File: Pick a location where this file will be saved. You will need to upload this to the iOS Dev Center shortly.

    2. Key File: Choose developer_identity.key from the drop-down box.

    3. Common Name: The name you used when registering with the iOS Developer Program.

    4. Email Address: The e-mail address you used when registering with the iOS Developer Program.

  2. Now log on to the iOS Dev Center and click on the iOS Provisioning Portal link.

  3. In the left-hand pane, click on the Certificates link. Click on the Development tab and then on the Request Certificate button to bring up a page of instructions. On this new page, press the Choose File button to upload the file you generated in step 1.

  4. Click on the Certificates link in the left-hand pane again, and click on the link telling you to download the WWDR intermediate certificate. Save this file into the subdirectory s3e\deploy\plugins\iphone\certificates of your Marmalade SDK installation.

  5. Refresh the Certificates page in your web browser until you see a Download button in the Action column. Click on this button and save the file into the directory from step 4, renaming it to developer_identity.cer.

  6. In the left-hand pane, click on the Devices link to register your test devices with the iOS Dev Center by clicking on the Add Devices button and then entering a description for the device and its 40-character hex device ID. There is a link labeled Finding the Device ID, which tells you how to discover this value for a particular device.

  7. Next click on the App IDs link and then on the New App ID button, and register a new App ID to use for your applications. You just need to enter a description (which can be anything you want) and a bundle identifier that is of the form com.domainname.appname. The domainname part can be pretty much anything you like (it doesn't necessarily have to relate to a real URL), while the appname part should either be the name of your application, or you can use an asterisk that then lets you use that App ID for any application.

  8. Click on the Provisioning link and then click on the New Profile button. Enter a descriptive name for the profile and tick the checkbox next to your certificate name. Select the App ID you generated in step 7 from the drop-down box, and then tick all the checkboxes for any device that you want this provisioning profile to apply to.

  9. Click on the Provisioning link again and keep refreshing this page until a Download button appears next to your new provisioning profile.

There is more information on this process in the Marmalade Documentation help file, and there are also How To tabs on most of the iOS Provisioning Portal pages explaining the processes involved, although most of these assume that you are using an Apple Mac to generate the various files.

With all those hurdles negotiated, we can then use Marmalade System Deployment Tool to generate a properly signed iOS install package, which will be named Hello.ipa. Now to get it installed onto a device!

It is possible to use iTunes to install your builds, but be warned that it tends to be a little bit of hit and miss as to whether it will work. Sometimes iTunes does not recognize that a new build is available and needs to be synched to the device. In my experience, a more reliable option is to use the iPhone Configuration Utility , which is a freely available Apple tool that can be downloaded from the following URL:

First of all, you need to let the iPhone Configuration Utility know about your provisioning profile. Click on Provisioning Profiles in the far left pane and then click on the Add button in the toolbar. Navigate to the provisioning profile file you created in step 9 and click the Open button to add it to the list of available profiles. Alternatively, you can drag-and-drop the file into the list from Windows Explorer.

Next, click on the Applications entry in the left-hand panel and then click on the Add button. Find the Hello.ipa file in the deployment's release directory and click on OK to add it to the list of known applications, or again you can drag-and-drop the file from Windows Explorer into the list.

Now connect your iOS device to your computer using a USB cable. It should appear in the bottom of the left-hand pane after a short delay. Click on the name of your device and you should see five tabs appear in the main panel. Click the Provisioning Profiles tab and then click on the Install button next to your provisioning profile. Once done, this button will change to become a Remove button.

Our next step is to install the application itself, so click on the Applications tab to see a list of all applications that are either installed on the device already, or which can be installed. Find the entry labeled Hello and click on its Install button, which will change to read Remove once the application is installed.

After all that, we can finally run our application by finding its icon on the device and tapping on it. You should see the message Hello iOS!, which I admit may seem like something of an anticlimax after going through such a drawn-out process.

Installing on BlackBerry QNX devices

Marmalade can also deploy to BlackBerry QNX devices, the best known of which is the PlayBook tablet. In order to deploy to PlayBook, we need to do some setup work first. In the steps that follow, there are some commandlines that need to be entered. In these commandlines there are some arguments enclosed in angled brackets. After each set of commands, there is a table explaining what to replace the angle-bracketed arguments with.

  1. First head over to the following URL to download the BlackBerry Native SDK, which contains some tools needed for signing builds:

  2. Run the installer by right-clicking on its icon in Windows Explorer and selecting the Run as Administrator option to avoid permission problems when installing the SDK.

  3. After the installation is complete, head over to the following URL to request some signing keys:

  4. We need to request a Device Code Signing Key, so select the first radio button to request this key type and then enter the personal information requested (your name, company name, and so on). You will also be asked to enter a PIN value consisting of eight alphanumeric characters. Ensure that you remember what you enter at this stage because you will need it to complete the registration of the keys.

  5. Make sure the checkbox labeled For BlackBerry PlayBook OS and BlackBerry 10 and Higher is checked before ticking the license agreement checkbox and clicking on the Submit button.

  6. The key files will be e-mailed to you, but there can be a delay of a few hours before they arrive. When you have the key files, create an empty folder on your PC and save them into it. We'll be assuming a folder called C:\PlayBook for the following steps.

  7. Open a command-prompt window and change the current directory to be the one you created in step 6, and enter the following commands. The first command sets up the PATH environment variable so that the other commands can be executed. These commands register your key files with the BlackBerry signing servers and allow your PC to generate debug tokens:

    C:\PlayBook> C:\bbndk-2.0.1\bbndk-env.bat
    C:\PlayBook> blackberry-keytool -genkeypair -keystore sigtool.p12 -storepass <password> -dname "cn=<company name>" -alias author
    C:\PlayBook> blackberry-signer -csksetup -cskpass <password>
    C:\PlayBook> blackberry-signer -register -csjpin <pin> -cskpass <password> <RDK file>
    C:\PlayBook> blackberry-debugtokenrequest.bat -register -cskpass <password> -csjpin <pin> <PBDT file>


    Value to enter

    <company name>

    The company name you specified when requesting the key files in step 4.


    A password of your choosing. Use the same value in each command.

    <PBDT file>

    The filename of the PBDT key file that was e-mailed to you in step 6. This filename should be of the form client-PBDT-1234567.csj, where the numeric part will be unique to your key file.


    The PIN value you specified when requesting the key files in step 4.

    <RDK file>

    The filename of the RDK key file that was e-mailed to you in step 6. This filename should be of the form client-RDK-1234567.csj, where the numeric part will be unique to your key file.

  8. We can now generate a debug token file with the following commandline:

    C:\PlayBook> blackberry-debugtokenrequest -cskpass <password> -keystore sigtool.p12 -storepass <password> -deviceId 0x<device id>


    Value to enter

    <device id>

    The device ID of your BlackBerry device. As an example, you can find out this value on a PlayBook by going into the settings screen, clicking on the About item in the left-hand pane, and selecting the Hardware option in the drop-down box. The value labeled PIN is the device ID. When you specify this value in the commandline, make sure you prefix it with 0x, as you would in C++ source code, to indicate a hexadecimal value.


    This is the same password you used in the previous set of commands.

  9. To install the debug token on to the device, first ensure that the device is connected via WiFi to the same network as your PC and then look at the device settings to determine the IP address assigned to it. This can be found by going to the About panel and selecting Network in the drop-down box.

  10. Next we must enable development mode on the device, which can be done in the settings screen. Choose the Security panel and then click on the Development Mode entry on that screen. Set the toggle control next to Use Development Mode to On. You will be asked to enter a password for using development mode, so enter one into the edit boxes and click on the Upload Debug Token button.

  11. Now we have to enter one more commandline to install the debug token on the device.

    C:\PlayBook> blackberry-deploy -installDebugToken -device <ip address> -password <device password>


    Value to Enter

    <device password>

    The device password you set in step 10.

    <ip address>

    The IP address of the device as discovered in step 9.

  12. Now we have to add the following two lines to the deployments sections of the MKB file, to allow us to make a valid deployment package:

    playbook-author="<company name>"
    playbook-authorid="<author id>"


    Value to Enter

    <company name>

    The company name value you specified when requesting the key files in step 4.

    <author id>

    Finding the value for this is a little convoluted. First make a copy of the file generated in step 8, renaming it with the extension .zip. You can now use an archiving program to look inside this file. Enter the META_INF directory and extract the MANIFEST.MF file. Open this file in a text editor and look for an entry called Package-Author-Id. The string of characters following this entry is the value you need to put in the MKB file.

  13. If Visual C++ is open, shut it down. Double-click the project MKB file to rebuild it with the changes made previously and start up Visual C++. Perform a GCC (ARM) Release build of the project and then press F5 to launch the deployment tool.

  14. In the deployment tool, change the settings to create a BlackBerry QNX deployment. When you reach the page labeled Deployment Summary, change the drop-down box to the Package and Install option before clicking the Deploy All button.

  15. The final page in the deployment tool will be displayed, which for BlackBerry deployments has two additional fields. The first is labeled Device hostname (or IP address) for which you should supply the IP address of the device that you want to install the package to. The other field is labeled Device password, and you should enter the password you set up in step 10. Click on the Deploy All button again and the deployment will be made and installed to the device over WiFi.

The build should now be installed on the device, so breathe a sigh of relief and then look for its icon in the applications list. Touch the icon to run the program, and you should be greeted with the merry little message Hello BlackBerry!

Installing on Bada devices

Installing a build on to a Bada device is one example where using the Package, Install and Run option in Marmalade System Deployment Tool is actually a very good idea, as it is not possible to copy the package to a Bada device manually to install it.

To begin with, you need to install some device drivers for your Bada device so that the deployment tool can connect to it. Marmalade does ship with some drivers for Bada, but working out which of the three possible drivers matches your device can be hard to work out. For this reason, it is better to first install the Samsung Kies utility, which comes with a number of drivers and will install the correct one for you automatically. You can download Kies from the following web address:

After installing Kies, connect your device to your computer with a USB cable and run the deployment tool. When you get to the platform selection page, you will see that there are four possible options for Bada. You must select the correct one for your device, which is based on both the version of Bada your device has and also its screen resolution.

Having chosen the correct Bada platform option, click on the Next Stage > button and then choose Package, Install and Run in the drop-down box at the top of the window. Click on the Deploy All button and an install package will be made, which is installed on to your device and executed, and you should then see the Hello Bada! message in all its monochrome glory!



The "Hello World" project may have been very simple, but it has served to demonstrate a surprising amount of the power of Marmalade. We now know how to create a new Marmalade project, build it, and create and apply our own application-specific settings to it.

We then ran our project in the Windows simulator and learned how to deploy and run it on a number of different mobile platforms.

Displaying some text on the screen isn't the most exciting thing in the world though, so in the next chapter we will learn how we can use the Marmalade SDK to draw simple 2D images on the screen. We'll also be finding out how Marmalade makes it easy for us to use bitmapped images.

About the Author

  • Sean Scaplehorn

    Sean Scaplehorn is a programmer with 15 years of experience in the videogames industry, who has worked on projects for both console and mobile devices. He has worked on games published by companies including Sony, Electronic Arts, Konami, Square Enix, and Namco. Sean got his first home computer while still at primary school, which kick-started his interest in programming. After learning to code from typing in listings printed in computer magazines, he went on to write his own games and shared them with his school friends. He knew then that writing games was what he wanted to do when he grew up. However, on leaving university, Sean spent a couple of years writing software for printing check books. When he could stand it no longer, he made the leap into videogames development and hasn't looked back since. He worked at Ideaworks3D, the company behind the Marmalade SDK, for four years. In this time he saw the Marmalade SDK evolve from an in-house technology to being a product in its own right, when it was launched as the Airplay SDK. Sean now works from his home in the South of England as a freelance game coder.

    Browse publications by this author

Latest Reviews

(1 reviews total)
Marmalade SDK Mobile Game Development Essentials
Unlock this book and the full library FREE for 7 days
Start now