build.txt

# Build Rhodes Application

This page describes how to build Rhodes Application on all of our supported platforms: iPhone, RIM Blackberry, Windows Mobile and Android.

## All Platforms Prerequisites 

### Required Software

For Windows use [Instant Rhodes](install#install-on-windows). On Mac, Linux, and Windows (if you didn't use Instant Rhodes) make sure you have following software installed:

* Ruby 1.8.6 or 1.8.7. Load it from [here](http://www.ruby-lang.org/en/downloads/).
* RubyGems v1.3.7 or higher. Load it from [here](http://rubygems.org/).
* GNU make 3.80 or higher (required by gem). Probably you already have it installed if you are running Mac OS X or Linux. On Windows, download it from [here](http://gnuwin32.sourceforge.net/packages/make.htm) and install it somewhere on your system. Ensure you have location where it installed in your PATH environment variable.
* Rhodes gem. Run `[sudo] gem install rhodes` to install the latest rhodes gem.
**NOTE: If you get any "no such file to load -- something" messages while running the rake tasks or rhogen commands, this can usually be resolved by running '[sudo] gem install something'. **

For Windows setup HOME environment variable:

	C:\Documents and Settings\<account_name>

If you are planning to build for Blackberry or Android, make sure you have JDK version 1.6.0_2 or higher installed. Recommended version 6.0 update 11.

* Version 1.6.0_24 for Mac OSX 10.6 available [here](http://support.apple.com/downloads/DL1360/en_US/JavaForMacOSX10.6Update4.dmg). Install it and then run "Java Preferences" utility to change default version.
* Sun JDK for Windows or Linux is available [here](http://java.sun.com/javase/downloads/index.jsp). The 32-bit Windows version is required for Blackberry tools. 

Make sure you set JAVA_HOME and that JAVA_HOME/bin is on your path.

## Setup Rhodes Source Code

If you planning to modify or [extend](extensions) Rhodes, you will need Rhodes source code. It is distributed under MIT license and it is perfectly all right for you to hack it if you want to. But you don't need it otherwise, having Rhodes gem installed is enough.

Rhodes source code is available on github.com and you will need Git to get it from there. If you used [Instant Rhodes](install#install-on-windows) you probably already have it installed on your system. Otherwise, load it from [here](http://git-scm.com).

To clone Rhodes, execute following from the command line:
	
	:::term
	$ git clone git://github.com/rhomobile/rhodes.git
	$ cd rhodes

Checkout the branch you are interested in (if not master):

	:::term
	$ git checkout -f -b <branchname> --track origin/<branchname>

Make sure you're up-to-date on the branch:

	:::term
	$ git pull

Add the bin folder to your path. On Linux/Mac it is typically done via the .profile. On windows it is done via the system control panel.

Configure your environment by running the rhodes-setup script. This will attempt to auto-detect installed SDK's and will prompt you to verify them or enter ones that cannot be detected.

	:::term
	$ rhodes-setup

### Build rhodes gem from source

You don't have to do it if you cloned sources, but if you want to build rhodes gem then do following:

	:::term
	$ git clone git://github.com/rhomobile/rhodes.git
  	$ cd rhodes
  	$ rake gem
  	$ gem install rhodes-[version].gem

### Build from Rhodes sources directly without gem

To build your application from Rhodes source code just set sdk: property in the build.yml (it is in the root folder of your app) to the Rhodes source code root folder.

## Build for iPhone/iPad

iPhone/iPad versions of Rhodes Apps have to be built on Mac machines or could be build on [rhohub.com](http://rhohub.com). The instructions below describe how to do this from either the XCode development environment or from the command line on your local Mac. 

### Prerequisites

To build for iPhone/iPad you will need following software installed:

* Mac OS X 10.5 (Leopard) or greater (Snow Leopard)
* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* iPhone SDK. We recommend the latest stable version available from the [iPhone Dev Center](http://developer.apple.com/iphone/index.action)

### Build Application with XCode

To build for iPhone/iPad follow these steps:

Note the 'sdk:' value in your build.yml.  You will use this in the next step.

Inside the <sdk directory from previous step>/platform/iphone directory is an iPhone XCode project, double-click on it to open XCode.

Open up a command window and switch to your application's directory. Run: 
	
	:::term
	$ rake switch_app
	
This changes your rhobuild.yml in the SDK folder to point to your application.

Prepare XCode rrhorunner.xcodeproj and other files for current application :

	:::term
  	rake build:iphone:setup_xcode_project

Restore original XCode rrhorunner.xcodeproj and other files :

	:::term
  	rake build:iphone:restore_xcode_project

After you change application code just run 'Build and Go' command in XCode to build for the simulator.

If you want to build for the device, open the 'rhorunner' target and select your code signing information that you installed from the apple developer site and change your active sdk to a device.

* Tip: after you make changes and want to see them reflected on the device, reset the simulator and repeat #2.
* Tip: to see a log of what is happening on the device, type command-shift-r in xcode to bring up the rhorunner console.

Result application package (*.app) located in <sdk directory>/platform/iphone/build/[Debug/Release]-[iphoneos/iphonesimulator]/rhorunner.app

### Build and Release on App Store

Once you have the application building with XCode as described above, it is treated as any other iPhone application when it comes to [signing and distributing to the app store](http://developer.apple.com/iphone/appstore/). 

### Build Application from Command Line

Unlike building the application from the XCode GUI, you build the application from command line via the rake command inside the directory of the app you had just generated with rhogen.

Change directory to your rhodes application.

Look at the contents of build.yml and verify the following setting `applog`. Do not enter full path here, this file will be in your app directory:

	applog: rholog.txt

Run:
  
	:::term
	$ rake run:iphone

Modify your application code. Exit application in simulator and run:

	:::term
  	$ rake run:iphone

### Build application for device

Modify build.yml:

	iphone:
		sdk: iphoneos4.2
		configuration: Release
		codesignidentity: "iPhone Developer"
		entitlements: ""

Run:

	:::term
  	rake device:iphone:production

Result package named <b>your application name.app</b> will be placed to `<your application folder>/bin/target/iOS/[sdkname]/[configuration]/[your application name].app` if you using Rhodes from 2.2.4 version.

Result package named <b>rhorunner.app</b> will be placed to `<sdk directory>/platform/iphone/build/[Debug/Release/Distribution]-[iphoneos/iphonesimulator]/rhorunner.app` if you using Rhodes before 2.2.4 version.

### Install Application to device
Use <b>iTunes</b> for install you application package (your application name.app) to device:
 
* open iTunes
* select <b>Apps</b>, drag your application package and drop it to Apps screen
* connect your device to iTunes
* select you device in iTunes
* select <b>Apps</b> tab in your device screen
* check your application for install to device
* do Sync for install your application to device

### build.yml settings

The build.yml settings for iphone are the following:

	name: myapp
	version: 1.0
	iphone: 
	  provisionprofile: 
	  sdk: iphonesimulator3.0
	  entitlements: 
	  codesignidentity: 
	  configuration: Debug
	  emulator: 3.0
	  emulatortarget: iphone
	  BundleIdentifier: com.yourcompany.yourapp
	  BundleURLScheme: yourapp

* name: name of your application. Will show on screen (iPhone application bundle display name)
* version: version of your application. iPhone application bundle version
* provisionprofile: The UUID of your provisioning profile to use when signing. 
* sdk: The version of sdk used to build. Typically iphonesimulatorX.X or iphoneosX.X
* entitlements: propertylist file for entitlements for your build. Typically is Entitlements.plist
* codesignidentity: The name of the code signing identity to use when signing for device.
* configuration: Debug/Release/Distribution
* emulator: version of emulator for run application
* emulatortarget: device family for simulator (iphone/ipad)
* BundleIdentifier: bundle identifier - used in provisioning profile
* BundleURLScheme: bundle URL scheme of your app (used for open your application from another application by using of custom URL scheme)


Example of iPhone setting in build.yml of your application:

	name: JS App
	version: 1.0
	iphone: 
	  provisionprofile: E5931D39-CA68-48E4-A3AF-BB538E1C8CE6 
	  sdk: iphoneos4.2
	  codesignidentity: "iPhone Developer: John Smith (MF99RW67WY)"
	  entitlements: ""
	  configuration: Release
	  emulator: 4.2
	  emulatortarget: ipad
	  BundleIdentifier: com.johnsmithcompany.jsapp
	  BundleURLScheme: jsapp


## Build for Android

### Prerequisites

* [OS compatible with Android SDK](http://developer.android.com/sdk/requirements.html)
* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* Download the [Android SDK Starter Package](http://developer.android.com/sdk/index.html)
	* Run `<sdk>/tools/android` on OSX/Linux or `<sdk>/SDK Setup.exe` on Windows
	* Go to Settings > check `Force https://... sources to be fetched using http://` and press `Save & Apply`.
	* Go to Available > Expand `https://dl-ssl.google.com`
	* Download the latest SDK version, latest platform (SDK Platform 2.2, for example) and latest "Google APIs" available.
* Set the environment variables ANDROID_HOME to where you installed the SDK, and add `<sdk path>/tools` to PATH
* Download and install the [Android NDK](http://developer.android.com/sdk/ndk/index.html)
* Run `rhodes-setup` and tell Rhodes where you installed the Android SDK and NDK

In case if you are planning to work with native geo mapping (MapView interface), two things should be done:

* Android Maps API key should be retrieved from Google. Follow these [instructions](http://code.google.com/intl/en/android/add-ons/google-apis/mapkey.html) to get it. When key received, put it in your application's `build.yml` or share it across all your applications by adding it to `rhobuild.yml`:

	android:
	  apikey: "GOOGLE-API-KEY-FOR-ANDROID"

* Enable 'mapping' in your application's `build.yml` (or in `<rhodes-root>/rhobuild.yml`):

	android:
	  mapping: yes

If you are using Eclipse (Optional) please follow [these instructions](http://source.android.com/using-eclipse) on how to increase Java memory space to use Android.


Please check you applications and change the way how you include css files into html pages.

For example, you will need to replace 

	<style type="text/css" media="screen">
		@import "/public/js/iui/iui.css"; @import "/public/css/rho.css";
	</style>

with

	<link rel="stylesheet" href="public/js/iui/iui.css" type="text/css">
    <link rel="stylesheet" href="public/css/rho.css" type="text/css">

Otherwise your css files will not be loaded in Android 1.5 (and higher)

### Device capabilities settings in build.yml

Attention ! On Android you should specify list of device capabilities need for you application. By default there are not any capabilities enabled !
This is important because all defined capability produce special <uses-permission ... > lines in AndroidManifest.xml specific to Android platfrom. Without enabled permission application can not access to device functions.
List of capabilities related to changes in AndroidManifest - add or remove this items in "capabilities" section in your build.yml:
	audio
  	camera
  	gps
  	network_state
  	phone
  	pim
  	record_audio
  	vibrate
  	bluetooth
  	calendar
  	sdcard
  	push

### Set up minimal Andoid SDK API level

The minimal API level supported by Rhodes is 4 (Android 1.6)
It is possible to set greated minimal API level with build.yml. This will restrict installing an application on any Android OS prior to 3.0:

   android:
     minSDK: 11

### Building app and running it in emulator from the command line

** NOTE: make sure that your PATH has the path to java bin. **

From the command line, in your rhodes application directory, run:

	:::term
	$ rake run:android

It will create (if needed) new virtual sdcard for emulator, then check if emulator is already running (and start if not) and upload application there. You can specify version of emulator you are want to run in your application's build.yml:

	android:
	  version: 2.1

You can also specify emulator AVD name (see 'Android SDK and AVD Manager').

	android:
	  emulator: myDeviceEmulator20

Disable Android title in application :

	android:
	  android_title: 0

If the rake command gets stuck you can kill the command window, open another window, run:

  	:::term
	$ adb start-server
  	$ rake run:android


** NOTE: If you didn't run your Android simulator yet or don't have AVD configuration set, you will be asked a few questions about emulator configuration. You should answer "yes" for most questions or use default answers. As a result new AVD configuration will be created. **

To uninstall application from emulator, run:

	:::term
	$ rake uninstall:android

### Building app and running it on the device from the command line

If you have an Android device, you can develop and debug your Android applications just as usual. Launching your apps on a device works just the same as on the emulator, but there are a few things to do before you can start. Please check corresponding [Android documentation](http://developer.android.com/guide/developing/device.html).

You can verify that your device is connected by executing:

	:::term
	$ adb devices
	
If connected, you'll see the device name listed.

If your machine doesn't "see" the device as connected, try killing the adb process first:

	:::term
	$ adb kill-server
	$ adb install <filename>.apk

After you have your device connected, in your rhodes application directory, run:

	:::term 
	$ rake run:android:device

This will build your application and sign it with auto-generated self-signed certificate

To uninstall from the device, run:

	:::term
	$ rake uninstall:android:device

If you want to build production version, edit your application's build.yml as below:

	android:
	  production:
	    certificate: /full/path/to/your/developer/certificate
	    password: "password-of-the-certificate"
	    alias: "keystore.alias"

This will use specified certificate to sign application. If certificate is not found, it will be auto-generated. In this case you'll be prompted with several questions like your name, organization etc. If you don't want to use auto-generated certificate, refer to the [these instructions](http://developer.android.com/guide/publishing/app-signing.html) on how to create it manually.

After that run:

	:::term
	$ rake device:android:production

Signed APK will be located in `<rhodes-app-dir>/bin/target`. To install application on the device run:

	:::term
	$ adb -d install -r <rhodes-app-dir>/bin/target/<app-name>_signed.apk

### Building app in Eclipse

Please note: It is only Google API target (with Google mapping API) supported for Eclipse

Create a new workspace in the following directory: `<Rhodes>/platform/android`

Go to the Window > Preferences 

Click on Android node in the tree and specify file path to the installed Android SDK (For example: `E:\android\android-sdk-windows`)

Import all projects from the following directory: `<Rhodes>/platform/android`

If you have set the option to build sources automatically all stuff will be compiled just after the import.

Select Properties from the Rhodes project context menu and select one of latest Google API target for Android.

Check bin directory. You should see Rhodes.apk file created. It will be signed with debug key provided with SDK.

Now you are ready to install your application on device and/or emulator.

In case of troubles in Eclipse while setting up the Android SDK and target try "Rhodes project context menu" > "Android Tools" > "Fix Project Properties".

It is possible your application has stopped unexpectedly just after the first build. In this case try to copy autogenerated java source files from the application folder <app>/bin/tmp to the Rhodes project.

### Getting application log from device or emulator

To get application log from device or emulator, from your application folder or from root of rhodes source tree (place where rhobuild.yml is located), issue command:

	:::term
	$ rake device:android:getlog

Or
	:::term
	$ rake emulator:android:getlog
	
Application log will be pulled from device/emulator and stored in your application directory with name RhoLog.txt.

To see all emulator messages run 'adb logcat' and start application on emulator

To see all device messages run 'adb -d logcat' and start application on device

## Build for BlackBerry

Blackberry SDK for Mac doesn't come with simulators so far. So for now we would assume you are using Windows to develop for BB.

### Prerequisites
* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* Load and install Blackberry JDE version 4.6.0 or higher(5.0 or higher recommended for simulator usage) from [here](http://na.blackberry.com/eng/developers/)
* Read about Blackberry Browser limitations of CSS, HTML and JavaScript. Get relevant documentation from [here](http://na.blackberry.com/eng/support/docs/subcategories/?userType=21&category=BlackBerry+Browser).

### Build application using rhodes gem

Before you build edit build.yml from the application directory. Set the bbver to the target BB OS that you are building for. For example:

	bbver: 5.0

#### To build and run using Blackberry simulator 5.0 and higher
Starting from  Blackberry JDE 5.0, simulator supports loading application cod-files to simulator without restart. This feature greatly improve Blackberry development perfomance.
There are 2 possible scenarios available:

* Load application cod-file manually using Simulator menu: 'File\Load Blackberry application or theme...':
        $ rake run:bb:startsim
        $ rake package:bb:production_sim
	
    In simulator window open menu: 'File\Load Blackberry application or theme...' and choose app cod-file:'<app_folder>/bin/target/<bb_ver>/<app_name.cod>'

    After application modification:
	    $ rake package:bb:production_sim
    And reload application cod-file in simulator using menu.

* Use rake commands to reload app on simulator.

    	$ rake run:bbapp

    Start application on simulator and DO NOT close application in simulator.
    After application modification:
	    $ rake run:bbapp
    
    In case of simulator errors:
    * Try load application cod-file manually.
    * Try to uninstall application: select application icon on simulator and press Menu\Delete
    * Close simulator and run clean.bat in simulator folder 
       
#### To build and run using Blackberry simulator

Run in application root directory:

	:::term
	$ rake run:bb

Launch application from the simulator's Downloads menu item for 4.6 or from Main menu screen on 4.3 and below. Do not close Simulator manually after you have done testing. Script will restart simulator for you.

Modify your application and run run rake script again:

	:::term
	$ rake run:bb


To see application log change log settings in [rhoconfig.txt](configuration#run-time-configuration). Run your application and see log file at `<simulator folder>\sdcard\rho\<app_name>\RhoLog.txt` 

To switch log on while running your application  select menu\log\options form the application menu and set log level to Info and Message classes to APP or to *.

To clean all data (database and log) go to '<simulator folder>\sdcard` and remove rho folder. If you use Persistent Storage mode - remove app or run clean.bat in the simulator folder.

##### Some known issues while building for BB simulator

Run `rake config:checkbb` and see are any problems reported

Run rake scripts from windows console. Do not use bash or similar tools.

When emulator starts, open Blackberry Internet Browser and browse for some web site. If you are unable to browse:
  
* check that MDS is running - it should be console window started with emulator.
* open manage connection (blackberry menu button)\check Mobile Network

Check your JAVA_HOME environment variable: it should NOT contain 'bin' at the end.

Do not use 'localhost' or '127.0.0.0' for sync server address if you host sync server on your machine. Use local computer name instead.


#### To build application for the device

You have to sign application before loading it to device. Go [here](http://na.blackberry.com/eng/developers/javaappdev/codekeys.jsp) to get Code Signing Keys.

Once you have Code Signing Keys files (sigtool.csk and sigtool.db) you should put them in the 'bin' folder of your Blackberry jdk and sign your application.

If your target device is Blackberry JDK 4.3 and later, you can provide password in the rhobuild.yml file (located in the Rhodes SDK folder) in the 'build' section:
 
	build:
	  bbsignpwd: <password>

Run:

	:::term
	$ rake device:bb:production

Built application will be available at `<application_directory>/bin/target`. For example, if you rake:bb:production, the files will be in a directory named for the SDK version, like /bin/target/4.6/ota-web. You should see many .cod files and a single .jad file.

You may deploy it to the device now. To do that upload .jad and all .cod files to a web server, then open the .jad file from the browser on your blackberry device. You may use [rhohub.com](http://rhohub.com) Gallery feature to host your builds as well.

##### Some known issues while building for BB device

After you get your CSI-file from Blackberry, you have to register them. If after dbl-click you will see message "Already registered" see instructions here: 
[Incorrect password error when attempting to register signature keys](http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/800989/Support_-_Incorrect_password_error_when_attempting_to_register_signature_keys.html?nodeid=1461314&vernum=0) 

After press Yes in dialog 'Would you like to create a new key pair file' - nothing appear. No dialogs, no error messages, just nothing then this is a problem with Java SDK and Blackberry SDK versions. See more information here: 

* [The signature key window disappears after receiving the private key prompt](http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/800738/800989/Support_-_The_signature_key_window_disappears_after_receiving_the_private_key_prompt.html?nodeid=1313681&vernum=0)
* [Supported versions of Java for different BlackBerry JDE versions](http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/800738/800901/What_Is_-_Supported_versions_of_Java_for_different_BlackBerry_JDE_versions.html?nodeid=1313614&vernum=0)

If you still have a problems then [manually register CSI files](http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/800989/How_to_-_Manually_register_the_CSI_files.html?nodeid=800993&vernum=0)

Signature files can be only registered once per computer. If you register them for example in 4.6 Blackberry SDK , you can copy sigtool.csk and sigtool.db to bin directory of any other BB SDK

There is a problem with network on BlackBerry simulators under Windows 7. It causes syncing failure. There are two workarounds for this issue. One is to use MDS for network connection in simulator (build script does this automatically). The second workaround is to emulate WiFi connection in the simulator.

#### Application log on the device

The log is written to the file 'rholog.txt': 

* If your device has SD card log will place to `<Media Card>\Rho\<app name>` folder.
* If your device doesn't have SD card log will place to `<Device Memory>\home\user\rho\<app name>`.

To see or copy log file to your computer:

* Add menu item Log to your application menu
* Call `RhoConf.show_log` or `RhoConf.send_log` somewhere in your app (for example on the settings page) 
* Open Media application on the Phone, select Menu\explore. You can view log file or send it via bluetooth
* If you have SD card: Phone options\memory\Mass storage support - ON, save. Then connect device to the computer via cable and you will see USB disk drive in computer explorer. Copy `rholog.txt` to computer. 

**NOTE: Do not forget to turn 'Mass Storage support' OFF, otherwise Rhodes wouldn't be able write to the files! **

#### Connectivity on the device
If your phone has Wifi connectivity Rhodes will use it without any additional efforts. In case of GPRS, you should :

* Setup mobile network: Phone Options\Mobile Network\Data Services ON, Connection preferences: Should be not WiFi-Only.
* Setup APN address: Phone Options\Advanced settings\TCP/IP/APN settings enabled. APN should address specific for your provider (wap.cingular for example).

#### Event log from device

Read Blackberry article on [how to enable, access, and extract the event logs on a BlackBerry smartphone](http://www.blackberry.com/btsc/search.do?cmd=displayKC&docType=kc&externalId=KB05349).

Now you should be able to extract a full copy of BlackBerry smartphone event logs to a text file using loader.exe on a computer. 

Connect the BlackBerry smartphone to the computer using a USB cable.

Open the command prompt and type: 
	
	:::term
	$ cd c:\Program Files\Common Files\Research In Motion\AppLoader
	
On a 64-bit system, type: 

	:::term
	$ cd c:\Program Files (x86)\Common Files\Research In Motion\AppLoader
	
Type: 

	:::term
	$ Loader.exe /eventlog c:\log.txt 

The log.txt file is the extracted log and should appear on the `C:\` drive.

** NOTE: To obtain the Loader.exe tool, install BlackBerry® Desktop Manager 4.7 or later, or visit [http://na.blackberry.com/eng/update/](http://na.blackberry.com/eng/update/) to check for updates for the BlackBerry smartphone that will install the necessary components to your computer. **

** NOTE: On some Windows Vista™ and Windows® 7 computers, even though c:\ was specified, the Java Event logs might be saved to the following location: `c:\Users\<username>\AppData\Local\VirtualStore\Program Files\Research In Motion\BlackBerry\Apploader` **

### Build rhodes from the source code using Eclipse

* You should have Blackberry Eclipse IDE installed.
* Please make sure that there are no .metadata folder in rhodes\platform\bb folder.
* Go to `<rhodescheckout>` and run:

	    $ rake build:bb:devrhobundle
	
* Run eclipse and choose rhodes\platform\bb as a workspace directory. Do not create workspace!
* Open menu Window\Preferences
    * Blackberry java plug-in\Warnings - check all 3 chekboxes to suppress all warnings
    * Java\Compiler - set Compiler compliance level to 1.4
* Go to File\Import... menu. Select `General\Existing projects into Workspace` workspace node. Press Next. 
    * Browse for `<rhodes>\platform\bb\RubyVM`. Press Finish. The project will be automatically build.
    * Browse for `<rhodes>\platform\bb\Hsqldb`. Press Finish. The project will be automatically build.
    * Browse for `<rhodes>\platform\bb\Rhodes`. Press Finish. The project will be automatically build.
* Go to Run\Debug Configurations - double click on Blackberry simulator
    * select all projects in Projects tab
    * got to Simulator tab, select Memory, check Use PC file system for SDCard files, add `Rho` to PC file system for SDCard files edit box
    * Press Debug

Congratulations! It is all done.

#### Known issues with Eclipse build

Sometime BB Eclipse project is checked in in a wrong state and wouldn't build correctly after loading:

* You need to make sure every sub-project is activated for BlackBerry: right-click on the sub-project and select `Activate for BlackBerry` menu item.
* Check and set project dependencies correctly: select `Project/Properties...` menu and navigate to BlackBerry Project Dependencies.... Set following dependencies:
	* PersLite doesn't have any dependencies
	* PersImplJSR75 depends on PersLite
	* RhoBundle depends on RubyVM
	* RubyVM doesn't have any dependencies
	* rhodes depends on PersLite, PersImplJSR75, RhoBundle, RubyVM

#### Rebuilding After Code Changes

Go to `<rhodescheckout>` and run:

	:::term
	$ rake build:bb:rhobundle

It should re-create `rhodes\platform\bb\RhoBundle\RhoBundle.jar`

Right click on RhoBundle project in Eclipse and select Refresh. It should rebuild rhodes and RhoBundle. You can see messages in Builder Console. OR Just Clean all projects.

#### Eclipse simulator debug instructions

Open `Debug\Open debug dialog...` from toolbar (small bug icons). Dbl-click on Blackberry simulator node.

Go to Simulator page and choose Profile other than Default. Check 'Launch Mobile Data System Connection service with simulator' checkbox. 
** NOTE: you may have to install MDS on your computer if it is not installed. **

Press Debug button. Simulator starts. Eclipse may ask you about missing debug files, press 'Don't ask me again button'. 

You can also clean emulator and start emulator again: 
	
	:::term
	$ run <JDE_HOME>\simulator\clean.bat 

Press Menu button on emulator. Go to Downloads, run Rhodes

## Build for Windows Mobile

Note that Windows Mobile versions of your Rhodes app must be built in a Windows environment.
   
### Prerequisites

* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* .NET Compact Framework
* Windows Mobile 6 Professional SDK(s) 
* Microsoft Active Sync 4.5
* Visual Studio 2005 Service Pack 1 installed or Visual Studio 2008. 
* [7-zip](http://www.7-zip.org/)

Open ActiveSync main window, go to the File -> Connection Settings, select checkbox "Allow connections to one of the following" and select "DMA" from the list box. It is required to work with emulator.

### Build application from the command line

Add path to vcbuild.exe and CabWiz.exe to rhobuild.yml in the Rhodes folder:

	env:
	  paths:
	    vcbuild: 'C:/Program Files/Microsoft Visual Studio 8/VC/vcpackages/vcbuild.exe'
	    cabwiz: 'C:/Program Files/Windows Mobile 6 SDK/Tools/CabWiz'

### To run application on device or emulator(Visual Studio 2008 only) :

To build and run application on emulator, run (fastest way):
	
	:::term
	$ rake run:wm

To build cab-file, install it and run application on emulator, run:

	:::term
	$ rake run:wm:cab 

To build and run application on device, run (fastest way):

	:::term
	$ rake run:wm:device

To build cab-file, install it and run application on device, run:

	:::term 
	$ rake run:wm:device:cab 

### To build application cab-file for the device, run:

	:::term
	$ rake device:wm:production 

If you want the application to be signed automaticly during the build process, please add the 'wmsign' key with full path to your code signing certificate to the 'build' section of rhobuild.yml file:

	wmsign: <disk:/path/MySign.pfx>

More information about  Windows Mobile code signing you could find at:
http://msdn.microsoft.com/en-us/windowsmobile/dd569132.aspx

### To deploy application on device
First connect your device to computer. You can use USB-cable, bluetooth or any other method. To use computer internet you have to start ActiveSync.

* You can use rake tasks. See 'Build application from the command line' section. Device should be connected via USB-cable. 
* You can manually copy .cab file to device, for example to Temp folder and click on cab-file on the device using File Explorer. Installation process will be started. After finish you should see app icon on the device

### Build from IDE

Checkout rhodes source code from github 

Open `<source-code-root>\platform\wm\rhodes.sln` in Visual Studio.

Select Windows Mobile 6 Professional and build Release configuration.

Open the file `rhobuild.yml` using a text editor:

* define the path to CabWiz tool
* define the path to your application

Run

	:::term
	$ rake build:wm:devrhobundle

Make sure you cradle your emulator (menu Tools/Device Emulator Manager/Select Running Emulator/Actions/Cradle)

Copy `rhodes.exe` and `rhobundle` (located `<source-code-root>\platform\wm\bin\Win32\rhodes\Debug\rho`) created at the previous step to the device: `My Computer\Mobile Device` and folder on that device `\Program Files\rhodes`. You may delete content of `\Program Files\rhodes\rho` folder first to ensure there is no old files left.

If you changed your application, then to compile your application code run:

	:::term
	$ rake build:wm:devrhobundle
	
After that copy bundle from  `<source-code-root>\platform\wm\bin\Win32\rhodes\Debug\rho` folder to the device or emulator folder `\Program Files\rhodes\rho` to see you changes.

If you changed your application and built it using rake tasks to compile your application:

	:::term 
	$ rake device:wm

Copy '<appdir>\bin\target\rhodes.cab' content to device or emulator in `\My Documents\`, execute that .cab to install the app and then run your app to se the changes.

### Logging
To get log from emulator or device:

* connect device or emulator using ActiveSync
* press explore on ActiveSync window
* navigate to `My Device\Program Files\<app_name>\rholog.txt`

## Build for Windows

### Prerequisites

* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* Visual Studio 2005 Service Pack 1 installed, Visual Studio 2008 or Visual Studio 2010 (Express editions are also supported)
* WTL : http://wtl.sourceforge.net/ :
	* unzip to folder: <VS path>\VC\WTL
	* open in Visual studio menu `Tools\Options\Projects and solutions\VC++ directories`. Select platform - `Win32`; Show directories for - `Include files`; Add - `$(VCInstallDir)wtl\include`

### Build application from the command line

Make sure that path to vcbuild.exe (something like `C:\Program Files\Microsoft Visual Studio 8\VC\vcpackages`) is in your PATH env variable. The list of paths which should be in PATH env variable:

<i>C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\bin;C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\bin;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin</i>

If you use Visual Studio 2010 : add path to `msbuild` to `rhobuild.yml` in rhodes folder:

	env:
	  paths:
	    vcbuild: msbuild

To build and run emulator run:

	:::term
	$rake  run:win32

To clean all binaries run:

	:::term
	$rake clean:win32

### Logging

Rholog.txt is placed in `<rhodes folder>\platform\wm\bin\win32\rhodes\Debug\rho`

## Build for Windows Phone 7

### Prerequisites

* Follow [All Platforms Prerequisites](#all-platforms-prerequisites)
* Windows 7 OS
* Visual Studio 2010 installed or VS Express for Windows Phone and VS Express for C#
    * [Windows Phone Developer Tools RTW](http://www.microsoft.com/downloads/en/details.aspx?FamilyID=04704acf-a63a-4f97-952c-8b51b34b00ce)
    * [Windows Phone Developer Tools January 2011 Update](http://www.microsoft.com/downloads/en/details.aspx?FamilyID=49b9d0c5-6597-4313-912a-f0cca9c7d277)
    
* Add path to `msbuild` to `rhobuild.yml` in rhodes folder. For example:

	    env:
	      paths:
	        msbuild: C:/Windows/Microsoft.NET/Framework/v4.0.30319/MSBuild.exe

### Application changes
    
* Add to application build.yml productid GUID. For example:

        wp:
          productid: 632621d0-5ecb-012e-2c97-482a1411c191
NOTE: When you use rhodes command to generate application, productid is generated automatically

* Windows Phone 7 does not support POST method in HTML forms. So you have to change all form method to GET or use javascript to do it:

    Copy file:

        <rhodes>\res\generators\templates\application\public\js\wp7.js

        to your application public/js folder
        
    Modify layout.erb:

        <%if System::get_property('platform') == 'WP7' %>
            <script src="/public/js/wp7.js" type="text/javascript"></script> 
        <% end %>

        <% if System::get_property('platform') == 'WP7' %>
	        <body onload="wp7_change_forms_action_to_get()">
        <% else %>
	        <body>
        <% end %>
            <%%= @content %>
        </body>

    This script just replace FORM action to GET:

        function wp7_change_forms_action_to_get() {
            for(i=0;i<document.forms.length; i++)
            {
                document.forms[i].method = "GET";
            }
        }

You can use [Rhodes Application Generator](#generator) to see application code with all this changes
NOTE: in form action when using url_for specify :action => :create to call create controller method

### Build and run using Rhodes gem

* Install Rhodes gem

* Run application simulator:

        $rake run:wp

* Run application device:    

        $rake run:wp:device

* See log in application folder : rholog.txt

NOTE: When running on device you may need to disconnect USB cable from device to see log

* After Application code modifications, run rake commands. DO NOT close simulator!

### Build from sources
* Checkout rhodes source code from github 
* Get IronRuby master branch to parent folder of rhodes:

        $ git clone https://github.com/IronLanguages/main.git
  
  rename IronLanguages folder to IronRuby

* Build IronRuby(Once)

        rake build:wp:ironruby

### Build from IDE
#### IronRuby
* Copy folder `rhodes\platform\wp7\IronRuby\Languages` to `IronRuby`
* Open `IronRuby\Solutions\Ruby.sln` in VS 2010 or VS Express 2010 for C#.
* Select 'Silverlight3Debug|Any CPU' or 'Silverlight3Release|Any CPU' in solution configuration and build solution

#### Rhodes
* Open `rhodes\platform\wp7\rhodes.sln` in VS 2010 or VS Express 2010 for Windows Phone.
* Select Debug or Release configuration, Windows Phone 7 Emulator target and build solution.
* Run emulator by pressing Start Debugging or Start Without Debugging
* After Application code modifications , build Rhodes solution and Start Debugging. DO NOT close emulator!
* See log in VS output console (Debug mode only)

## How to set application name and icon

### Application Name
In the build.yml in your application folder there is an entry "name". This is the display name that the user will see on the device. Example:

	name: My Own App

### Application Icon
Place your image to use as an icon in a folder called `icon` in your application. If you created an app called `testapp` then the folder would be `testapp/icon`. The icon should be named `icon.png` and  `icon.ico` for Windows Mobile. Starting from iOS 4.0, Apple require three icons for application: 57x57, 72x72 and 114x114 pixels. Prepare such files, name them as `icon57.png`, `icon72.png` and `icon114.png` and place into `icon` folder

	testapp/
		build.yml
	    Rakefile
	    rhoconfig.txt
	    app/
	    public/
	    icon/
	    	icon.png
	    	icon.ico

### iPhone using xCode

* Target->info->General->Name
* Target->info->Build->Product Name (for all configurations)    
* rhodes\platform\iphone\icon.png, icon57.png, icon72.png, icon114.png - change to your icons
* check rhodes\platform\iphone\Info.plist it should contain BundleName=${PRODUCT_NAME}

### Windows Mobile
Windows Mobile Shell program caches program icons. This cache is cleared only when device or simulator is restarted.
So if you change icon of application, you have to restart device/simulator(uninstall/install is not enough).