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. This doc will provide guidelines and examples of how to modify this file without jeopardizing your app.

• Default build.yml Settings
• Other Build-time Settings
• Capabilities
• RhoGallery Security Token
• Rhobuild.yml Configuration

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
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

Other Build-time Settings

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

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: Right now only Android recognizes these platform specific configuration options. However, we are planning to enable these options across all platforms.

List of supported capabilities:

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

Windows Mobile / Windows 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.

Android Specific Settings

The capabilities listed above are directly related to the Android device capabilities that your app will require and that the user will be asked to give permission to 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 such:

android:
    capabilities:
      - hardware_acceleration
    mapping: yes
    extensions:
      - gmaps

• hardware_acceleration: enables the hardware_acceleration capability for Android applications
• 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; otherwise, you can edit build.yml directly.

Note: Some versions of Android require hardware acceleration to play embedded video.

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.

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

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

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

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, we generate a bunch of default setting in a file called rhobuild.yml. Below is the default appearance of that file:

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, the file resides in the rhodes- directory.
   • on Windows, the file resides in the RhoMobileSuite directory