This guide will assist you in building your apps using the remote build capabilities of rhomobile.com. Using this tool you will be able to build for any of the platforms that we support regardless of your computer hardware. That means you will be able to build iOS apps even if you are using a Windows computer and build Windows Mobile apps even if you are using an Apple computer. There are however, a few limitations to this build process and we have listed them below.
The following is a table showing the versions of Rhodes that are supported for which platforms concerning cloud builds. Note that the end of life date is simply an estimate and will not necessarily be exact to the day. Note that dates for estimated End of Life are subject to change as release dates of next versions change.
|Rhodes Version||Estimated End of Life||Platforms|
Note: Micro Kiosk devices (MKxxxx) are not supported for cloud-built apps. For these devices, Enterprise Browser is also available as an app building solution alternative.
Before building remotely, you’ll need to sign up for a subscription plan of either silver or gold; only paid subscription plans allow the use of the remote build feature. Refer to the licensing doc for assistance on signing up and applying your remote build token.
Note: Once you login using your rhomobile.com account credentials, the token used to verify your identity will be saved for about a week, at which time you’ll need to have an data connection in order to update your token. You must do this even if you are building your app off-line.
Using RhoMobile’s product suite, apps can be built using either the command line interface, or with our eclipse based IDE, RhoStudio. All steps will be shown using both methods.
RhoMobile makes the entire app creation process extremely quick by auto-generating common files for you so that you can get into coding your specific app as soon as possible. During either of these processes you’ll see the framework create all the necessary files.
To generate the app’s structure using the command line, simply run the following command:
$ rhodes app <appanme>
To generate the app’s structure using RhoStudio, follow these steps:
At this point, you can actually build the app for the platform of your choice and you’ll have a fully functioning, bare-bones app. It currently does nothing but you have created the structure of a running app in just about a minute, with no coding necessary on your part. but how do we get this app to build in the cloud?
Once you've set up your account and generated an app it's time to build that app for a device. To build locally using RhoStudio or the command line interface follow our guide on running your app locally. To build your app remotely, start by logging into your rhomobile.com account and add an app to your account that has the same name as the app that you just created in RhoStudio or with the CLI. The name of the remote project does not need to be the same but it aids in reducing confusion. If you experience trouble during any of the steps below, please see our troubleshooting section below.
Note: This is step simply make an empty repo for you to push code up to, there is no code generation happening at this point. To generate code, you must use either RhoStudio or the CLI.
Once you have created the remote end of the app you will see a screen like this. On this screen you can either build your app remotely from inside your browser or you can copy the git URL to build from RhoStudio or the command line. For the purposes of this guide, let's copy the git URL by clicking the copy icon next to the Git URL field. Once you have done that, you'll need to associate your local project with your remote project.
Open you command line utility (terminal on Mac and cmd on Windows), navigate to your projects root folder and run the following commands:
$ git init $ git remote add origin <Your Git URL> $ touch README.md $ git add . $ git commit -m 'Initial commit' $ git push -u origin master
Let’s walk through these commands to understand what’s going on.
git init– This initializes your local project’s directory as a git repository.
git remote add origin <Your Git URL>– This will associate the remote git repo that you specify using your Git URL to the local repo.
touch README.md– This creates a README markdown file. You can use this file to describe to others what your app is all about. This step is optional.
git add .– This stages all the files in your project to be committed and pushed to the remote repo. Note, the
add .command should not be used frequently, it is used here as an initial startup process. Usually you’ll want to add files individually as to not commit files mistakenly.
git commit -m 'Initial commit'– This will finalize the addition of the files you have just added and will make note that this is the initial commit of this repo.
git push -u origin master– This will upload the files you have committed to the remote repo. The
-uoption is used to set the upstream endpoint so that in the future, all you need to use is
git pushto upload to origin/master. In this case, “origin” is the name of our remote endpoint and “master” is the name of the branch we are pushing code up to. If you wanted to push to a different branch you would use
git push -u origin <your_branch>.
That’s all there is to it! You can now build your app remotely on rhomobile.com.
You may wish to perform a remote build using an app inside of a private GitHub repository. To do so, there is a bit of setup that must be done first.
Note: If you’ve already accepted the ‘rhohubbuild’ user into your organization, you do not need to re-invite the user( aka: the private repository setup applies across rhomobile applications in your GitHub organization). If you are unsure, see the optional step at the bottom of this section to check if the user is already invited.
Inside of Github, invite the user ‘rhohubbuild’ to a team in your organization. Steps for adding members to your organization can be found in GitHub’s documentationn. This user will need access to your repository before it can clone your private repository for the purposes of building.
In your Rhomobile.com account profile, click the GitHub tab on the left to access the GitHub integration info. You'll need to add your organization's GitHub name in the first text box. This name needs to be EXACTLY the same as what's on GitHub or the connection will not work. Then push the 'Accept Invite' button. This will use GitHub's API V3 to accept the 'rhohubbuild' user invitation.
First click the "Change Git Source" button and then enter your SSH GitHub clone address in the main build page and hit save. This is the address that starts with `firstname.lastname@example.org`. Now you're ready to build using your private GitHub repository.
If you would like to confirm that your organization has fully accepted the 'rhohubbuild' user, and that you are set to clone from a private repository, please enter your organization name below and click the 'Check Invite' button.
To build your app remotely, you have tree different ways that you can go about it:
1. Build your app directly on rhomobile.com.
2. Build your app remotely through RhoStudio.
3. Build your app remotely through the Command Line Interface.
Command Line Build
Building on rhomobile.com is fairly straight forward, once you have completed the steps above, you'll see a screen similar to this one once you sign into rhomobile.com. From here, all you need to do is select the parameters you want to build with from the drop-down boxes shown and click build.
|When building for iOS you will need to provide your developer certificate, the password for that certificate, your provisioning profile file, and your bundle identifier. These items are not necessary when building for other platforms but Apple is very strict on it's policy for building apps.|
Once you have built your app through the online console, you will be able to click the download icon to download the app package (.apk for android, .cab for Windows Mobile, etc), put the package on your device, and install it. If the build failed, you'll be able to download the logs of the build to debug the reason for the failed build.
In addition to the clickable link download your app's package, you can also hover over the QR icon and it will expand, showing a QR you can use to download the app directly to your device. Alternatively, if you click the QR icon it will download the app to your machine.
Note: Before remotely building through RhoStudio, you’ll need to manually push any recent changes that you want your app to build with up to your remote repo using the command line. Simply add, commit, and push the changes, similar to the last three steps in the Git Integration section above.
When you start RhoStudio for the first time, you'll be prompted to provide your rhomobile.com email and password (You must have an active and open internet connection for this to work properly). This will connect your RhoStudio installation with your account on rhomobile.com and allow for cloud building, should your subscription level permit cloud builds.
Once you have logged in and RhoStudio has verified your subscription, you build your app the same way you normally would but in the build configuration for your app, choose "Rhomobile.com" in the Build field. This type of build can only be done for device and simulator builds. Click run and the app will start to build remotely. If you receive error concerning your local build during this step, it does not necessarily mean the the remote build failed.
Once the app has finished building, the app will be downloaded and placed into the
<appname>/bin/<platform>/ folder. Upon build failure, the build log will also be stored in the aforementioned folder, as well as all app build behavior being printed out in the RhoStudio console.
Note: Before remotely building through the command line interface, you’ll need to manually push any recent changes that you want your app to build with up to your remote repo. Simply add, commit, and push the changes, similar to the last three steps in the Git Integration section above.
The first time you attempt to build, you'll be prompted to enter the email and password you used to sign up with on rhomobile.com. Entering this information will connect your installation to your account on rhomobile.com and allow you to build according to the restrictions of your account subscription.
To build your app remotely from the command line, after you've logged in, you will need to use one of many rake commands. To view the available rake commands, run the command
$ rake -T. Once you have decided on the command to use, run that command and wait for the build process to finish. For this example, we will keep with the Android theme and build for an android device using the command
$ rake cloud:android:device which will build our app into an .apk that we can download and install onto our device.
Once the build process finishes, it will automatically download and uncompress the app package into the
<app-project-directory>/bin/<platform>/ directory, similar to the way that RhoStudio does this.
Note: When building an Android app to run on the simulator, i.e.
rake cloud:run:simulator[build_id], you must have the corresponding Android SDK installed or it will not run. The rake task will run, download, and unpack the app, and then fail to launch with the message ‘Wrong Android emulator version: . Android SDK target API is not installed’.
There are a few limitations that our remote build service must adhere to in order to function properly and efficiently:
Here are a few issues that may come up while you are attempting to build remotely:
A: This is an issue that comes up when you have not configured your settings correctly in your rhobuild.yml file. To fix this in RhoStudio, open the RhoMobile > Android section in the preferences and fill in the correct information for the Android SDK and NDK. The same thing goes for incorrect information for Windows Mobile builds, only that you will need to fill out the Windows Mobile section instead of the android section. See our RhoBuild.yml section of the build config doc for more information.
A: This error is caused by not having setup your app’s remote endpoint yet. Follow the instructions here to get setup.
A: This happens when you are trying to build remotely to a GitHub repo instead of a remote repo on rhomobile.com. You must change the remote repo that is associated with your local project folder to one that exists on rhomobile.com.
A: You’ll get this error if you forget to add and commit your changes before your initial push. Follow the instructions here closely to remedy this.
A: The most common cause for this is that you have not yet added your SSH public key to your account on rhomobile.com. Follow github’s guide on SSH keys to generate your public key if you have not already done so. Then go to your profile on rhomobile.com (after signing in, click “Profile” in the account menu in the upper-right corner of the page) and select “SSH Keys” to add it to your account.
A: There is a known issue wherein the app will not appropriately start the ‘ANS’ service required for some parts of the app to work properly. There is a workaround for this: include rhoconnect-push in the app’s
build.yml file. This will apply the required manifest settings, allowing the app to start the ANS service.