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.
2. Prerequisites
RubyMotion requires a 64-bit Mac running OS X 10.8.4 or higher. OS X 10.9 Mavericks is however recommended.
2.1. iOS and OS X
You will need to install the iOS and OS X SDK on your machine. These days the SDKs comes with Xcode.
2.1.1. Installing Xcode
Xcode can be downloaded and installed for free using the App Store application.
|
|
Xcode is Apple’s IDE. You do not need to use it when programming with RubyMotion, you can keep using your favorite text editor. |
Open the App Store application then search for "Xcode" in the search field.
Find Xcode from the result, then click on it.
That should open a new page where you can download Xcode.
Once Xcode is installed, you will need to install the Command Line Tools package, required by RubyMotion.
Open the Xcode application from your Applications folder, then go to the Preferences window and click on the Downloads tab. You should see the Command Line Tools package in this list, make sure to hit the Install button.
Okay, you should be all set now! You can close Xcode.
If you happened to have an older version of Xcode installed on your machine before you installed a newer Xcode from the App Store, you may want to type the following command in order to properly set up the default Xcode path.
$ sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
2.2. Android
|
|
Android support is currently in public beta. While it is fully functional, we are still working on making it ready for prime time. |
The first thing you have to do is install the RubyMotion for Android beta, using the following command.
$ sudo motion update --pre
This will install the beta under the /Library/RubyMotionPre directory.
After you do that, you need to set up a proper Android development environment.
2.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.
After doing that you can verify that Java has been properly installed:
$ javac -version javac 1.6.0_65
Java 1.7 should work but we recommend sticking to Java 1.6.
2.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.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.2.4. Downloading the NDK
Download the Mac OS X 64-bit NDK for 32-bit target package from the official Android website. You will have to accept the terms of conditions before the download.
|
|
It is important that you download the right NDK package. The Mac OS X 64-bit NDK for 64-bit target package will not work with RubyMotion at the time of this writing. |
Once downloaded, open the .tar.bz2 file, then copy its content inside ~/android-rubymotion under the ndk directory:
$ cp -r ~/Downloads/android-ndk-r10 ~/android-rubymotion/ndk
To confirm that the copy was successful, this is what it 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 documentation.html prebuilt find-win-host.cmd remove-windows-symlink.sh ndk-build samples ndk-build.cmd sources ndk-depends tests ndk-gdb toolchains ndk-gdb-py
After that, you can safely delete the .tar.bz2 file as well as the directory that was extracted from it.
2.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.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. If you already have a preferred editor such as RubyMine, Vim or TextMate you should be good to go. Please read our editors guide for more information.
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 2.24
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.
5. 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.
6. Hello World
6.1. iOS
We are now ready to write our first RubyMotion iOS program: Hello World.
Open your terminal and go to a place where you would like this first project to be created, then type the following command.
$ motion create Hello
This command will create a RubyMotion project in a new directory named Hello. If this directory already exists or cannot be created, the command will fail.
Let’s have a look inside.
$ cd Hello $ ls Rakefile app resources spec
A RubyMotion project is Rakefile-based. rake is the de-facto Ruby build program. It is similar to make and it ships with Mac OS X by default.
The app directory contains the application code. The resources directory will eventually contain the resource files of your project, such as icon, image or sound files. The spec directory contains specification/test files.
Let’s run the default task.
$ rake
This should build our project then start the simulator, and you should see… an empty, black window. It’s actually normal, we haven’t written any code yet!
If you look inside the app directory you will see an app_delegate.rb file, which is created by default. This file implements the AppDelegate class, which is responsible for controlling your application.
class AppDelegate
def application(application, didFinishLaunchingWithOptions:launchOptions)
true
end
end
Open the app/app_delegate.rb file with your favorite editor. We will change the code to do something more interesting, such as triggering an alert.
class AppDelegate
def application(application, didFinishLaunchingWithOptions:launchOptions)
alert = UIAlertView.new
alert.message = "Hello World!"
alert.show
true
end
end
If you run the rake command again from the terminal you should be able to see the alert in the simulator.
Now, let’s try this outside the simulator. Make sure you have an iOS device properly configured for development connected over USB, and type the following.
$ rake device
This should install the Hello app on your device. You can now pick it up and run the app, and you should be able to see the alert message.
Congratulations, you successfully created your first RubyMotion program. That wasn’t too hard, was it?
6.2. OS X
Now, let’s try to write our first RubyMotion OS X program. It will also be Hello World.
Open your terminal and go to a place where you would like this first project to be created, then type the following command.
$ motion create --template=osx Hello
|
|
Please note that we are passing the --template=osx option to the motion command here. By default, motion create will create iOS projects. Since we want to create an OS X project, we need to select the OS X project template. |
This command will create a RubyMotion OS X project in a new directory named Hello. If this directory already exists or cannot be created, the command will fail.
Let’s have a look inside.
$ cd Hello $ ls Rakefile app resources spec
A RubyMotion project is Rakefile-based. rake is the de-facto Ruby build program. It is similar to make and it ships with Mac OS X by default.
The app directory contains the application code. The resources directory will eventually contain the resource files of your project, such as icon, image or sound files. The spec directory contains specification/test files.
Let’s run the default task.
$ rake
This should build our project then start the app, and you should see… an empty window! It’s actually normal, we haven’t written any code yet!
If you look inside the app directory you will see an app_delegate.rb file, which is created by default. This file implements the AppDelegate class, which is responsible for controlling your application.
class AppDelegate
def applicationDidFinishLaunching(notification)
buildMenu
buildWindow
end
end
Open the app/app_delegate.rb file with your favorite editor. We will change the code to do something more interesting, such as triggering an alert.
class AppDelegate
def applicationDidFinishLaunching(notification)
buildMenu
buildWindow
alert = NSAlert.new
alert.messageText = "Hello World!"
alert.runModal
end
end
If you run the rake command again from the terminal you should be able to see the alert in the simulator.
6.3. Android
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 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.
7. And Now?
Congratulations, you successfully created your first RubyMotion iOS, OS X and Android programs. That wasn’t too hard, was it?
You will find sample code for both iOS, OS X and Android in 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.
Make sure to check the Developer Center for more resources, such as guides, articles and screencasts.