• Introduction
  • Dev Environment Setup
  • Developing Apps
  • Data Handling
  • Device Capabilities
  • Testing & Debugging
  • Extending

Build time configuration

Build time settings are dictated by a file in your app directory called build.yml. By default, this file has the most commonly used settings and some defaults that will work fine for most platforms. However, you may need to modify it at certain points. For example, if you need to build for an iOS device, you’ll need to change the iphone: sdk: section to use an iphoneos SDK instead of an iphonesimulator SDK. Other special requirements apply to building for Android. Please refer to the Android-specific Settings section for more information.

This doc will provide guidelines and examples for modifying the build.yml file without jeopardizing your app.

Default build.yml Settings

When you create your app, a default version of the build.yml file will be generated and it will look like this:

#sdk: "/path/to/rhodes_gem"
sdkversion: 5.0.0
name: My RhoMobile App
version: 1.0
vendor: rhomobile
build: debug
applog: rholog.txt
iphone:
  configuration: Release
  sdk: iphonesimulator7.0
  provisionprofile:
  codesignidentity: iPhone Developer
  entitlements: ""
  BundleIdentifier: com.rhoappbuildersinc.myrhodesapp
  BundleURLScheme: buildymltest
  ApplicationQueriesSchemes: 
wp8:
  productid: '4ff21ee0-8ef1-0132-ec69-7831c1c374dc'
android:
  manifest_template: 'AndroidManifest.erb'
  version: 2.3.3
wm:
  #sdk: "MC3000c50b (ARMV4I)"
  #sdk: "Windows Mobile 6.5.3 Professional DTK (ARMV4I)"

extensions: ["rhoconnect-client"]

Settings Details

Group\\Setting Description Possible Values Example
sdk Path to your rhodes gem. This is commented out by default to let rhodes determine the latest gem and use that. If you have multiple rhodes gems and you wish to use one that is not the latest one, specify that here. String "/path/to/rhodes_gem"
sdkversion The version of your Rhodes gem. Rhodes Version 5.0.25
name The name of your app. String My RhoMobile App
version The version of your app. App Version 1.0.5
vendor The name that will be set as the vendor of your app. Usually this will be your Company's name. String RhoApp Builders, Inc.
build Build configuration of this version of your app. Debug
development
release
development
applog Name of app log file on the device. Log file name /path/to/log_file.txt
iphone\\configuration Build configuration to pass to XCode. Debug
Distribution
Release
Distribution
iphone\\sdk The version of the sdk used to build. Typically, iphonesimulatorX.X or iphoneosX.X. iPhone SDK Version, or "latest" iphoneos8.0
iphone\\provisionprofile The UUID of your provisioning profile to use when signing. UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
iphone\\codesignidentity The name of the code signing identity to use when signing for device. Code Sign Identity, String rhoAppDevIdentity
iphone\\entitlements Property list file for entitlements for your build. Typically, Entitlements.plist. .plist file myAppEntitlements.plist
iphone\\BundleIdentifier Bundle identifier – used in provisioning profile. String com.rhoappbuildersinc.myrhodesapp
iphone\\BundleURLScheme Bundle URL scheme of your app (used for opening your application from another application by using custom URL scheme). String My Rhodes App
iphone\\ApplicationQueriesSchemes Whitelist of URL schemes that can be used by your app to provide a service, pass data or launch another app. URL schemes specified here are added during build to the LSApplicationQueriesSchemes key in the app's info.plist. For more information, refer to the iOS 9-specific Settings section, below. Array of strings ["http", "sms", "tel", "facetime"]
iphone\\emulatortarget Target emulator to launch the app. Can use default iPhone and iPad emulators, or already existing emulator by its UUID. iphone
ipad
UUID
iphone
wp8\\productid A productid GUID to application build.yml. GUID '17d460b0-701f-0131-ea62-482a14303cd5'
android\\Manifest Template It is possible to specify manifest erb template file at build.yml. Manifest Template File manifest_template: 'AndroidManifest.erb'
android\\version The version of Android for which you will be building. Android version 2.3.3
extensions Comma-separated list of extensions your app will be using. Comma-separated list ["rhoconnect-client"]

Other Build-time Settings

The following are some non-default settings that you may add to the build.yml in certain circumstances.

Group\\Setting Description Possible Values Example
Android Title If you want your app to hide the default Android title bar, you need to set android_title to '0' in your build.yml file. 0 - Hidden1 - Visible android_title: 0
JS API Bridge This option is typically only used for debugging purposes. If your AJAX-based app is not working properly, you can set this to true. If your application code resides on a remote server (as opposed to running locally), the Rhomobile Javascript APIs will not be available when this settings = true. true - Enabledfalse - Disabled ajax_api_bridge: true
JavaScript and CSS Obfuscation To enable JavaScript and/or CSS code obfuscation of the files in the public folder of your app, just add the following lines to the build.yml:
obfuscate:
  js: yes
  css: yes
  exclude_dirs: ["jqmobile", "jqtouch", "jquery"]
Add to exclude_dirs all javascript libraries that are obfuscated already.
If JavaScript or CSS code obfuscation is not required, then just omit js or css line accordingly. obfuscate:
  js: yes
  css: yes
JavaScript and CSS Minification To enable JavaScript and/or CSS code minification of the files in the public folder of your app, just add the following lines to the build.yml:
minify:
  js: true
  css: true
  exclude_dirs: ["jqmobile", "jqtouch", "jquery"]
Add to exclude_dirs all javascript libraries that are minimized already.
If JavaScript or CSS code minification is not wanted, then just omit js or css line accordingly. minify:
  js: false
  css: false
Building for Intel-Based Processors on Android By default, the build process will build only for ARM-based processors but, Rhodes can be configured to build for Intel-based processors instead. To build for such a device, you must set a flag in your build.yml file. You can also elect to build for both arm AND Intel-based processor by specifying abis: [arm, x86]. x86 - Build for Intel Processors
arm - Build for arm-based processors
android:
  abis: [x86]
Production iOS To build iOS for production, there are a few settings that need to be added to your build.yml file in order to allow Rhodes correctly configure the build. You'll need to add the mobileprovision file, the certificate_file, and the certificate_password in a production sub-heading in the iphone section of the build.yml as shown below.
iphone:
...
  production:
    mobileprovision_file: "./production/PROVISION.mobileprovision"
    certificate_file: "./production/CERTS.p12"
    certificate_password: "PASSWORD"
you'll need to add your custom information into the appropriate fields here. mobileprovision_file: "./production/PROVISION.mobileprovision"
certificate_file: "./production/CERTS.p12"
certificate_password: "PASSWORD"

Capabilities

There are two ways of modifying your app’s capabilities:

  • Direct Edit - Just open the file and edit it.
  • RhoStudio Modification - The RhoStudio IDE provides a GUI for modifying the capabilities using check-boxes.

Direct edit

You can easily change specific settings in your build.yml file by simply opening it in you favorite text editor and modifying the text.

To enable specific device capabilities, edit your application’s build.yml as follows:

capabilities:
  - camera
  - gps
android:
  capabilities:
    - network_state

Rhodes support common plus platform-specific capabilities. They are merged into a single list at build time.

Note: Only Android currently recognizes these platform-specific configuration options. Enabling these options across other platforms is planned for a future release.

List of supported capabilities:

  • audio allows use of audio hardware (record audio, modify audio settings)
  • camera allows use of hardware camera
  • gps allows use of geo location service
  • network_state allows read device network state (connected/disconnected)
  • phone allow make calls/read phone state
  • pim allow read/modify personal information and contacts
  • push allows use of PUSH on device
  • record_audio allows the recording of audio (‘audio’ implies it)
  • vibrate allows use of hardware vibration mechanism
  • bluetooth allows use of bluetooth hardware
  • calendar allows access to default device calendar
  • sdcard allows writing to the SD card on Android devices

Windows Mobile/CE-specific Settings

You can specify where the config.xml file will reside on your device using the config: option.

wm:
  rhoelements:
    config: "/Config/Config.xml"
  • config : path to the custom Config.xml file to use. This path is relative to the RhoMobile Project.

iOS 9-specific Settings

Beginning with iOS 9, Apple now requires that apps declare in advance which URL schemes they would like to access when using the ‘canOpenURL’ method. According to Apple, this improves privacy by preventing an app from scanning a list of ‘known’ URL schemes on a device in an attempt to compile a list of installed apps. The change is intended to apply only to the ‘canOpenURL’ method, but the ‘openURL’ method also might generate a “This app is not allowed to query for scheme [scheme]” syslog entry. To change a URL scheme whitelist, an update must be submitted to Apple.

URL schemes can be used by an app to provide a service, pass data or launch another app. URL schemes specified as below are added during build to the LSApplicationQueriesSchemes key in the app’s info.plist parameter list. To specify a whitelist of URL schemes, add a line like the following to the ‘iphone’ section of your app’s build.yml:

iphone:
    ...
    ApplicationQueriesSchemes:["http", "sms", "tel", "facetime"]
    ...

Android-specific Settings

The capabilities listed above are directly related to the Android device capabilities that your app will require, and for which the user will be asked to give permission when installing the app. You can add capabilities to your Android app by adding a ‘capabilities’ section to your build.yml in the ‘android’ heading as below.

To work around build issues related to Android-M, we recommend adding 'version: 4.1.0' in the 'android:' section, as below.
android:
    capabilities:
      - hardware_acceleration
    mapping: yes
    extensions:
      - gmaps
    version: "4.1.0"
  • hardware_acceleration enables video playback and other resource-intensive apps
  • mapping enables the use of mapping apps
  • gmaps extension enables the use of Google maps for mapping

In RhoStudio, you can double-click on your application’s build.yml and edit from the text editor, or edit it directly using a text editor of your choosing.

RhoMobile 5.2.2 will build successfully with Android versions up to and including Android 5.1 (Android L). For Android builds, please install an Android SDK with API level 22 or lower. For information about Android API levels, please visit the Android API documentation.

The Android SDK allows you to programatically specify an application’s compatibility with one or more versions of the Android platform using an API-Level integer. The API Level can be specified in the AndroidManifest.erb, which must then be specified in the build.yml (see sample, below). Android versions specified here will be compared to that of a given Android target device.

The syntax for the Android <uses-sdk> parameter:

<uses-sdk android:minSdkVersion="integer"
      android:targetSdkVersion="integer"
      android:maxSdkVersion="integer" />

For more information about this parameter, please visit the Android uses-sdk page.

Android Keycode Mapping

Keycodes are constants that uniquely identify the ASCII values of device keypresses (hard or soft). On Android devices, the keycode values of certain keys are sometimes not returned as expected or desired. To ensure control and accuracy of key presses, RhoMobile apps for Android can have some or all of their default keycode values assigned from a file when the app starts up. Keycode value(s) can be assigned through the current KeyCapture 4.x API as well as legacy 2.x versions. The steps below apply to all API versions.

This section applies to Android only.

The following facts apply generally to keycode mapping:

  • Keycode mapping requires RhoMobile Suite 5.4 or higher.
  • Mapping requires a KeyCapture API. Read more.
  • Keycode mappings are contained in the keycodemapping.xml file.
  • The keycodemapping.xml file is the same for all versions of the KeyCapture API.
  • The mapping file is read each time the RhoMobile app is launched.
  • Upon app install, a mapping-file template is placed in the app’s installation directory, usually sdcard0/android/data/com.rhomobile.appName.
  • Keycodes not mapped (or left blank in the mapping file) retain their default values.
  • Additional restrictions apply to keycapture and keycode mapping.

Mapping Keycodes

To assign custom keycodes to Android hard or soft keys, follow these simple steps:

1. Deploy the app to the device.

2. Navigate to the installation directory on the device. This is usually sdcard0/android/data/com.rhomobile.appName

3. Copy the keycodemapping.xml template to a PC and open it for editing.

The template should look similar to the image below:

<?xml version = "1.0"?>
<!--
.....KeyCode Mapping File....
-->
<KeyCodeConfiguration>

    <KeyCodes>

        <!-- Example -->
        <!-- <KEYCODE  name="KEYCODE_0" from="7" to="0x30" /> -->

    </KeyCodes>

</KeyCodeConfiguration>

4. Copy and paste the example KEYCODE tag (omitting the comment tags) as shown:

...
<KeyCodes>

    <!-- Example -->
    <!-- <KEYCODE  name="KEYCODE_0" from="7" to="0x30" /> -->

    <KEYCODE  name="KEYCODE_0" from="7" to="0x30" />

</KeyCodes>
...

5. Replace the values (within the quotes) for ‘name,’ ‘from’ and ‘to’ fields, as required.

Note: The ‘from’ field refers to the key’s current keycode value; the ‘to’ will hold the value that replaces it. In the example above, pressing the ‘0’ key (after mapping) will generate a keycode value of ‘0x30’ instead of its former value of ‘7.’ The ‘name’ field can hold any value; standard Android key names are recommended.

For help exposing keycodes, see Handling Incorrect Keycodes section below.

6. Repeat steps 4 and 5 until all required keycodes are mapped.

For example:

        <?xml version = "1.0"?>
    <!--
    .....KeyCode Mapping File....
    -->
    <KeyCodeConfiguration>
        <KeyCodes>
            <!-- Example -->
            <!-- <KEYCODE  name="KEYCODE_0" from="7" to="0x30" /> -->
            <KEYCODE  name="KEYCODE_F1" from="131" to="20" />
            <KEYCODE  name="KEYCODE_ENTER" from="46" to="76" />
            <KEYCODE  name="KEYCODE_E" from="33" to="7" />
            <KEYCODE  name="KEYCODE_BACK" from="4" to="32" /> 
            <KEYCODE  name="KEYCODE_VOLUME_DOWN" from="25" to="175" /> 
        </KeyCodes>
    </KeyCodeConfiguration>

7. Copy the modified keycodemapping.xml file to its original location on the device, replacing the template.

8. Relaunch the app and check that its keycodes are mapped as specified.

Handling Incorrect Keycodes

Once it is determined that correct keypresses are generating incorrect keycodes, the incorrect keycode value must be determined before the correct one can be substituted. This process uses JavaScript to expose the keycodes that appear when pressing one or more keys.

The first step is to confirm that Windows keycodes are not being forced as a result of the <isWindowsKey> tag:

1. In the app’s Config.xml file, confirm that the <isWindowsKey> tag has a value of 0.

2. Using one of the KeyCapture APIs, reveal the keycodes generated by keypresses to identify incorrect keycode value(s). The test code might look something like this:

        // KeyCapture API 4.x: 
    EB.KeyCapture.captureKey(false,'all',function(obj){alert(obj.keyValue)
    });

    // KeyCapture API 2.x: 
    <META HTTP-Equiv="KeyCapture" Content="KeyValue:All; Dispatch:False; KeyEvent:url('JavaScript:alert('Key Pressed: %s');')"> 

3. Map the incorrect keycode values to the correct ones using the same syntax described in the earlier section:

<KEYCODE  name="[KEYCODE_X]" from="[incorrect_keycode]" to="[correct_keycode]" />

For example, if Step 2 determined that the keycode value being generated is 0x05 and the desired value is 0x06, then the correct mapping statement would be:

<KEYCODE  name="KEYCODE_X" from="0x05" to="0x06" />

where “KEYCODE_X” = the desired keycode name. Standard Android key names are recommended.

4. Relaunch the app and repeat Step 2 to confirm that correct code(s) are generated.

More Information

RhoStudio Modification

You can also edit the capabilities that your app will have access to through RhoStudio. To do this, double click your build.yml in your app’s project in the project explorer pane in RhoStudio.

img

Once you have done this, you should see the following screen wherein you can modify your build.yml settings, mainly, the capabilities.

img

Click the add button next to the capabilities field to bring up this window and add capabilities by clicking the corresponding check-box.

imgimg

You’ll notice that as you add capabilities to your app, the build.yml text file will change to reflect these added capabilities.

img

RhoGallery Security Token

To restrict access to the application you may have it built with a security token. Specify the security token in the build.yml and build the app. Apps built with a security token can be started in normal mode only if you provide this token as a parameter. If you do not specify the correct security token in the start params, the app will close on start by default. If you want do something instead of exit (for example show special message or run application in limited mode etc.) you can define another start_path for your application in “rhoconfig.txt”:

invalid_security_token_start_path = '/app/InvalidSecurityTokenStartPage'

Specify security token in build.yml:

security_token: 123

Run application with special parameter:

System::run_app( 'app_name', "security_token=123" )

Rhobuild.yml Configuration

After installing the RhoMobile Suite, you must tell the software where you have certain files on your machine. To do this, a file called rhobuild.yml is built that contains those file locations and other settings. The default version of the file is shown below:

env:
  paths:
    java: "C:/Program Files/Java/jdk1.6.0_11/bin"
    android: "C:/Android/sdk"
    android-ndk: "C:/Android/ndk"
    cabwiz: "C:/Program Files (x86)/Windows Mobile 6 SDK/Tools/CabWiz"
    msbuild: "C:/Windows/Microsoft.NET/Framework/v4.0.30319/MSBuild.exe"
    vcbuild: "C:/Program Files (x86)/Microsoft Visual Studio 9.0/VC/vcpackages/vcbuild.exe"
build:
  wmpath: "platform/wm"
  wp8path: "platform/wp8"
  androidpath: "platform/android"
  iphonepath: "platform/iphone"
android:
excludedirs:
  all:
# Google API key obtained from http://code.google.com/intl/en/android/add-ons/google-apis/mapkey.html
#apikey: "GOOGLE-API-KEY-FOR-ANDROID"
# This is version of Android platform used to run emulator. If not specified, latest available will be used.
#version: 1.6
# This enable/disable native geo mapping for Android. Disabled by default
#mapping: yes
# Here data for production certificate located. If file pointed by certificate: does not exist, it will be auto-generated
#production:
#  certificate: /path/to/developer/certificate
#  password: "password-for-certificate"
#  alias: "certificate-alias"
  - "**/.*.swo"
  - "**/.*.swn"
  - "**/.DS_Store"

Rhobuild.yml Properties

  • env - Environment settings.
    • paths - Paths to necessary build tools.
      • java - The path to your Java’s binary folder.
      • android - The path to your Android SDK.
      • android-ndk - The path to your Android NDK.
      • cabwiz - The path to your Windows Mobile 6 cabwiz file.
      • msbuild - The path to MSBuild.exe.
      • vcbuild - The path to vcbuild.exe.
    • build - This is where the binaries will be stored once they are built for each specified platform.
      • wmpath - Windows Mobile .cab file path.
      • wp8path - Windows Phone 8 executable file path.
      • androidpath - Android .apk file path.
      • iphonepath - iOS .ipa file path.
    • android - Settings specific to Android builds.
    • excludedirs - Directories to exclude from the build.
    • apikey - Google API key.
    • version - The version of the Android platform to run in the emulator. If not specified, latest will be used.
    • mapping - This enable/disable native geo mapping for Android. Disabled by default.
    • production - Settings used in production builds.
      • certificates - The path to your developer certificate.
      • password* - Your developer certificate password.
      • alias - Your certificate alias.

Modifying rhobuild.yml settings

To modify these settings, there are two methods:

  1. Modify these settings in the properties of RhoStudio.
  2. Modify the rhobuild.yml file directly.
    • On Mac OS X, the file resides in \rhodes\<version>
    • On Windows, the file resides in \RhoMobileSuite
Back to Top