RubyMotion logoRubyMotion

 
 
 

Getting Started with RubyMotion for iOS and OS X

Thank you for downloading RubyMotion. This guide will help you get started with RubyMotion for iOS and OS X.

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 iOS and OS X. For Android, check out the Getting Started With Android 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.

You will need to install the iOS and OS X SDK on your machine. These days the SDKs comes with Xcode.

2.1. Installing Xcode

Xcode can be downloaded and installed for free using the App Store application.

Note
 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.

Searching for Xcode in the App Store

Find Xcode from the result, then click on it.

Searching for Xcode in the App Store

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.

Installing the Command Line Tools package

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

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

5.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.

Hello World

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?

5.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
Note
 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.

Hello World

6. And Now?

Congratulations, you successfully created your first RubyMotion iOS and OS X apps. 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.