Command Line Usage

This section describes how to carry out some of the most common actions using the robovm command line tool. For a complete usage reference for the options supported by the robovm tool run

$ robovm -help

Working with robovm.xml files

Almost everything can be done directly from the command line using the options of the robovm command but it is still recommended to use an XML configuration file called robovm.xml to configure the compiler.

The -dumpconfig option can be used to create a robovm.xml file. This creates a robovm.xml file for the demo app in [demo-app]:

$ robovm -arch thumbv7 -os ios -cp "$ROBOVM_HOME/lib/robovm-objc.jar:$ROBOVM_HOME/lib/robovm-cocoatouch.jar:bin/" -dumpconfig robovm.xml IOSDemo

Once we have the robovm.xml file we only have to specify it on the command line to launch the app. This would launch the app on a connected device since the robovm.xml file specifies the thumbv7 architecture:

$ robovm -config robovm.xml -run

TIP: You can load multiple configurations by specifying -config multiple times. The latter ones take precedence.

We can override the configuration read from a robovm.xml file by specifying the options we want to override after the robovm.xml file has been read in. To launch on the iOS simulator we need to build for the x86 architecture so we use the -arch option after the configuration file has been specified:

$ robovm -config robovm.xml -arch x86 -run

We can even "edit" the robovm.xml file by combining -config and -dumpconfig. This adds a new classpath entry:

$ robovm -config robovm.xml -cp foo.jar -dumpconfig robovm-new.xml
$ mv robovm-new.xml robovm.xml

Expanding properties in robovm.xml files

XML configuration files (and also Info.plist files) will be searched for ${...} patterns. Such patterns will be replaced with properties loaded using the -properties command line option which reads in .properties file. Individual properties can also be specified directly on the command line using the -Pname=value option.

Launching apps

To launch an app using the command line tool you simply specify the -run command line option. RoboVM will use the configured target OS (-os) and architecture (-arch) to determine how to launch the app.

To launch in the iOS simulator use -os ios -arch x86:

$ robovm -cp ... -os ios -arch x86 -run com.example.MainClass

To launch on an iOS device in 32-bit mode use -os ios -arch thumbv7:

$ robovm -cp ... -os ios -arch thumbv7 -run com.example.MainClass

To launch on an iOS device in 64-bit mode use -os ios -arch arm64:

$ robovm -cp ... -os ios -arch arm64 -run com.example.MainClass

RoboVM also supports building Mac OS X console apps. This is what you get if you don't specify any -os or -arch (or use -os macosx -arch x86):

$ robovm -cp ... -run com.example.MainClass

Packaging for App Store/Ad-Hoc distribution

The -createipa option is used to create an IPA file) which can be submitted to the App Store or distributed to beta tester or throughout an enterprise.

NOTE: Before you can do this you will have to have your signing certificates and provisioning profiles in order. Apple has some great resources that describe how to enroll in the iOS developers program and create the certificates and provisioning profiles required for App Store distribution.

This will create an IPA file signed with the code signing certificate matching iPhone Distribution and using the provisioning profile named My Distribution Profile. The IPA will be stored in ~/Desktop/IPA/:

$ robovm -config robovm.xml -signidentity 'iPhone Distribution' -provisioningprofile 'My Distribution Profile' -d ~/Desktop/IPA/ -createipa

TIP: The -signingidentiy option matches against the start of the certificate name. Alternatively you can use a certificate fingerprint. If the -signingidentiy value is enclosed in / a regexp search will be done against the certificate name instead. Run the command security find-identity -v -p codesigning or use the KeyChain Access OS X app to view your installed certificates.

CAUTION: The IPA creation also creates a .dSYM folder in the folder you specify with -d. The .dSYM contains the debug symbols of your app. It is required if you want to symbolicate a crash report generated by your app. To symbolicate you need the exact .dSYM so make sure you back this up.

The IPA is now ready to be distributed. To submit the IPA file to the App Store you would use the Application Loader application that comes with Xcode. The Application Loader application can easily be located using Spotlight.