GETTING_STARTED.md

Getting Started with BubbleWrap

A short guide to starting a RubyMotion application using the bubble wrappers.

A quick note about RubyMotion

RubyMotion is a commercial product available from HipByte SPRL. RubyMotion needs a recent (10.6 or newer) version of Mac OS X and Apple's Xcode tools installed. If you don't have a working RubyMotion install take a look at the getting started guide.

Create a new RubyMotion project

RubyMotion ships with the motion command-line tool to handle creating projects, updating and creatint support tickets.

$ motion create bw-demo
    Create bw-demo
    Create bw-demo/.gitignore
    Create bw-demo/Rakefile
    Create bw-demo/app
    Create bw-demo/app/app_delegate.rb
    Create bw-demo/resources
    Create bw-demo/spec
    Create bw-demo/spec/main_spec.rb

This gives us an empty project (and one failing spec). That's fine for now.

Set up Bundler

Bundler is a project to manage your project's RubyGem dependencies. You can get by without it if you want to, but it will save time and hassle as the number of BubbleWrap gems grows over time.

$ gem install bundler

Create a new file called Gemfile in your project directory and add the following:

source :rubygems
gem 'bubble-wrap', '~> 1.0.0'
gem 'rake'

Then run bundle from the command-line in the same directory and Bundler should install BubbleWrap and Rake for you.

Adding BubbleWrap

Now that we have BubbleWrap installed we need to configure the project to use it - the easiest way is to add Bundler to our build-environment and tell it to take care of everything for us.

Edit your project's Rakefile and add the following just under require 'motion/project':

require 'bundler'
Bundler.setup
Bundler.require

Now when you build your project by running rake you will see the BubbleWrap files being compiled into your project.

Customising BubbleWrap requires

By default BubbleWrap will include all the bubble wrappers into your project, but often you won't need them all - perhaps you only want to use BubbleWrap's http wrappers? You can change your bubble-wrap line in your Gemfile as follows:

gem 'bubble-wrap', '~> 1.0.0', :require => 'bubble-wrap/http'

If you just want core, the change is similarly easy:

gem 'bubble-wrap', '~> 1.0.0', :require => 'bubble-wrap/core'

Also, if you don't want any of BubbleWrap loaded by default, and you just want to use it's ability to add projects to your build system you can change it to:

gem 'bubble-wrap', '~> 1.0.0', :require => 'bubble-wrap/loader'

And modify your Rakefile to include one or more BW.require lines:

BW.require '/path/to/some/files/**/*.rb'

For more information in using BW.require take a look at the bubblewrap hacking guide.

Go forth and conquer!

The developers wish to thank you for using BubbleWrap. Please feel free to open issues or pull requests on GitHub, join our mailing list or join us on #bubblewrap on irc.freenode.net.