RubyMotion Tutorial for Beginners: Part 1

In this RubyMotion Tutorial for beginners, you’ll learn how to make a simple Pomodoro app for the iPhone. By Gavin Morrice.

Leave a rating/review
Save for later

Ask any Ruby developer, especially one with a background in Java, C or C++, and they’ll tell you just how much better their life is since discovering Ruby. Ruby’s syntax is concise, simple, and consistent, which makes it very easy to learn and to use.

Despite it’s simplicity, Ruby has extensive metaprogramming features; this makes it a very powerful language for developing scalable, developer-friendly applications.

RubyMotion helps iOS and Mac developers create full-featured, native apps that are as slick and performant as apps written in Objective-C or Swift — only they’re written in the fun, elegant and flexible Ruby language. Goodbye, Xcode! :]

In this 2-part RubyMotion tutorial series, you’ll build a simple iPhone application from scratch using RubyMotion and learn the basics of RubyMotion.

You’ll need the following basic knowledge to get the most out of this RubyMotion tutorial:

  • Experience in developing for iOS in Objective-C
  • Basic understanding of Ruby
  • Basic knowledge of CSS
  • Basic experience with Terminal

If you need a Ruby refresher, there’s a great free guide at CodeSchool. As for iOS development, we have tons of iOS tutorials to help you along.

With those prerequisites met, you’re ready to begin!

Getting Started

RubyMotion isn’t free; to get started you’ll have to purchase a license from RubyMotion. It’s $199.99, but in my opinion it’s a worthwhile investment for the time savings it offers.

Download and install RubyMotion as per the Getting Started guide on the RubyMotion site.


While you’re waiting for RubyMotion to finish downloading, you can learn some of the similarities — and the differences — between RubyMotion and Ruby below.

Differentiating RubyMotion vs. Ruby

RubyMotion uses a Ruby-like syntax. In order to bridge the gap between Ruby and Objective-C, RubyMotion has a few differences from the reference implementation of Ruby – the key difference being how you name method parameters.

While Ruby 2.0 does support named parameters, RubyMotion considers the parameters as part of the method name itself, just as they are in Objective-C.

Consider the following method definitions:

def tableView(table_view, cellForRowAtIndexPath: indexPath)
  # ...

def tableView(tableView, heightForRowAtIndexPath: indexPath)
  # ...

In Ruby 2.0.0 and later, the second method definition would overwrite the first. However, RubyMotion would consider them as two distinct methods.

RubyMotion also handles the parameter names differently: in Ruby, the parameter key (heightForRowAtIndexPath in this case) becomes the local variable available in the method, while in RubyMotion the parameter value itself is available to the method, much like Objective-C.

Finally, RubyMotion is a compiled language; while Ruby is an interpreted language.

Introducing Pomotion

Your task in this RubyMotion tutorial is to develop a productivity tool based on the famous Pomodoro Technique. The app consists of a 25-minute countdown timer which can help you develop a more productive pattern of working for a focused period and then taking a short rest.

Open up Terminal, move to a directory of your choice (I used ~/Gavin/Code/) and run the following command:

motion create Pomotion

You should see the following output:

Create Pomotion
Create Pomotion/.gitignore
Create Pomotion/app/app_delegate.rb
Create Pomotion/Gemfile
Create Pomotion/Rakefile
Create Pomotion/resources/Default-568h@2x.png
Create Pomotion/spec/main_spec.rb

The motion command creates a basic template app containing the bare essentials to get you started.

Change to the newly created directory using the cd command as follows:

cd Pomotion

Then open the directory in Finder:

open .

You should see the following files:

Empty RubyMotion App directories

Here’s what’s in each of those files:


If you’ve used Cocoapods before, you can think of the Gemfile as being similar to a Podfile.

Ruby offers thousands of libraries or gems, most of which are open source code projects maintained by the Ruby community. Many of these gems are directly compatible with RubyMotion and a few are now being written especially for RubyMotion.

Using the bundler gem with this Gemfile lets you easily include other gems in your project and manage your app’s dependencies. This makes it easier to share code between developers.


Rake is Ruby’s answer to Make.

A Rakefile is equivalent to a Makefile. Rake lets you specify tasks, set configurations, and add dependencies within your application. Rake ships with OS X so you should be able to run it from Terminal without any problems.

Open the Rakefile in your favorite text editor; you’ll see it already has one pre-set configuration option: the app name Pomotion. There are several default configurations you can also change yourself; you can find a list of them in the RubyMotion Project Management Guide.

Head back to Terminal and run the following command:

rake config

This shows you your current configuration like so:

  background_modes       : []
  build_dir              : "./build"
  codesign_certificate   : "iPhone Developer: Gavin Morrice (X999X9X9XX)"
  delegate_class         : "AppDelegate"
  deployment_target      : "7.1"
  device_family          : :iphone
  embedded_frameworks    : []
  entitlements           : {}
  external_frameworks    : []
  files                  : ["./app/app_delegate.rb"]
  fonts                  : []
  framework_search_paths : []
  frameworks             : ["UIKit", "Foundation", "CoreGraphics"]
  icons                  : []
  identifier             : "com.yourcompany.Pomotion"
  interface_orientations : [:portrait, :landscape_left, :landscape_right]
  libs                   : []
  manifest_assets        : []
  motiondir              : "/Library/RubyMotion"
  name                   : "Pomotion"
  prerendered_icon       : false
  provisioning_profile   : "/Users/Gavin/Library/MobileDevice/Provisioning Profiles/XXXX.mobileprovision"
  resources_dirs         : ["./resources"]
  sdk_version            : "7.1"
  seed_id                : "XXXXXXXX"
  short_version          : nil
  specs_dir              : "./spec"
  status_bar_style       : :default
  version                : "1.0"
  weak_frameworks        : []
  xcode_dir              : "/Applications/"

Some of those configuration settings will likely be familiar to you, others, like motiondir and xcode_dir are unique to RubyMotion.

Overriding Configuration Options

You’ll override a couple of these defaults with your own preferences. Since Pomotion is still under development, the version number should probably be lower than 1.0.0. Also, you won’t support landscape orientation just yet.

Open Rakefile and add the following lines within the Motion... do block:

app.interface_orientations = [:portrait]
app.version = "0.1.0"

Your entire Rakefile should now look like this:

# -*- coding: utf-8 -*-
require 'motion/project/template/ios'

  require 'bundler'
rescue LoadError

Motion::Project::App.setup do |app|
  # Use `rake config' to see complete project settings. = 'Pomotion'
  app.interface_orientations = [:portrait]
  app.version = "0.1.0"

Run rake config to verify the changes you just made to the configuration. You should now see that version and interface_orientations have been changed for your app – and all it took was a quick modification to the Rakefile.

Gavin Morrice


Gavin Morrice


Over 300 content creators. Join our team.