RubyMotion API Reference, Smart File Dependencies

Time for another significant RubyMotion release! RubyMotion 1.28 is now available featuring a couple interesting new features as well as its traditional set of bug fixes.

RubyMotion API Reference

As RubyMotion compiles down to iOS and uses the exact same APIs as Objective-C, a RubyMotion developer has to discover and learn the official APIs. This is often done by browsing Apple’s official documentation on developer.apple.com. However, users have been complaining that it was not easy enough and that the APIs are still described using the Objective-C syntax.

Well, this used to be a problem, but not anymore. We are now delivering a complete RubyMotion APIs reference in our online developer center.

The documentation has been generated using a modified version of yard, an excellent alternative to RDoc, and should cover the basic iOS frameworks and their APIs. We also cover C-based APIs such as structures, functions, enumerations and constants, as well as Objective-C protocols. Finally, builtin RubyMotion APIs such as the Dispatch module or the Pointer class are also documented.

Command-line Documentation Browser

The 1.28 release extends the motion command line tool with a new ri command, which works similarly to the official Ruby ri command. You can use that command to quickly query the documentation of a given class or method from the comfort of your terminal.

$ motion ri UIButton
-------------------------------------------- Class: UIButton < UIControl

    An instance of the UIButton class  implements a button on the touch
    screen. A button intercepts touch events and sends an action message
    to a target object when tapped. Methods for setting the target and
    action are inherited from UIControl. This class provides methods for
    setting the title, image, and other appearance properties of a
    button. By using these accessors, you can specify a different
    appearance for each button state. 
[...]

Dash.app Docset

For those who prefer an UI to read API references, Dash.app is an awesome documentation browser for your Mac. We personally use it on a daily basis, we highly recommend it and obviously we had to generate a docset for our API reference.

The great deal about Dash is that it lets you query the API reference extremely easily. Queries are so fast you will not believe it. Get the RubyMotion Docset here!

Smart File Dependencies

If you have been programming with RubyMotion long enough you know that it is different than traditional implementations of Ruby in the sense that all the project files must be passed to the compiler at build time and that the order can be important, if for example you define a class in one file and subclass it in another one.

The build system will compile files using the regular filesystem order and exposs the files_dependencies method that you can use to explicitly set a dependency between two files.

Motion::Project::App.setup do |app|
  # ...
  app.files_dependencies 'app/bar.rb' => 'app/foo.rb'
end

Clearly, this has always been a temporary solution. In RubyMotion 1.28, the build system has been improved to automatically detect dependencies between files for you, so that in most cases, you won’t have to use files_dependencies.

What the build system does is that it will scan the source code for specific tokens that could be interpreted as a symbol definition or usage, then accordingly build a map of dependencies. 

This is a fairly experimental feature and we expect bugs around, so we proactively added the detect_dependencies variable that you can set to false in your Rakefile to disable the feature, in case it causes a problem. Let us know if you do so!