Manuals | RubyMotion

Getting Started with RubyMotion for Android

Thank you for downloading RubyMotion. This guide will help you get started with RubyMotion for Android.

1. Overview

RubyMotion is a toolchain that permits the development of iOS, OS X and Android applications using the Ruby programming language.

iOS is Apple’s mobile operating system, powering a variety of devices such as the iPhone, iPod touch and iPad. OS X is Apple’s desktop operating system, powering Mac computers such as the iMac or the MacBook Air. Android is Google’s mobile operating system, powering a huge array of devices from different manufacturers.

Developers can write applications for iOS and OS X and submit them to the App Store, Apple’s application distribution system. Alternatively, RubyMotion can be used to conceive applications for Android that can be submitted to the Google Play store.

Conceptually, RubyMotion is a combination of two major components:

Runtimes: Brand-new implementations of the Ruby language, tightly integrated with the native Apple or Google runtime and optimized for embedded device constraints.
Project Management: A command-line interface to create, manage, and interactively develop RubyMotion projects. It also includes a static compiler that compiles Ruby into optimized machine code and an interactive console where you can evaluate expressions on the fly and change the way your app behaves in real-time.

RubyMotion installs itself into '/Library/RubyMotion'. A symbolic link to the command-line interface is created as '/usr/bin/motion'.

This document focuses on RubyMotion for Android. For iOS and OS X, check out the Getting Started With iOS and OS X document instead.

2. Prerequisites

RubyMotion requires a 64-bit Mac running OS X 10.8.4 or higher. OS X 10.12 Sierra or higher is however recommended.

A proper Android development environment is required in order to use RubyMotion for Android.

2.1. Installing Java

The RubyMotion build system requires a Java compiler to be installed. By default, OS X does not come with Java.

Follow the steps on this page to get Java installed on your environment.

Install Java 1.8, also.

After doing that you can verify that Java has been properly installed:

$ javac -version
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

2.2. Downloading the SDK

Download the Eclipse ADT bundle from the official Android website. You will have to accept the terms of conditions before the download.

Despite its name, the Android SDK resides within this bundle.

Once downloaded, open the .zip file. You will see 2 directories inside, eclipse and sdk. The later is the one that RubyMotion will need.

We recommend that you copy the sdk directory somewhere in your home directory. In this document we will use ~/android-rubymotion.

$ mkdir ~/android-rubymotion
$ cp -r ~/Downloads/adt-bundle-mac-x86_64-20140702/sdk ~/android-rubymotion

Once you do that make sure the ~/android-rubymotion/sdk directory has been properly copied. This is what it should contain (at the time of this writing):

$ ls ~/android-rubymotion/sdk
build-tools	extras		platform-tools	platforms	tools

Unless you plan to use Eclipse, you can safely delete the .zip file as well as the directory that was extracted from it.

2.3. Setting Up the SDK

Now that the Android SDK has been copied, you still need to set it up by downloading internal packages. Run the android tool:

$ ~/android-rubymotion/sdk/tools/android

This will pop up a window titled Android SDK Manager with a selection of packages that should be installed. Click the Install button and wait until it’s done. It can take some time.

2.4. Downloading the NDK

Download the Mac OS X 64-bit package from the official Android website. You will have to accept the terms of conditions before the download.

Note	It is important that you download the right NDK package. The Mac OS X 32-bit package will not work with RubyMotion at the time of this writing.

The Android NDK package is a self-contained installer. Once downloaded, you can mark the binary as executable, run it, then rename it as ~/android-rubymotion/ndk:

$ chmod +x ~/Downloads/android-ndk-r10c-darwin-x86_64.bin
$ ~/Downloads/android-ndk-r10c-darwin-x86_64.bin
$ mv ~/Downloads/android-ndk-r10c ~/android-rubymotion/ndk

To confirm that the installation was successful, this is what the ~/android-rubymotion/ndk should contain (at the time of this writing):

$ ls ~/android-rubymotion/ndk
GNUmakefile			ndk-gdb-py.cmd
README.TXT			ndk-gdb.py
RELEASE.TXT			ndk-stack
build				ndk-which
docs				platforms
find-win-host.cmd		prebuilt
ndk-build			remove-windows-symlink.sh
ndk-build.cmd			samples
ndk-depends			sources
ndk-gdb				tests
ndk-gdb-py			toolchains

After that, you can safely delete the .bin file.

2.5. Configuring RubyMotion

We are almost finished! It is now time to point RubyMotion to the Android SDK and NDK directories.

Add the following lines to your ~/.profile file (you can create the file if it does not exist yet):

export RUBYMOTION_ANDROID_SDK=~/android-rubymotion/sdk
export RUBYMOTION_ANDROID_NDK=~/android-rubymotion/ndk

Once done, restart your terminal so that these environmental changes are taken into account.

You can verify that the environment variables are properly set:

$ env | grep RUBYMOTION_ANDROID
RUBYMOTION_ANDROID_SDK=...
RUBYMOTION_ANDROID_NDK=...

2.6. Configuring Your Device For Development

You will need a functional Android device configured for development when writing Android apps in RubyMotion. (The provided emulator is way too slow.)

In case you haven’t done it already, make sure your device is connected to your Mac via a USB cable, then perform the following steps:

Open the Settings app.
Scroll down and tap on the About phone or About tablet item, depending of the type of the device you are using. This will open a new screen.
Scroll down again and tap 7 times on the Build number item. A message should appear after that, clarifying that you are now in developer mode.
Go back to the previous screen and scroll down again, a Developer options item is now available. Tap on it.
Check the USB debugging item. This will allow your Mac to communicate with the device for development tasks. A window will appear on the device, asking you to authorize the Mac. Make sure to confirm that.

You should now be good to go!

If you are running an older version of Android these steps might not work for you. We recommend that you do a Google search for enable developer mode with your Android version number.

3. Text Editor

After having installed RubyMotion you need to set up a text editor for development. RubyMotion does not come with a proprietary IDE and lets you use the editor of your choice.

3.1. RubyMine

RubyMine is a commercial IDE for Ruby built on JetBrains' IntelliJ IDEA platform.

It is at the time of this writing the best environment to work with RubyMotion. RubyMine features context-based auto-completion, point-and-click debugging (on both the simulator and the device), inline documentation, and so on.

Please refer to the Getting Started with RubyMotion guide on JetBrains' developer website for more information.

3.2. TextMate

TextMate is a popular editor on OS X.

A RubyMotion.tmbundle plugin is available. It provides code completion and an integration with the build system. It is developed by Libin Pan and Berklee.

3.3. Sublime Text

Sublime Text is a relatively new editor for OS X, Windows and Linux that is gaining a lot of interest.

SublimeRubyMotionBuilder is a plugin that provides code completion and an integration with the build system. It is developed by Kentaro Hara.

3.4. Redcar

Redcar is an Open Source editor written in Ruby.

redcar-rubymotion is a plugin that integrates the RubyMotion workflow in Redcar. All features of RubyMotion are integrated. It is developed by Delisa Mason.

3.5. Vim

Vim is the most popular clone of vi. Vim ships in OS X. MacVim is a flavor of Vim for OS X that runs outside the terminal.

The builtin rake ctags task can be used to generate a tags file containing all the APIs the project can call into. This file can then be used to automatically complete API calls in the editor. RubyMotion uses Exuberant Ctags. Ctags is a format understood by a variety of text editors, Vim included.

Better auto-completion can be provided by using the snipmate-snippets-rubymotion plugin, courtesy of Rajeev Cyrus.

3.6. Emacs

Emacs is a popular text editor. Emacs ships in OS X.

motion-mode is a plugin that provides code completion and an integration with the build system. It is developed by Satoshi Namai.

4. Software Updates

Software updates can be applied via the command-line.

The following command will grab the latest version of RubyMotion from the network and install it. You must be connected to the Internet to successfully update RubyMotion.

$ sudo motion update

You can run the following command to check the version of RubyMotion installed on your computer.

$ motion --version
5.8

Once a day, the RubyMotion build system pings the software update server in order to see if a new version of RubyMotion is available to install.

If a new version is available RubyMotion prints a message to your terminal suggesting that you to upgrade. The build system will also print a message if your license is about to expire.

Support _~_~-

If you are experiencing an issue, would like to request a feature, or simply have a question, you can file a support ticket from the command-line too.

$ motion support

This will open a new window in your browser where you can fill up a support ticket. Your license key and some useful information regarding your environment will be added automatically.

Note	Support tickets are available to Professional and Enterprise customers only. If you are not entitled to use support tickets you can make use of the community forum for support enquiries instead.

5. Hello World

Let’s create a Hello World app for Android.

Go to a directory of your choice, then type the following command to create a new Android project.

$ motion create --template=android Hello
$ cd Hello

Note	Note that we pass `--template=android` to the toolchain. By default, RubyMotion will create iOS projects, so we have to select the Android template.

A new Hello directory has been created. Check out the Rakefile and the app/main_activity.rb files.

You can try to run the app on your device. Make sure it’s connected via USB, then run the following command.

$ rake device

The app should start right away (make sure you unlocked the device screen first). The window should be empty, which is expected given that we have not written any code yet.

Now, edit the app/main_activity.rb file and change its content to the following code.

class MainActivity < Android::App::Activity
  def onCreate(savedInstanceState)
    puts "Hello World!"
    super
    view = Android::Widget::TextView.new(self)
    view.text = "Hello World!"
    self.contentView = view
  end
end

If you run rake device again, you should see the hello world message appearing on your device. Also, the same message will be printed on your terminal, due to the #puts call.

6. And Now?

Congratulations, you successfully created your first RubyMotion Android app. That wasn’t too hard, was it?

To continue, we recommend that you check the Samples page as well as the Sample Code Repository on GitHub. Each of the sub-folders contains a RubyMotion project as introduced above. You can type rake in each directory to build and run them and check their source code by reading the files in the 'app' directory.