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.
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!
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:
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.
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.
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.
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.
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.
Note
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.
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.
Note
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.
Let's start by looking at how to install an Android build.
Note
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:
http://www.oracle.com/technetwork/java/javase/downloads/index.html
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.
Note
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.
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:
https://developer.apple.com/programs/which-program/
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:
Launch the Marmalade iPhone Sign Request Tool and fill in the fields as follows:
Certificate Request File: Pick a location where this file will be saved. You will need to upload this to the iOS Dev Center shortly.
Key File: Choose developer_identity.key from the drop-down box.
Common Name: The name you used when registering with the iOS Developer Program.
Email Address: The e-mail address you used when registering with the iOS Developer Program.
Now log on to the iOS Dev Center and click on the iOS Provisioning Portal link.
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.
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\certificatesof your Marmalade SDK installation.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.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.
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. Thedomainnamepart can be pretty much anything you like (it doesn't necessarily have to relate to a real URL), while theappnamepart 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.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.
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:
http://support.apple.com/kb/DL1466
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.
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.
First head over to the following URL to download the BlackBerry Native SDK, which contains some tools needed for signing builds:
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.
After the installation is complete, head over to the following URL to request some signing keys:
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.
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.
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:\PlayBookfor the following steps.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
PATHenvironment 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>
Argument
Value to enter
<company name>The company name you specified when requesting the key files in step 4.
<password>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.<pin>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.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> debugtoken.bar
Argument
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.<password>This is the same password you used in the previous set of commands.
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.
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.
Now we have to enter one more commandline to install the debug token on the device.
C:\PlayBook> blackberry-deploy -installDebugToken debugtoken.bar -device <ip address> -password <device password>
Argument
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.
Now we have to add the following two lines to the
deploymentssections of the MKB file, to allow us to make a valid deployment package:playbook-author="<company name>" playbook-authorid="<author id>"
Argument
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
debugtoken.barfile generated in step 8, renaming it with the extension.zip. You can now use an archiving program to look inside this file. Enter theMETA_INFdirectory and extract theMANIFEST.MFfile. Open this file in a text editor and look for an entry calledPackage-Author-Id. The string of characters following this entry is the value you need to put in the MKB file.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.
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.
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 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:
http://www.samsung.com/uk/support/usefulsoftware/KIES/JSP
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!