Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

initial revision

  • Loading branch information...
commit ec790c57752162f2d5818abdbd00af7f2764ae42 0 parents
authored June 01, 2012

Showing 38 changed files with 1,219 additions and 0 deletions. Show diff stats Hide diff stats

  1. 1  .gitignore
  2. 42  README.rdoc
  3. 13  Rakefile
  4. 61  articles/cocoapods/index.txt
  5. 82  articles/testflight/index.txt
  6. BIN  guides/getting-started/images/hello.png
  7. BIN  guides/getting-started/images/xcode-prefs-download.png
  8. BIN  guides/getting-started/images/xcode-search.png
  9. BIN  guides/getting-started/images/xcode-search2.png
  10. 161  guides/getting-started/index.txt
  11. 371  guides/project-management/index.txt
  12. 483  guides/runtime/index.txt
  13. 5  icons/README
  14. BIN  icons/callouts/1.png
  15. BIN  icons/callouts/10.png
  16. BIN  icons/callouts/11.png
  17. BIN  icons/callouts/12.png
  18. BIN  icons/callouts/13.png
  19. BIN  icons/callouts/14.png
  20. BIN  icons/callouts/15.png
  21. BIN  icons/callouts/2.png
  22. BIN  icons/callouts/3.png
  23. BIN  icons/callouts/4.png
  24. BIN  icons/callouts/5.png
  25. BIN  icons/callouts/6.png
  26. BIN  icons/callouts/7.png
  27. BIN  icons/callouts/8.png
  28. BIN  icons/callouts/9.png
  29. BIN  icons/caution.png
  30. BIN  icons/example.png
  31. BIN  icons/home.png
  32. BIN  icons/important.png
  33. BIN  icons/next.png
  34. BIN  icons/note.png
  35. BIN  icons/prev.png
  36. BIN  icons/tip.png
  37. BIN  icons/up.png
  38. BIN  icons/warning.png
1  .gitignore
... ...
@@ -0,0 +1 @@
  1
+*.html
42  README.rdoc
Source Rendered
... ...
@@ -0,0 +1,42 @@
  1
+= RubyMotion Documentation
  2
+
  3
+This repository contains the official documentation of RubyMotion, a
  4
+commercial toolchain for iOS development in Ruby.
  5
+
  6
+The files in this repository are used to build the Developer Center section
  7
+of the RubyMotion website.
  8
+
  9
+http://www.rubymotion.com/developer-center
  10
+
  11
+== Setup
  12
+
  13
+Documentation is written using the AsciiDoc text document format. You can find more information about AsciiDoc on its website: http://www.methods.co.nz/asciidoc
  14
+
  15
+We use the Mizuho tool to build the documentation. Mizuho conveniently includes
  16
+AsciiDoc as well as additional functionality.
  17
+
  18
+  $ sudo gem install mizuho
  19
+
  20
+You can also find the source code of Mizuho on GitHub. Mizuho is a project of
  21
+Hongli Lai of the amazing Phusion folks. https://github.com/FooBarWidget/mizuho
  22
+
  23
+== Usage
  24
+
  25
+The default +rake+ task will build the documentation by creating a +.html+
  26
+file for each +.txt+ file.
  27
+
  28
+  $ rake
  29
+
  30
+== Contributions
  31
+
  32
+Please use the GitHub pull-request mechanism to submit contributions. We will
  33
+refresh the RubyMotion website on a periodical basis.
  34
+
  35
+Thanks a lot in advance!
  36
+
  37
+== License
  38
+
  39
+This documentation is licensed under a Creative Commons Attribution 3.0
  40
+Unported License.
  41
+
  42
+http://creativecommons.org/licenses/by/3.0/
13  Rakefile
... ...
@@ -0,0 +1,13 @@
  1
+task :default => :all
  2
+
  3
+task :all do
  4
+  Dir.glob('**/*.txt').each do |src|
  5
+    Dir.chdir(File.dirname(src)) do
  6
+      src = File.basename(src)
  7
+      dest = src.sub(/\.txt/, '.html')
  8
+      if !File.exist?(dest) or File.mtime(src) > File.mtime(dest)
  9
+        sh "mizuho -a max-width=55em --icons-dir \"../../icons\" \"#{src}\" -o \"#{dest}\""
  10
+      end
  11
+    end
  12
+  end
  13
+end
61  articles/cocoapods/index.txt
... ...
@@ -0,0 +1,61 @@
  1
+Use CocoaPods Dependencies in RubyMotion Apps
  2
+=============================================
  3
+Laurent Sansonetti <lrz@hipbyte.com>
  4
+
  5
+In this article we will cover how you can integrate the http://cocoapods.org[CocoaPods] dependency manager inside your RubyMotion project.
  6
+
  7
+Synopsis
  8
+--------
  9
+
  10
+CocoaPods is the missing dependency manager for Objective-C projects. It is similar to RubyGems but for Objective-C dependencies.
  11
+
  12
+Dependencies in CocoaPods are called Pods. You can get the list of Pods available from the http://github.com/CocoaPods/Specs[CocoaPods/Specs] GitHub repository.
  13
+
  14
+CocoaPods was originally designed to be integrated in Objective-C Xcode projects, but we worked with the awesome CocoaPods author to make it possible to be used in RubyMotion projects.
  15
+
  16
+You can check the http://cocoapods.org website to get more information about CocoaPods.
  17
+
  18
+Installation
  19
+------------
  20
+
  21
+First, you will need to install and setup CocoaPods, unless you already have.
  22
+
  23
+----
  24
+$ sudo gem install cocoapods
  25
+$ pod setup
  26
+----
  27
+
  28
+The RubyMotion CocoaPods integration also comes as a gem. 
  29
+
  30
+----
  31
+$ sudo gem install motion-cocoapods
  32
+----
  33
+
  34
+The code lives in the http://github.com/HipByte/motion-cocoapods[HipByte/motion-cocoapods] GitHub repository.
  35
+
  36
+Usage
  37
+-----
  38
+
  39
+You will need to require the gem inside the 'Rakefile' of your project.
  40
+
  41
+----
  42
+require 'motion-cocoapods'
  43
+----
  44
+
  45
+Once you do that, you can simply use the +pods+ method of the application configuration object to describe the Pods you want to require, by using the same expressions as you would do in a regular Podfile.
  46
+
  47
+For instance, if you want to require the +JSONKit+ Pod.
  48
+
  49
+----
  50
+Motion::Project::App.setup do |app|
  51
+  # ...
  52
+  app.pods do
  53
+    dependency 'JSONKit'
  54
+  end
  55
+end
  56
+----
  57
+
  58
+That's all you have to do.
  59
+
  60
+The next time you build your project, the +JSONKit+ sources will be downloaded then built and linked against your application executable. If you require a Pod that has dependencies, they will also be properly honored.
  61
+
82  articles/testflight/index.txt
... ...
@@ -0,0 +1,82 @@
  1
+Submit RubyMotion Apps to TestFlight
  2
+====================================
  3
+Laurent Sansonetti <lrz@hipbyte.com>
  4
+
  5
+In this article we will cover how you can submit development builds of your RubyMotion apps to http://testflightapp.com[TestFlight].
  6
+
  7
+Synopsis
  8
+--------
  9
+
  10
+TestFlight is a platform that you can use to distribute development builds of your apps to you team members. You receive feedback, console logs and crash reports automatically. It can very useful during the development cycle of an app.
  11
+
  12
+You can create an account on http://testflightapp.com[http://testflightapp.com]. It's free.
  13
+
  14
+Installation
  15
+------------
  16
+
  17
+We recommend the use of the +motion-testflight+ gem which provides a seemingless experience.
  18
+
  19
+----
  20
+$ sudo gem install motion-testflight
  21
+----
  22
+
  23
+The source code of the +motion-testflight+ gem lives on the http://github.com/HipByte/motion-testflight[HipByte/motion-testflight] GitHub repository.
  24
+
  25
+Unpack the SDK
  26
+--------------
  27
+
  28
+You will need to download the TestFlight SDK package from http://testflightapp.com/sdk/download and unpack it into the 'vendor/TestFlightSDK' directory of your RubyMotion project.
  29
+
  30
+Create the 'vendor' directory if it does not exist.
  31
+
  32
+You should then have something like this.
  33
+
  34
+----
  35
+$ ls vendor/TestFlightSDK
  36
+README.txt			libTestFlight.a
  37
+TestFlight.h			release_notes.txt
  38
+----
  39
+
  40
+Change your project configuration
  41
+---------------------------------
  42
+
  43
+You will need to change the 'Rakefile' of your project in order to set up the gem.
  44
+
  45
+First, you need to require the gem. Add the following line at the beginning of the file, right after the other +require+ statements.
  46
+
  47
+----
  48
+require 'motion-testflight'
  49
+----
  50
+
  51
+Now that the gem is loaded, it's time to configure it. Inside your application configuration block, add the following lines.
  52
+
  53
+----
  54
+Motion::Project::App.setup do |app|
  55
+  # ...
  56
+  app.testflight.sdk = 'vendor/TestFlight'
  57
+  app.testflight.api_token = '<insert your API token here>'
  58
+  app.testflight.team_token = '<insert your team token here>'
  59
+end
  60
+----
  61
+
  62
+You can retrieve the values for +api_token+ and +team_token+ from your TestFlight account page.
  63
+
  64
+Optionally, you can use the +distribution_lists+ key if you do want to set up a distribution list for your submissions.
  65
+
  66
+----
  67
+Motion::Project::App.setup do |app|
  68
+  # ...
  69
+  app.testflight.distribution_lists = ['CoolKids']
  70
+end
  71
+----
  72
+
  73
+Usage
  74
+-----
  75
+
  76
+You will see that a new rake task is available, +rake testflight+, which will automatically submit a development build of your app to TestFlight.
  77
+
  78
+The +notes+ argument must be provided, its content will be the actual release notes for the submission.
  79
+
  80
+----
  81
+$ rake testflight notes='zomg!'
  82
+----
BIN  guides/getting-started/images/hello.png
BIN  guides/getting-started/images/xcode-prefs-download.png
BIN  guides/getting-started/images/xcode-search.png
BIN  guides/getting-started/images/xcode-search2.png
161  guides/getting-started/index.txt
... ...
@@ -0,0 +1,161 @@
  1
+Welcome to RubyMotion
  2
+=====================
  3
+Laurent Sansonetti <lrz@hipbyte.com>
  4
+
  5
+
  6
+Thank you for purchasing RubyMotion. This guide will help you getting started with the product.
  7
+
  8
+Overview
  9
+--------
  10
+
  11
+http://www.rubymotion.com[RubyMotion] is a toolchain that permits the development of iOS applications using the Ruby programming language.
  12
+
  13
+http://www.apple.com/ios[iOS] is Apple's mobile operating system, powering a variety of devices such as iPhone, iPod touch and iPad. Developers can write applications for iOS and submit them to the App Store, Apple's application distribution system.
  14
+
  15
+Conceptually, RubyMotion is a combination of two major components:
  16
+
  17
+* *Runtime*: a brand-new implementation of the Ruby language, tightly integrated with the native iOS runtime and optimized for embedded iOS device constraints.
  18
+* *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.
  19
+
  20
+RubyMotion installs itself into '/Library/RubyMotion'. A symbolic link to the command-line interface is created as '/usr/bin/motion'.
  21
+
  22
+Prerequisites
  23
+-------------
  24
+
  25
+RubyMotion requires a Mac running OSX 10.6 or higher. OSX 10.7 Lion however is highly recommended.
  26
+
  27
+You will need to install the iOS SDK on your machine. These days the iOS SDK comes with Xcode. Xcode can be downloaded and installed for free using the App Store application.
  28
+
  29
+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.
  30
+
  31
+Open the 'App Store' application then search for "Xcode" in the search field.
  32
+
  33
+image:/developer-center/guides/getting-started/images/xcode-search.png["Searching for Xcode in the App Store"]
  34
+
  35
+Find 'Xcode' from the result, then click on it.
  36
+
  37
+image:/developer-center/guides/getting-started/images/xcode-search2.png["Searching for Xcode in the App Store"]
  38
+
  39
+That should open a new page where you can download Xcode. 
  40
+
  41
+Once Xcode is installed, you will need to install the Command Line Tools package, required by RubyMotion.
  42
+
  43
+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 from the list, make sure to hit the 'Install' button.
  44
+
  45
+image:/developer-center/guides/getting-started/images/xcode-prefs-download.png["Installing the Command Line Tools package"]
  46
+
  47
+Okay, you should be all set now! You can close Xcode.
  48
+
  49
+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.
  50
+
  51
+----
  52
+$ sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
  53
+----
  54
+
  55
+Software Updates
  56
+----------------
  57
+
  58
+Software updates can be applied via the command-line.
  59
+
  60
+The following command will grab the latest version of RubyMotion from the network and install it. You must be connected to the Internet to perform that command.
  61
+
  62
+----
  63
+$ sudo motion update
  64
+----
  65
+
  66
+You can always see the version number of the version of RubyMotion installed on the computer.
  67
+
  68
+----
  69
+$ motion -v
  70
+1.0
  71
+----
  72
+
  73
+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, and accordingly prints a message on your terminal, suggesting you to upgrade.
  74
+
  75
+Support
  76
+-------
  77
+
  78
+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.
  79
+
  80
+----
  81
+$ motion support
  82
+----
  83
+
  84
+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.
  85
+
  86
+Hello World
  87
+-----------
  88
+
  89
+We are now ready to write our first RubyMotion program: Hello World.
  90
+
  91
+Open your terminal and go to a place where you would like this first project to be created, then type the following command.
  92
+
  93
+----
  94
+$ motion create Hello
  95
+----
  96
+
  97
+This command will create a RubyMotion project in a new directory, called Hello. If this directory already exists or cannot be created, the command will fail.
  98
+
  99
+Let's have a look inside.
  100
+
  101
+----  
  102
+$ cd Hello
  103
+$ ls
  104
+Rakefile app resources spec
  105
+----
  106
+
  107
+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.
  108
+
  109
+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.
  110
+
  111
+Let's run the default task.
  112
+
  113
+----
  114
+$ rake
  115
+----
  116
+
  117
+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!
  118
+
  119
+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.
  120
+
  121
+----
  122
+class AppDelegate
  123
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
  124
+    true
  125
+  end
  126
+end
  127
+----
  128
+
  129
+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.
  130
+
  131
+----
  132
+class AppDelegate
  133
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
  134
+    alert = UIAlertView.new
  135
+    alert.message = "Hello World!"
  136
+    alert.show
  137
+    true
  138
+  end
  139
+end
  140
+----
  141
+
  142
+If you run the +rake+ command again from the terminal, you should be able to see the alert in the simulator.
  143
+
  144
+image:/developer-center/guides/getting-started/images/hello.png["Hello World"]
  145
+
  146
+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.
  147
+
  148
+----
  149
+$ rake device
  150
+----
  151
+
  152
+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.
  153
+
  154
+Congratulations, you successfully created your first RubyMotion program. That wasn’t too hard, was it?
  155
+
  156
+And Now?
  157
+--------
  158
+
  159
+You will find sample code in the https://github.com/HipByte/RubyMotionSamples[Sample Code Repository] on GitHub. Each of the sub-folders is a RubyMotion project as introduced above. You can type +rake+ from their directory to build and run them and check their source code by reading the files in the 'app' directory.
  160
+
  161
+Make sure to check the link:/developer-center[Developer Center] for more resources, such as guides, articles and screencasts.
371  guides/project-management/index.txt
... ...
@@ -0,0 +1,371 @@
  1
+RubyMotion Project Management Guide
  2
+===================================
  3
+Laurent Sansonetti <lrz@hipbyte.com>
  4
+
  5
+In this guide we will explain how to create new RubyMotion projects, then configure and maintain them.
  6
+
  7
+Creation
  8
+--------
  9
+
  10
+To create a new RubyMotion project, pass the +create+ command to '/usr/bin/motion'. It will create a new project directory.
  11
+
  12
+----
  13
+$ motion create Hello
  14
+$ cd Hello
  15
+$ ls
  16
+Rakefile app resources spec
  17
+----
  18
+
  19
+Project Anatomy
  20
+~~~~~~~~~~~~~~~
  21
+
  22
+The following table illustrates the anatomy of a project directory.
  23
+
  24
+[options="header,autowidth"]
  25
+|=========================
  26
+| File/Directory | Purpose 
  27
+| 'Rakefile' | This file contains the configuration of the project, as well as a default set of tasks. It can be edited to change the configuration or add new tasks.
  28
+| '.gitignore' | This file contains file patterns that should be ignored by the source control management software (for instance, build files). This file is used by Git, but it can be ported to other SCMs.
  29
+| 'app/' | This directory contains the Ruby code of the project. In a new project, a 'main.rb' file is created automatically.
  30
+| 'resources/' | This directory contains the resources files of the project, such as images or sounds. In a new project, this directory is empty.
  31
+|'spec/' | This directory contains the specification files of the application. In a new project, a default specification file is created automatically.
  32
+|=========================
  33
+
  34
+RubyMotion projects are based on Rake. Essential rake tasks will be covered in the following sections. To see the full list of available tasks:
  35
+
  36
+----
  37
+$ rake -T
  38
+----
  39
+
  40
+TIP: Rake is the de-facto build system framework for Ruby. It is similar to make and ships by default in OSX.
  41
+
  42
+Configuration
  43
+-------------
  44
+
  45
+The +rake config+ task will dump the project configuration. Each configuration variable has a sensible default value that can be manually overriden in the 'Rakefile' file.
  46
+
  47
+[options="header,autowidth"]
  48
+|====
  49
+| Variable | Discussion
  50
+|+name+ | Project name, as a +String+. The default value is the name passed to +motion create+.
  51
+|+version+ | Project version, as a +String+. The default value is +"1.0"+.
  52
+|+identifier+ | Project identifier, as a +String+, in reverse DNS format. The default value is the concatenation of +"com.yourcompany."+ and the +name+ variable.
  53
+|+delegate_class+ | Name of the application delegate class, as a +String+. The default value is +"AppDelegate"+ and the class is defined in 'app/main.rb'.
  54
+|+files+ | Project files, as an +Array+. The default value is the result of the following expression: +Dir.glob('./app/**/*.rb')+ (every '.rb' file in the 'app' directory).
  55
+|+frameworks+ | The names of iOS frameworks to link against, as an +Array+. It should contain the names of public iOS frameworks, typically present in '/System/Library/Frameworks'. The build system is capable of dealing with dependencies, for instance there is no need to mention +"CoreFoundation"+ if you have +"Foundation"+. The default value is +['UIKit', 'Foundation', 'CoreGraphics']+.
  56
+| +libs+ | Library paths to link against, as an +Array+. It should contain paths to public, system libraries, for example +"/usr/lib/libz.dylib"+. The default value is +[]+, an empty array.
  57
+|+build_dir+ | Path to the directory for build products, as a +String+. It must be relative to the project directory. The directory will be created by the build system if it does not exist yet. If it cannot be created, a temporary directory will be used instead. The default value is +"build"+.
  58
+|+resources_dir+ | Directory for resources files, as a +String+. It must be relative to the project directory. The default value is +"resources"+.
  59
+|+specs_dir+ | Directory for specification files, as a +String+. It must be relative to the project directory. The default value is +"spec"+.
  60
+|+icons+ | List of names of resource files to use for icons, as an +Array+. For example, +["Icon.png", "Icon-72.png", "Icon@2x.png"]+. The files must conform to the http://developer.apple.com/library/ios/#documentation/userexperience/conceptual/mobilehig/IconsImages/IconsImages.html[HIG guidelines]. The default value is +[]+, an empty array.
  61
+|+fonts+ | List of names of font files in the resources directory, as an +Array+. For example, +["Inconsolata.otf"]+. The fonts will then be properly taken into account when generating the application. The default value is the list of all '.ttf' and '.otf' files in the resources directory. It is recommended to keep the default value.
  62
+|+prerendered_icon+ | Whether the image files in +icons+ are already pre-rendered according to the HIG guidelines. If +false+, iOS will apply a reflective shine effect on the icons. The default value is +false+.
  63
+|+device_family+ | Family of devices to support. Possible values can be: +iphone+, +ipad+ or +[:iphone, :ipad]+ (for a universal application). The default value is +:iphone+.
  64
+|+interface_orientations+ | Supported interface orientations. Value must be an +Array+ of one or more of the following symbols: +:portrait+, +:landscape_left+, :+landscape_right+:, and +:portrait_upside_down+. The default value is +[:portrait, :landscape_left, :landscape_right]+.
  65
+|+xcode_dir+ | Directory where Xcode is installed, as a +String+. The default value is determined by the returned value of '/usr/bin/xcode-select -printPath', or, if invalid, '/Applications/Xcode.app/Contents/Developer'. Giving a new value to this setting must be done first, before changing other settings.
  66
+|+sdk_version+ | Version number of the SDK to use, as a +String+. The default value is the version number of the most recent supported SDK in +xcode_dir+. Example: +"5.0"+.
  67
+|+deployment_target+ | Version number of the SDK to target, as a +String+. The default value is the value of +sdk_version+, but can be lowered to target older versions of iOS. Example: +"4.3"+.
  68
+|+codesign_certificate+ | The name of the certificate to use for codesigning, as a +String+. The default value is the first iPhone Developer certificate found in keychain. Example: +"iPhone Developer: Darth Vader (A3LKZY369Q)"+.
  69
+|+provisioning_profile+ | Path to the provisioning profile to use for deployment, as a +String+. The default value is the first '.mobileprovision' file found in '~/Library/MobileDevice/Provisioning'.
  70
+|+seed_id+ | The application provisioning identifier, as a +String+. It is a unique (within the App Store) 10 characters identifier generated by the provisioning portal. The default value is the first application identifier found in +provisioning_profile+.
  71
+|====
  72
+
  73
+Custom values for the configuration settings can be added by tweaking the +Motion::App.setup+ block in the +Rakefile+ file.
  74
+
  75
+As an example, let's take the configuration block of a fictional video player application for the iPad. The device family setting has to change from its default value, iPhone, to iPad. Also, the application makes use of an additional framework, AVFoundation, for audio-video functionality.
  76
+
  77
+----
  78
+Motion::Project::App.setup do |app|
  79
+  app.name = 'Awesome Video Player'
  80
+  app.device_family = :ipad
  81
+  app.frameworks += ['AVFoundation']
  82
+end
  83
+----
  84
+
  85
+Files Dependencies
  86
+~~~~~~~~~~~~~~~~~~
  87
+
  88
+By default, RubyMotion will compile files in the regular sorting order of the filesystem. When a RubyMotion application starts, the main scope of each file will then be executed in that specific order.
  89
+
  90
+Sometimes, you will want to customize the order, if for instance one file makes use of a constant defined in another.
  91
+
  92
+----
  93
+$ cat app/foo.rb
  94
+class Foo
  95
+end
  96
+$ cat app/bar.rb
  97
+class Bar < Foo
  98
+end
  99
+----
  100
+
  101
+In the example above, using the default order, 'bar.rb' will be compiled before 'foo.rb' resulting in a constant lookup error, because the +Foo+ constant has not been defined yet when we execute the code in 'bar.rb'.
  102
+
  103
+To fix that problem, the +files_dependencies+ method can be used in the 'Rakefile'. This method accepts a +Hash+ which should be a set of files dependencies.
  104
+
  105
+----
  106
+Motion::Project::App.setup do |app|
  107
+  # ...
  108
+  app.files_dependencies 'app/bar.rb' => 'app/foo.rb'
  109
+end
  110
+----
  111
+
  112
+After this change, the build system will compile 'foo.rb' before 'bar.rb'.
  113
+
  114
+Using 3rd-Party Libraries
  115
+~~~~~~~~~~~~~~~~~~~~~~~~~
  116
+
  117
+The iOS SDK has a significant amount of functionality built-in that one can use from a RubyMotion project, however, sometimes you will have to use a 3rd-party library that provides a missing feature of iOS.
  118
+
  119
+To vendor a 3rd-party library in a RubyMotion project, the source code must be available somewhere on the filesystem. It is recommended to keep the 3rd-party libraries required by the project at the same place, for instance under a 'vendor' directory.
  120
+
  121
+The +vendor_project+ method can be called from the 'Rakefile'. Its first argument must be the path to the 3rd-party library, for example +"vendor/OAuth2Client"+. Its second argument must be a symbol representing the project type, like +:xcode+. Other arguments can be provided as a list of key/value objects.
  122
+
  123
+Here is a table summarizing project types and key/value objects.
  124
+
  125
+[cols=".^,.^,.^",options="header,autowidth"]
  126
+|====
  127
+| Project Type | Key | Discussion
  128
+.6+|+:xcode+ | +:xcodeproj+ | Name of the Xcode project file to use. Optional if there is one '.xcodeproj' file in the directory.
  129
+| +:target+ | Name of the target to build. If not provided, the default target will be used. Cannot be used at the same time than +:scheme+.
  130
+| +:scheme+ | Name of the scheme to build. If not provided, the default scheme will be used. Cannot be used at the same time than +:target+.
  131
+| +:configuration+ | Name of the configuration to build. If not provided, +"Release"+ will be used.
  132
+| +:headers_dir+ | Path to the directory that contains public headers files, declaring APIs that will be used by the RubyMotion project. The path should be relative to the path provided to +vendor_project+, for example +"Sources/Headers"+. This key is optional.
  133
+| +:products+ | An +Array+ containing the names of products to use in the RubyMotion project, for example +["libfoo.a"]+. This key can be used when the project builds more than one product and you want to filter what will be used by the app. If not provided, all +.a+ libraries built will be used.
  134
+.2+| +:static+ | +:products+ | An +Array+ containing the names of static libraries to use. The default value is the list of all '.a' files in the vendor project directory.
  135
+| +:headers_dir+ | Path to the directory that contains public headers files, declaring APIs that will be used by the RubyMotion project. The path should be relative to the path provided to +vendor_project+, for example +"include"+. The default value is the vendor project directory.
  136
+|====
  137
+
  138
+As an example, assuming our video player project wants to make use of the OAuth2Client 3rd-library library, a 'vendor' directory would be created and the OAuth2Client source code would be added there.
  139
+
  140
+----
  141
+$ cd AwesomeVideoPlayer
  142
+$ ls vendor
  143
+OAuth2Client
  144
+----
  145
+
  146
+Then, the 'Rakefile' can be modified as such. 
  147
+
  148
+----
  149
+Motion::Project::App.setup do |app|
  150
+  # ...
  151
+  app.vendor_project('vendor/OAuth2Client', :xcode,
  152
+      :target => 'OAuth2Client',
  153
+      :headers_dir => 'Sources/OAuth2Client')
  154
+  app.frameworks << 'Security' # OAuth2Client depends on Security.framework
  155
+end
  156
+----
  157
+
  158
+Entitlements
  159
+~~~~~~~~~~~~
  160
+
  161
+Entitlements confer specific capabilities or security permissions to an application. You may be required by Apple to request an entitlement when trying to access a specific feature of the system.
  162
+
  163
+An application running on an iOS device that does not have the proper entitlement for a functionality will fail at runtime when trying to use such functionality. It will also not be accepted into the App Store.
  164
+
  165
+Entitlements are used during the code-signing part of the build process.
  166
+
  167
+The +entitlements+ method of the 'Rakefile' configuration object returns an empty +Hash+ object by default, that you can modify to set appropriate keys and values.
  168
+
  169
+For instance, our video player might require access to the keychain to store the user credentials. According to the documentation, the +keychain-access-groups+ entitlement must be requested, passing a combination of the application provisioning identifier and the application identifier, respectively exposed as +seed_id+ and +identifier+ in RubyMotion.
  170
+
  171
+----
  172
+Motion::Project::App.setup do |app|
  173
+  # ...
  174
+  app.entitlements['keychain-access-groups'] = [
  175
+    app.seed_id + '.' + app.identifier
  176
+  ]
  177
+end
  178
+----
  179
+
  180
+Advanced Info.plist Settings
  181
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  182
+
  183
+An iOS app has its configuration described into the 'Info.plist' file, which is located inside the application bundle. This file contains a set of keys and values. It is fully documented in the http://developer.apple.com/library/ios/#documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html[Info.plist reference] guide.
  184
+
  185
+In a RubyMotion project, the 'Info.plist' file is derived from the configuration object exposed in the 'Rakefile' file. For example, the +CFBundleName+ variable in 'Info.plist' is derived from the +name+ variable in the 'Rakefile'. Most of the time, the configuration object will let you control the necessary settings of his project.
  186
+
  187
+However, it might happen that you will want to change an advanced setting of a project. The 'Rakefile' interface does not cover all the possible settings, but it exposes the internal 'Info.plist' data structure that one can modify if needed.
  188
+
  189
+As an example, our video player might need to register a custom URI scheme, so that it can open custom URLs from the web browser, for instance, +x-videoplayer://play+. The 'Rakefile' configuration object does not provide support for this.
  190
+
  191
+The reference suggests that the +CFBundleURLTypes+ key should be used. The key can be manually set by using the +info_plist+ method, which returns a mutable +Hash+ object.
  192
+
  193
+----
  194
+Motion::Project::App.setup do |app|
  195
+  # ...
  196
+  app.info_plist['CFBundleURLTypes'] = [
  197
+    { 'CFBundleURLName' => 'com.mycompany.x-videoplayer',
  198
+      'CFBundleURLSchemes' => ['x-videoplayer'] }
  199
+  ]
  200
+end
  201
+----
  202
+
  203
+Build
  204
+-----
  205
+
  206
+The +rake build+ task builds the project into the temporary 'build' directory. Two different versions of the project will be built, one to run in the iOS simulator (on the Mac itself) and one to run on the iOS device.
  207
+
  208
+The following steps are performed during the build process:
  209
+
  210
+. It compiles each Ruby source code file into optimized machine code, translating the Ruby syntax tree into an intermediate representation language (using http://llvm.org[LLVM]), then assembly. The compiler will generate code for either the Intel 32-bit (+i386+) or ARM (+armv6+, +armv7+) instruction sets and ABIs depending on the target.
  211
+. It links the machine code with the RubyMotion runtime statically to form an executable. The linker also includes metadata for the C APIs that the project uses, as well as 3rd-party libraries vendored from the configuration.
  212
+. It creates an '.app' bundle and copies the executable there. The 'Info.plist' file is generated based on the project configuration. Each resource file in the 'resources' directory is copied in the bundle. Old resource files, that have been deleted since from the project, will not be present in the application bundle.
  213
+. It codesigns the bundle based on the certificate, the provisioning profile and the entitlements specified in the project configuration.
  214
+
  215
+Normally the user does not need to explicitly build the project, as the 'build' task is a dependency of the other tasks.
  216
+
  217
+Parallel Compilation
  218
+~~~~~~~~~~~~~~~~~~~~
  219
+
  220
+The compilation of Ruby source files into machine code takes a non-negligeable amount of time.
  221
+
  222
+If the machine used to build the project runs a multicore processor, which is very likely these days, the build system will try to spread the compilation tasks in parallel. This can be very useful when building a project that contains a significant number of files.
  223
+
  224
+The build system uses the value of the +machdep.cpu.thread_count+ sysctl kernel variable to determine  know how many compilation tasks can be executed in parallel. For example, a MacBook Pro running an Intel Core i7 processor has 4 available cores, each one being able to run 2 concurrent threads, and the build system will therefore compile 8 files at a time.
  225
+
  226
+It is possible to override the number of concurrent jobs the build system should use by setting the +jobs+ environment variable. It can be set to a lower number if for instance the machine is performing another CPU intensive task that should not be interrupted by the build system.
  227
+
  228
+----
  229
+$ rake jobs=1        # Force compilation tasks to be sequential.
  230
+----
  231
+
  232
+Cleaning
  233
+~~~~~~~~
  234
+
  235
+The +rake clean+ task empties the 'build' directory and clean the build directories of the vendored projects.
  236
+
  237
+----
  238
+$ rake clean
  239
+----
  240
+
  241
+Simulation
  242
+----------
  243
+
  244
+The +rake simulator+ task builds the project for the iOS simulator, and runs the application in the simulator.
  245
+
  246
+The default +rake+ task is a shortcut to +rake simulator+.
  247
+
  248
+----
  249
+$ rake simulator
  250
+$ rake
  251
+----
  252
+
  253
+Interactive Console
  254
+~~~~~~~~~~~~~~~~~~~
  255
+
  256
+An interactive shell, similar to Ruby's own +irb+ command, is available when you run your app through the iOS simulator.
  257
+
  258
+You can evaluate any expression in the shell. The shell does not block the app from running, but expressions typed into it will be sent to the app which will execute them in the main thread.
  259
+
  260
+NOTE: The REPL (read-eval-print-loop) support is loaded at demand in the app. By default, an app built for the simulator does not contain any more code than an app built for an iOS device.
  261
+
  262
+You can type +help+ to get more information about the builtin expressions.
  263
+
  264
+The interactive shell also features a way to select views in the simulator. Maintain the +command+ key then move your mouse over the simulator window and you should see red borders around views you are selecting as well as the object in the shell. Once you click, the shell will open a new session whose context (the +self+ object) is the view you selected.
  265
+
  266
+Universal Applications
  267
+~~~~~~~~~~~~~~~~~~~~~~
  268
+
  269
+A universal application targets both the iPhone and iPad device families (see the +device_family+ project configuration setting for more details).
  270
+
  271
+In this case, it can be convenient to specify which device family the simulator should use. By default, the simulator will use the first device family provided in the project configuration setting.
  272
+
  273
+The +device_family+ environment variable can be set to either +iphone+ or +ipad+ to change this default. For example, forcing a universal application to run on the iPad.
  274
+
  275
+----
  276
+$ rake simulator device_family=ipad
  277
+----
  278
+
  279
+Cleaning the Sandbox
  280
+~~~~~~~~~~~~~~~~~~~~
  281
+
  282
+Each application lives in its own directory inside the iOS simulator sandbox. This directory contains the application bundle, but also the 'Documents' and 'Library' folders, which store its filesystem state. When running an application through the simulator, the sandbox will be created if it doesn't exist, otherwise, the application will be copied into the existing sandbox.
  283
+
  284
+Sometimes, you may want to clean the application sandbox before running the simulator, in order to start from a fresh state. For instance, if resource files are removed from the project, or if the application has state data that has to be cleaned up.
  285
+
  286
+To perform that, the +clean+ environment variable can be set to any value, which will trigger the removal of the application sandbox before running the simulator.
  287
+
  288
+----
  289
+$ rake simulator clean=1
  290
+----
  291
+
  292
+Testing
  293
+-------
  294
+
  295
+RubyMotion has built-in http://en.wikipedia.org/wiki/Behavior_Driven_Development[Behavior-Driven Development] functionality that you can use to cover the specifications of an application. RubyMotion uses a flavor of the http://github.com/alloy/MacBacon[Bacon] framework slightly modified to integrate better with the iOS system.
  296
+ 
  297
+Specification files are written in the 'spec' directory.
  298
+
  299
+The +rake spec+ task will build a special version of the project that will execute all specification files right after the application launches. A summary will then be printed on the standard output terminal, and the application will exit.
  300
+
  301
+Note: +rake spec+ currently only works with the simulator.
  302
+
  303
+Specification files have full access to the iOS SDK as well as the application classes. Here is a spec that makes sure the application has one active window.
  304
+
  305
+----
  306
+$ cat spec/main_spec.rb 
  307
+describe "My Awesome App" do
  308
+  it "has a window" do
  309
+    app = UIApplication.sharedApplication
  310
+    app.windows.size.should == 1
  311
+  end
  312
+end
  313
+----
  314
+
  315
+Assuming the application is properly implemented to follow that specification, +rake spec+ will gracefully exit with a status error of 0.
  316
+
  317
+----
  318
+$ rake spec
  319
+...
  320
+My Awesome App
  321
+  - has a window
  322
+
  323
+1 specifications (1 requirements), 0 failures, 0 errors
  324
+----
  325
+
  326
+Archiving
  327
+---------
  328
+
  329
+RubyMotion projects can be archived in order to be distributed and submitted to the App Store.
  330
+
  331
+Development vs Release
  332
+~~~~~~~~~~~~~~~~~~~~~~
  333
+
  334
+A RubyMotion project can be built for development or release. A project is built for development when you run it in the simulator, or push it to your development device. A project is built for release when you're generating an archive for an App Store submission.
  335
+
  336
+Currently, the only difference between a RubyMotion app built for release and one built for development is that all symbols are stripped from the main executable. This process removes about 1MB of data from the app bundle, but at the same time, makes debugging more difficult, which is why it's not applied in development. 
  337
+
  338
+Sometimes, you want to apply different settings in the 'Rakefile' if the project builds for release. This can be done by using the +development+ and +release+ methods on the configuration object, which will yield the given block in case the project builds for the appropriate mode.
  339
+
  340
+----
  341
+Motion::Project::App.setup do |app|
  342
+  # ...
  343
+  app.development do
  344
+    # This entitlement is required during development but must not be used for release.
  345
+    app.entitlements['get-task-allow'] = true
  346
+  end
  347
+end
  348
+----
  349
+
  350
+Install on Device
  351
+~~~~~~~~~~~~~~~~~
  352
+
  353
+The +rake device+ task builds and uploads a development archive of the application to an iOS device.
  354
+
  355
+There must be one iOS device connected via USB to the Mac. The deployment task will attempt to upload the application to the first discovered iOS device on the USB channel.
  356
+
  357
+The process will fail in the following cases:
  358
+
  359
+* No iOS device was found on USB.
  360
+* The project builds on a version of iOS greater than the version of iOS running on the device.
  361
+* The project doesn't use the appropriate certificate and provisioning profile linked to the device.
  362
+* There is a USB connection issue when talking to the device.
  363
+
  364
+Otherwise, the process returns successfully and the application is then available on the device springboard.
  365
+
  366
+Distribution
  367
+~~~~~~~~~~~~
  368
+
  369
+The +rake archive+ task can be used to generate '.ipa' archives for both development and release modes. An '.ipa' archive is suitable for ad-hoc distribution and can also be used for a submission to the App Store.
  370
+
  371
+The task requires a valid certificate and provisioning profile in order to codesign the app bundle.
483  guides/runtime/index.txt
... ...
@@ -0,0 +1,483 @@
  1
+RubyMotion Runtime Guide
  2
+========================
  3
+Laurent Sansonetti <lrz@hipbyte.com>
  4
+
  5
+The RubyMotion runtime implements the Ruby language functionality required during the execution of an application. The object model, builtin classes and memory management system are part of the runtime.
  6
+
  7
+Although similar in appearance, the RubyMotion runtime has a completely different implementation than http://www.ruby-lang.org/en/[CRuby], the mainstream implementation (which is also called MRI, or simply Ruby). We will cover the main differences in the following sections.
  8
+
  9
+The key feature of the RubyMotion runtime is its tight integration with iOS, which makes it suitable to power efficient applications.
  10
+
  11
+RubyMotion follows the Ruby 1.9 language specifications.
  12
+
  13
+Object Model
  14
+------------
  15
+
  16
+The object model of RubyMotion is based on http://en.wikipedia.org/wiki/Objective-C[Objective-C], the underlying language runtime of the iOS SDK. Objective-C is an object-oriented flavor of C that has been, like Ruby, heavily influenced by the http://en.wikipedia.org/wiki/Smalltalk[Smalltalk] language.
  17
+
  18
+Sharing a common ancestor, the object models of Ruby and Objective-C are conceptually similar. For instance, both languages have the notion of open classes, single inheritance and single dynamic message dispatch. 
  19
+
  20
+RubyMotion implements the Ruby object model by using the http://developer.apple.com/library/ios/#documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html[Objective-C runtime], the library that powers the Objective-C language and indirectly, the iOS SDK APIs.
  21
+
  22
+In RubyMotion, Ruby classes, methods and objects are respectively Objective-C classes, methods and objects. And reciprocally, Objective-C classes, methods and objects are available in Ruby as if they were native.
  23
+
  24
+By sharing the same object model infrastructure, Objective-C and RubyMotion APIs can be interchangeable at no additional performance expense.
  25
+
  26
+Objective-C Messages
  27
+~~~~~~~~~~~~~~~~~~~~
  28
+
  29
+RubyMotion lets you send and define Objective-C messages.
  30
+
  31
+An Objective-C message, also called a selector, can look different than a typical Ruby message, if it contains more than one argument.
  32
+
  33
+Unlike Ruby messages, Objective-C messages contain keywords. Each argument has a keyword associated to it and the final Objective-C message is the combination of all keywords.
  34
+
  35
+Let's take the following piece of Objective-C code which draws a string.
  36
+
  37
+----
  38
+[string drawAtPoint:point withFont:font];
  39
+----
  40
+
  41
+In this code, +string+, +point+ and +font+ are variables. The message keywords are +drawAtPoint:+ and +withFont:+. The complete message is the combination of these keywords, +drawAtPoint:withFont:+ , which is sent to the +string+ object, passing the +point+ and +font+ objects as arguments.
  42
+
  43
+Objective-C messages can be sent from RubyMotion using a similar syntax.
  44
+
  45
+----
  46
+string.drawAtPoint(point, withFont:font)
  47
+----
  48
+
  49
+It is important to keep in mind that the message being sent here is +drawAtPoint:withFont:+. To illustrate more, the same message can be manually dispatched using the +send+ method.
  50
+
  51
+----
  52
+string.send(:'drawAtPoint:withFont:', point, font)
  53
+----
  54
+
  55
+Objective-C messages can also be defined in RubyMotion. Let's imagine we are building a class that should act as a proxy for our drawing code. The following piece of code defines the +drawAtPoint:withFont:+ message on the +DrawingProxy+ class.
  56
+
  57
+----
  58
+class DrawingProxy
  59
+  def drawAtPoint(point, withFont:font)
  60
+    @str.drawAtPoint(point, withFont:font)
  61
+  end
  62
+end
  63
+----
  64
+
  65
+TIP: The syntax used to define Objective-C selectors was added to RubyMotion and is not part of the Ruby standard.
  66
+
  67
+Objective-C Interfaces
  68
+~~~~~~~~~~~~~~~~~~~~~~
  69
+
  70
+As Objective-C is the main language used to describe the iOS SDK, it is necessary to understand how to read Objective-C interfaces and how to use them from Ruby.
  71
+
  72
+Objective-C interfaces can be found in Apple's iOS API reference and also in the iOS framework header (+.h+) files. 
  73
+
  74
+An Objective-C interface starts with either the minus or plus character, which is used to respectively declare instance or class methods. 
  75
+
  76
+For instance, the following interface declares the +foo+ instance method on the +Foo+ class.
  77
+
  78
+----
  79
+@class Foo
  80
+- (id)foo;
  81
+@end
  82
+----
  83
+
  84
+The next one declares the +foo+ class method on the same class.
  85
+
  86
+----
  87
+@class Foo
  88
++ (id)foo;
  89
+@end
  90
+----
  91
+
  92
+NOTE: +(id)+ is the type information. Types are covered in an upcoming section, so you can omit them for now.
  93
+
  94
+As seen in the previous section, arguments in Objective-C methods can be named with a keyword. The sum of all keywords form the message name, or selector.
  95
+
  96
+The following interface declares the +sharedInstanceWithObject:andObject:+ class method on the +Test+ class.
  97
+
  98
+----
  99
+@class Test
  100
++ (id)sharedInstanceWithObject:(id)obj1 andObject:(id)obj2;
  101
+@end
  102
+----
  103
+
  104
+This method can be called from Ruby like this.
  105
+
  106
+----
  107
+# obj1 and obj2 are variables for the arguments.
  108
+instance = Test.sharedInstanceWithObject(obj1, andObject:obj2)
  109
+----
  110
+
  111
+Selector Shortcuts
  112
+~~~~~~~~~~~~~~~~~~
  113
+
  114
+The RubyMotion runtime provides convenience shortcuts for certain Objective-C selectors.
  115
+
  116
+[options="header,autowidth"]
  117
+|===============================
  118
+| Selector            | Shortcut
  119
+| +setFoo:+           | +foo=+
  120
+| +isFoo+             | +foo?+
  121
+| +objectForKey:+     | +[]+
  122
+| +setObject:forKey:+ | +[]=+
  123
+|===============================
  124
+
  125
+As an example, the +setHidden:+ and +isHidden+ methods of +UIView+ can be called by using the +hidden=+ and +hidden?+ shortcuts.
  126
+
  127
+----
  128
+view.hidden = true unless view.hidden?
  129
+----
  130
+
  131
+Builtin Classes
  132
+---------------
  133
+
  134
+Some of the builtin classes of RubyMotion are based on the http://developer.apple.com/library/ios/#documentation/Cocoa/Reference/Foundation/ObjC_classic/_index.html[Foundation framework], the base layer of iOS.
  135
+
  136
+The Foundation framework is an Objective-C framework, but due to the fact that RubyMotion is based on the Objective-C runtime, the classes that it defines can be naturally re-used in RubyMotion.
  137
+
  138
+Foundation class names typically start with the +NS+ prefix, which arguably stands for NeXTSTEP, the system for which the framework was originally built.
  139
+
  140
+Foundation comes with the root object class, +NSObject+, as well as a set of primitive object classes. In RubyMotion, +Object+ is an alias to +NSObject+, making +NSObject+ the root class of all Ruby classes. Also, some of the builtin classes inherit from Foundation types.
  141
+
  142
+Here is a table showing the ancestors chain of a newly created class, +Hello+, as well as some of the Ruby builtin classes.
  143
+
  144
+[options="header,autowidth"]
  145
+|==================================
  146
+| Ruby Class | Ancestors
  147
+| +Hello+    | +NSObject+ → +Kernel+
  148
+| +String+   | +NSMutableString+ → +NSString+ → +Comparable+ → +NSObject+ → +Kernel+
  149
+| +Array+    | +NSMutableArray+ → +NSArray+ → +Enumerable+ → +NSObject+ → +Kernel+
  150
+| +Hash+     | +NSMutableDictionary+ → +NSDictionary+ → +Enumerable+ → +NSObject+ → +Kernel+
  151
+| +Numeric+  | +Comparable+ → +NSNumber+ → +NSValue+ → +NSObject+ → +Kernel+
  152
+| +Time+     | +Comparable+ → +NSDate+ → +NSObject+ → +Kernel+
  153
+|===================================
  154
+
  155
+A direct consequence of hosting the Ruby builtin classes on Foundation is that instances respond to more messages. For instance, the +NSString+ class defines the +uppercaseString+ method. Since the +String+ class is a subclass of +NSString+, strings created in Ruby also respond to that method.
  156
+
  157
+----
  158
+'hello'.uppercaseString # => 'HELLO
  159
+----
  160
+
  161
+Respectively, the Ruby interface of these builtin classes is implemented on their Foundation counterparts. As an example, +Array+'s +each+ method is implemented on +NSArray+. This allows primitive types to always respond to the same interface, regardless of where they come from. +each+ will always work on all arrays.
  162
+
  163
+----
  164
+def iterate(ary)
  165
+  ary.each { |x| p x }
  166
+end
  167
+
  168
+iterate [42]
  169
+iterate NSArray.arrayWithObject(42)
  170
+----
  171
+
  172
+But the main purpose of this design is to allow the exchange of primitive types between Objective-C and Ruby at no performance cost, since they don't have to be converted. This is important as most of the types that will be exchanged in a typical application are likely going to be builtin types. A +String+ object created in Ruby can have its memory address passed as the argument of an Objective-C method that expects an +NSString+.
  173
+
  174
+Mutability
  175
+~~~~~~~~~~
  176
+
  177
+The Foundation framework ships a set of classes that have both mutable and immutable variants. Mutable objects can be modified, while immutable objects cannot.
  178
+
  179
+Immutable Foundation types in RubyMotion behave like frozen objects (objects which received the +freeze+ message).
  180
+
  181
+As an example, changing the content of an +NSString+ is prohibited and an exception will be raised by the system if doing so. However, it is possible to change the content of an +NSMutableString+ instance.
  182
+
  183
+----
  184
+NSString.new.strip!           # raises RuntimeError: can't modify frozen/immutable string
  185
+NSMutableString.new.strip!    # works
  186
+----
  187
+
  188
+Strings created in RubyMotion inherit from +NSMutableString+, so they can be modified by default. The same goes for arrays and hashes.
  189
+
  190
+However, you must be careful that it is very common for iOS SDK APIs to return immutable types. In these cases, the +dup+ or +mutableCopy+ messages can be sent to the object in order to get a mutable version of it, that can be modified later on.
  191
+
  192
+Interfacing with C
  193
+------------------
  194
+
  195
+You do not need to be a C programmer in order to use RubyMotion, however some basic notions, explained in this section, will be required.
  196
+
  197
+Objective-C is a superset of the C language. Objective-C methods can therefore accept and return C types.
  198
+
  199
+Also, while Objective-C is the main programming language used in the iOS SDK, some frameworks are only available in C APIs.
  200
+
  201
+RubyMotion comes with an interface that allows Ruby to deal with the C part of APIs. 
  202
+
  203
+Basic Types
  204
+~~~~~~~~~~~
  205
+
  206
+C, and indirectly Objective-C, has a set of basic types. It is common in iOS SDK APIs to accept or return these types.
  207
+
  208
+An example are the following methods of +NSFileHandle+, which both respectively accept and return the C integer type, +int+.
  209
+
  210
+----
  211
+- (id)initWithFileDescriptor:(int)fd;
  212
+- (int)fileDescriptor;
  213
+----
  214
+
  215
+Basic C types cannot be created from Ruby directly, but are automatically converted from and to equivalent Ruby types. 
  216
+
  217
+The following piece of code uses the two +NSFileHandle+ methods described above. The first one, +initWithFileDescriptor:+, is called by passing a +Fixnum+. The second one, +fileDescriptor+, is called and a +Fixnum+ is returned back to Ruby.
  218
+
  219
+----
  220
+handle = NSFileHandle.alloc.initWithFileDescriptor(2)
  221
+handle.fileDescriptor # => 2
  222
+----
  223
+
  224
+This table describes all basic C types and discusses how they are converted from and to Ruby types.
  225
+
  226
+[options="header,autowidth"]
  227
+|=========================================
  228
+| C Type | From Ruby to C | From C to Ruby
  229
+| +bool+ .2+.^| If the object is +false+ or +nil+, +false+, otherwise, +true+. Note: the +0+ fixnum will evaluate to +true+. .2+.^| Either +true+ or +false+.
  230
+| +BOOL+
  231
+| +char+ .5+.^| If the object is a +Fixnum+ or a +Bignum+, the value is returned. If the object is +true+ or +false+, +1+ or +0+ are respectively returned. If the object responds to the +to_i+ message, it is sent and the result is returned. .5+.^| Either a +Fixnum+ or a +Bignum+ object.
  232
+| +short+
  233
+| +int+
  234
+| +long+
  235
+| +long_long+
  236
+| +float+ .2+.^| If the object is a +Float+, the value is returned. If the object is +true+ or +false+, +1.0+ or +0.0+ are respectively returned. If the object responds to the +to_f+ message, it is sent and the result is returned. .2+.^| A +Float+ object.
  237
+| +double+
  238
+|=========================================
  239
+
  240
+When using an API that returns the +void+ C type, RubyMotion will return +nil+.
  241
+
  242
+Structures
  243
+~~~~~~~~~~
  244
+
  245
+C structures are mapped to classes in RubyMotion. Structures can be created in Ruby and passed to APIs expecting C structures. Similarly, APIs returning C structures will return an instance of the appropriate structure class.
  246
+
  247
+A structure class has an accessor method for each field of the C structure it wraps.
  248
+
  249
+As an example, the following piece of code creates a +CGPoint+ structure, sets its +x+ and +y+ fields, then passes it to the +drawAtPoint:withFont:+ method.
  250
+
  251
+----
  252
+pt = CGPoint.new
  253
+pt.x = 100
  254
+pt.y = 200
  255
+'Hello'.drawAtPoint(pt, withFont: font)
  256
+----
  257
+
  258
+It is possible to pass the field values directly to the constructor.
  259
+
  260
+----
  261
+pt = CGPoint.new(100, 200)
  262
+'Hello'.drawAtPoint(pt, withFont: font)
  263
+----
  264
+
  265
+RubyMotion will also accept arrays as a convenience. They must contain the same number and type of objects expected in the structure.
  266
+
  267
+----
  268
+'Hello'.drawAtPoint([100, 200], withFont: font)
  269
+----
  270
+
  271
+Enumerations and Constants
  272
+~~~~~~~~~~~~~~~~~~~~~~~~~~
  273
+
  274
+C enumerations and constants are mapped as constants of the +Object+ class.
  275
+
  276
+For instance, both +NSNotFound+ and +CGRectNull+, respectively an enumeration and a constant defined by Foundation, can be directly accessed.
  277
+
  278
+----
  279
+if ary.indexOfObject(obj) == NSNotFound
  280
+  # ...
  281
+end
  282
+# ...
  283
+view = UIView.alloc.initWithFrame(CGRectNull)
  284
+----
  285
+
  286
+IMPORTANT: Some enumerations or constants defined in the iOS SDK may start with a lower-case letter, like +kCLLocationAccuracyBest+ (starting with +k+). Because Ruby constants must always start with a capital letter, their names must be corrected by changing the case of the first letter, becoming +KCLLocationAccuracyBest+ (starting with +K+) in Ruby.
  287
+
  288
+----
  289
+locationManager.desiredAccuracy = kCLLocationAccuracyBest # NameError: undefined local variable or method
  290
+locationManager.desiredAccuracy = KCLLocationAccuracyBest # works
  291
+----
  292
+
  293
+Functions
  294
+~~~~~~~~~
  295
+
  296
+C functions are available as methods of the +Object+ class. Inline functions, which are implemented in the framework header files are also supported.
  297
+
  298
+As an example, the +CGMakePoint+ function can be used in Ruby to create a +CGRect+ structure.
  299
+
  300
+----
  301
+pt = CGMakePoint(100, 200)
  302
+'Hello'.drawAtPoint(pt, withFont: font)
  303
+----
  304
+
  305
+IMPORTANT: Most functions in the iOS SDK start by a capital letter. For those who accept no argument, it is important to explicitely use parentheses when calling them, in order to avoid the expression to be evaluated as a constant lookup.
  306
+
  307
+----
  308
+NSHomeDirectory   # NameError: uninitialized constant NSHomeDirectory
  309
+NSHomeDirectory() # works
  310
+----
  311
+
  312
+Pointers
  313
+~~~~~~~~
  314
+
  315
+Pointers are a very basic data type of the C language. Conceptually, a pointer is a memory address that can point to an object.
  316
+
  317
+In the iOS SDK, pointers are typically used as arguments to return objects by reference. As an example, the +error+ argument of this +NSData+ method expects a pointer that will be set to an +NSError+ object in case of failure.
  318
+
  319
+----
  320
+- (BOOL)writeToFile:(NSString *)path options:(NSDataWritingOptions)mask error:(NSError **)errorPtr
  321
+----
  322
+
  323
+RubyMotion introduces the +Pointer+ class in order to create and manipulate pointers. The type of the pointer to create must be provided in the +new+ constructor. A pointer instance responds to +[]+ to dereference its memory address and +[]=+ to assign it to a new value.
  324
+
  325
+The +NSData+ method above can be used like this in Ruby.
  326
+
  327
+----
  328
+# Create a new pointer to the object type.
  329
+error_ptr = Pointer.new(:object)
  330
+
  331
+unless data.writeToFile(path, options: mask, error: error_ptr)
  332
+  # De-reference the pointer.
  333
+  error = error_ptr[0]
  334
+
  335
+  # Now we can use the `error' object.
  336
+  $stderr.puts "Error when writing data: #{error}"
  337
+end
  338
+----
  339
+
  340
+In the case above, we need a pointer to an object. +Pointer.new+ can also be used to create pointers to various types, including the basic C types, but also structures. 
  341
+
  342
++Pointer.new+ accepts either a +String+, which should be one of the http://developer.apple.com/library/ios/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtTypeEncodings.html[Objective-C runtime types] or a +Symbol+, which should be a shortcut. We recommend the use of shortcuts.
  343
+
  344
+Following is a table summarizing the pointers one can create.
  345
+
  346
+[cols="m,m,m",options="header,autowidth"]
  347
+|=======================================================
  348
+| C Type Pointer | Runtime Type String | Shortcut Symbol
  349
+| id *  | "@" | :object
  350
+| char *  | "c" | :char
  351
+| unsigned char *  | "C" | :uchar
  352
+| short *  | "s" | :short
  353
+| unsigned short *  | "S" | :ushort
  354
+| int *  | "i" | :int
  355
+| unsigned int *  | "I" | :uint
  356
+| long *  | "l" | :long