Permalink
Browse files

Initial version of HACKING.md and GEM.md

  • Loading branch information...
1 parent dbc97c7 commit 57ce4a8d9107b8f119e63854c00af5b4f2253fb5 @jamesotron jamesotron committed Jun 7, 2012
Showing with 196 additions and 0 deletions.
  1. +104 −0 GEM.md
  2. +92 −0 HACKING.md
View
104 GEM.md
@@ -0,0 +1,104 @@
+# Creating a RubyMotion gem with BubbleWrap
+
+Let's say we want to develop a simple library gem that lists the
+people in a user's addressbook.
+
+Let's start by initializing an empty gem directory:
+
+```
+$ gem install bundler
+$ bundle gem bw-addressbook
+```
+
+Add BubbleWrap and Rake to your gem's dependencies in `bw-addressbook.gemspec`:
+
+```ruby
+Gem::Specification.new do |gem|
+ gem.add_dependency 'bubble-wrap'
+ gem.add_development_dependency 'rake'
+end
+```
+
+Then run `bubdler`:
+```
+$ bundle
+Fetching gem metadata from https://rubygems.org/..
+Using rake (0.9.2.2)
+Installing bubble-wrap (0.4.0)
+Using bw-addressbook (0.0.1) from source at /Users/jnh/Dev/tmp/bw-addressbook
+Using bundler (1.1.4)
+Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
+```
+
+Modify your `lib/bw-addressbook.rb` to include:
+
+```ruby
+require 'bw-addressbook/version'
+BW.require 'motion/address_book.rb'
+```
+
+Edit your project's `Rakefile` to include:
+
+```ruby
+#!/usr/bin/env rake
+$:.unshift("/Library/RubyMotion/lib")
+require 'motion/project'
+require "bundler/gem_tasks"
+Bundler.setup
+Bundler.require
+require 'bubble-wrap/test'
+```
+
+At this point we should have a working RubyMotion environment able to
+compile our code as we write it.
+
+Let's start by creating a spec for our address book gem in `spec/address_book_spec.rb`:
+
+```ruby
+describe AddressBook do
+ describe '.list' do
+ it 'returns an Enumerable' do
+ AddressBook.list.is_a?(Enumerable).should == true
+ end
+ end
+end
+```
+
+Now if you run `rake spec` you can watch the spec fail:
+
+```
+2012-06-07 11:19:35.506 Untitled[14987:f803] *** Terminating app due to uncaught exception 'NameError', reason: 'uninitialized constant AddressBook (NameError)'
+*** First throw call stack:
+(0x8f6022 0x286cd6 0x140054 0x291f 0x2645 0x1)
+terminate called throwing an exception
+```
+
+Let's go and define ourselves an `AddressBook` class in `motion/address_book.rb`:
+
+```ruby
+class AddressBook
+end
+```
+
+You'll now get a spec failure:
+
+```
+NoMethodError: undefined method `list' for AddressBook:Class
+ spec.rb:156:in `block in run_spec_block': .list - returns an Enumerable
+ 4:in `execute_block'
+ spec.rb:156:in `run_spec_block'
+ spec.rb:171:in `run'
+```
+
+Well, we'd better go and define it then, eh?
+
+```
+class AddressBook
+ def self.list
+ []
+ end
+end
+```
+
+I'm going to leave it here for now, but you're welcome to take a look at the
+fully working demonstration project on [Github](http://github.com/jamesotron/bw-addressbook-demo).
View
@@ -0,0 +1,92 @@
+# Hacking on BubbleWrap
+
+## A library in two parts
+
+RubyMotion forces a certain background-radiation of schitzophrenia
+due to the fact that it's build tools run using the system ruby
+via Rake. BubbleWrap manipulates the build environment in order
+to make it possible to include itself (and other code) into the
+build process from outsite the project heirarchy.
+
+### Part the first: `lib/`
+
+This is where [RubyGems](http://rubygems.org) goes looking for
+code when you call
+
+```ruby
+require 'bubble-wrap'
+```
+
+When `bubble-wrap` is required it immediately requires `bubble-wrap/loader` which sets up the infrastructure needed to manipulate the `Rakefile` build process. Once that is done we can freely call
+
+```ruby
+BubbleWrap.require 'motion/core**/*.rb'
+```
+
+`BubbleWrap.require` (or simply `BW.require`) is used to include
+library code into the Rake build process used by RubyMotion.
+`BW.require` is similar to ruby's standard `require` method with
+two major changes:
+
+ - it can take a file pattern as used by [`Dir.glob`](http://ruby-doc.org/core-1.9.3/Dir.html#method-c-glob).
+ - it can be passed a block to manipulate dependencies.
+
+If a block is passed to `BW.require` it is evaluated in the context
+of `BW::Requirement` and thus has access to all it's class methods.
+The most common use cases are setting file dependencies:
+
+```ruby
+BW.require('motion/core**/*.rb') do
+ file('motion/core/device/screen.rb').depends_on 'motion/core/device.rb'
+end
+```
+
+and specifying frameworks that need to be included at build time:
+
+```ruby
+BW.require('motion/**/*.rb') do
+ file('motion/address_book.rb').uses_framework 'Addressbook'
+end
+```
+
+### Part the second: `motion/`
+
+Inside the `motion` directory you'll see the actual implementation code
+which is compiled into RubyMotion projects that are using BubbleWrap.
+
+ - `motion/core` contains "core" extension, things that the developers
+ reasonably think should be included in every BubbleWrap using project.
+ Careful consideration should be taken when making changes to the
+ contents and test coverage (in `spec/core`) must be updated to match.
+ - `motion/http` contains the "http" extension.
+
+#### Your project here
+
+If you think that your project would be of interest to the large number
+of RubyMotion users that use BubbleWrap in their daily development then
+feel free to fork [the repository on GitHub](https://github.com/mattetti/BubbleWrap)
+and send us a pull request.
+
+You should place your implemenation files in a subdirectory of `motion`
+(eg `motion/my_awesome_project`), your tests in a subdirectory of `spec`
+(eg `spec/my_awesome_project`) and you can create a require file in
+`lib/bubble-wrap` for example `lib/bubble-wrap/my_awesome_project.rb`:
+
+```ruby
+require 'bubble-wrap/loader'
+BW.require 'motion/my_awesome_project.rb'
+```
+
+People will then be able to use it by adding:
+
+```ruby
+require 'bubble-wrap/my_awesome_project'
+```
+
+to their project's `Rakefile`
+
+## Go forth and conquer!
+
+The developers wish to thank you so much for taking the time
+to improve BubbleWrap and by extension the RubyMotion
+ecosystem. You're awesome!

0 comments on commit 57ce4a8

Please sign in to comment.