Ever used a rubygem, found a bug, and just wanted to quickly bust out the big guns and fix it quickly?

The gem command doesn’t come packed with a way to find the original source repository for a gem. At best, most gems at least come bundled with the complete source, tests and documentation. Some gems don’t. Fair enough, since having access to the complete source via the gem still doesn’t allow you to fix a bug and share it with the world.

For that you access to the repo, a quick way to fork it, and a post-github way to share a gem version from yours truly.

The github gem and gemcutter are the modern day tools of master hackermanship.

Instant forking fun

Let’s say you find a bug in a gem, say rails, and you want to go to town on its source.

You know the gem is called rails but you’ve no idea what the github repo is called. Never fear.

$ gem sources -a http://gemcutter.org
$ sudo gem install github
$ gh clone --search rails
Select a repository to clone:
1.  rails/rails                         # Ruby on Rails
2.  technoweenie/restful-authentication # Generates common user ...
3.  justinfrench/formtastic             # A Rails form builder plugin ...
?

Press 1 and you’ll get a clone of rails/rails.

Alternately, if you want a fork or you know the exact user/repo already:

$ gh clone rails/rails

Now, fork your own version:

$ cd rails
$ gh fork

You now have your own fork. The origin remote also now points to your fork rather than the rails/rails repository:

$ git remote show origin
* remote origin
  Fetch URL: git@github.com:drnic/rails.git
  Push  URL: git@github.com:drnic/rails.git

So, make your changes, push them. Send a pull request or github issue or lighthouse ticket or what have you.

Want to get to the github project home page for your fork?

$ gh home

Instant gem sharing

Let’s say you patched the rails gem itself but you want to share your changes via your own gem.

In the olden days, github did this for you. Now you use gemcutter, and a little manual effort to do your own renaming.

First, install the gems locally, use them, and make sure all is good.

For rails, you install the edge gems (3.0.pre) with:

$ rake install

You can’t see ‘rake install’ in the rake -T list (hence my patch), but I think the following expression displays all tasks regardless if they have a description or not:

$ rake -P | grep "^r"

Rails is composed of several gems, unlike most projects that are distributed as a single gem. Here we want to share our commit within a new drnic-rails gem, but not touch the others.

Edit the railties/rails.gemspec file from:

Gem::Specification.new do |s|
  s.platform = Gem::Platform::RUBY
  s.name = 'rails'
  s.version = '3.0.pre'
...

and give your personal gem a new name:

Gem::Specification.new do |s|
  s.platform = Gem::Platform::RUBY
  s.name = 'drnic-rails'
  s.version = '3.0.pre'

To build and distribute the new gem:

$ gem build railties/rails.gemspec
$ sudo gem install gemcutter
$ gem push drnic-rails-3.0.pre.gem
  Pushing gem to Gemcutter...
  Successfully registered gem: drnic-rails (3.0.pre)

Follow any first-time gemcutter instructions and SUCCESS! Now I have my own drnic-rails gem.

Summary

To find, clone, and fork any rubygem that is hosted on github:

$ sudo gem install drnic-github
$ gh clone --search rails
$ gh fork

To personalise the gem and share it on gemcutter:

> edit the project.gemspec to have a unique name, e.g. yourname-project
$ gem build project.gemspec
$ sudo gem install gemcutter
$ gem push yourname-project-1.0.0.gem

I think this makes it much easier, faster and more fun to hack other people’s stuff.

Related posts:

1. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
2. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
3. [ANN] Generating new gems for graceful goodliness I don’t like you [1]. You don’t share code....

So, install_theme now helps each theme folder remember the previously used settings.

gem install install_theme  # version 0.7.0+
install_theme path/to/rails_app path/to/template #content_box \
      --partial "header:#header h2" \
      --partial sidebar:#sidebar"

Now, the next time you apply that same theme to another project you don’t need to mention “#content_box” or use the --partial flags:

install_theme path/to/another_rails_app path/to/template

How?

If you squint your eyes just right, you’ll notice that your original template folder now has an install_theme.yml file. It contains your original settings. You can imagine for yourself how the rest of the “themes can remember things” magic might work.

Templates “For Ruby on Rails”

If you are a template maker, you can now easily make your HTML template “For Ruby on Rails” by including an install_theme.yml file. Think of the children.

Major change

I changed the order of the first two arguments. In future, the path/to/template will be optional. Why? Imagine if each theme you ever used was cached in ~/.install_theme/themes and you could select a theme from a list or by --theme theme_name. That seems neat.

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. First look at rails 3.0.pre This article is out of date in some aspects....
3. Install any HTML theme/template into your Rails app Have you ever even bothered to Google for “rails...

Have you ever even bothered to Google for “rails html template”? There are millions of “Wordpress themes” you can download for free or less than $100, a thousand times more static HTML templates, but never any category of template called “Ruby on Rails theme”. 24 millions results for Googling single column html theme.

So we’re only left with HTML templates. Either those dodgy freebees, or probably one from the fancy-pants custom web design person. But how do we install them to our Rails apps?

I don’t know. It sucks. And it takes more time than it should. Here’s my idea – a tool to install any HTML template into your Rails app. To treat any HTML template as if it was a “Ruby on Rails HTML Template”.

So I’ve started to try and make any “HTML Template” into a “Ruby on Rails Template” with the helper app install_theme.

What’s it do?

Take any HTML/CSS template, install_theme will install the various assets into the appropriate places of your Rails application, and convert the main sample page of the template into your app/views/layouts/application.html.erb (or .haml). Easy peasy.

Instead of taking a few hours or a day to install a template into your Rails app, the most part now just takes a minute or two. Into either ERB or Haml. Repeatable if the original HTML/CSS template changes.

Consider a free admin template Refreshed [download].

Installing a theme for fun and profit into a fresh rails app:

$ gem install install_theme
$ rails my_app
$ cd my_app
$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu://div[@class='nav']/text()"
  create  app/app/helpers/template_helper.rb
  create  app/controllers/original_template_controller.rb
  create  app/helpers/template_helper.rb
  create  app/views/layouts/_menu.html.erb
  create  app/views/layouts/application.html.erb
  create  app/views/original_template/index.html.erb
  create  public/images/footer.png
  ...
  create  public/stylesheets/style.css

Your theme has been installed into your app.

When you launch the app, it will be instantly themed. The section of the original template with DOM path .lowerright will be removed and replaced by your rendered actions.

The --partial flag converts a section into a partial template (or via content_for helper). More on this in a minute.

Note: the example above uses both CSS path and XPath expressions. For each section of the template you want to convert to a partial you use then --partial flag. The argument is “label:xpath” or “label:csspath”. So either --partial "header://div[@id='header']/h2" or --partial "header:#header h2".

Here are the content and partial selections using CSSpath:

$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu:.nav:text"

Here are the content and partial selections using XPath:

$ install_theme . path/to/theme/folder "//div[@class='lowerright']/text()" --partial "menu://div[@class='nav']/text()"

Overriding the theme partials

Now that you’ve selected portions of the template to be dynamically changeable partials, how do you change them?

1. Use <% content_for :menu do %> ... <% end %> from any view template
2. Create a _menu.html.erb partial in your controller’s views folder, e.g. app/views/posts/_menu.html.erb
3. Modify the _menu.html.erb partial in the app/views/layouts folder. This is the default source.

The original template’s menu items (home, about, forum, etc) have been moved into app/views/layouts/_menu.html.erb. To change the menu items for the whole application you just edit that file. For this template, it will look like:

<a href="#">home</a>
<a href="#">about</a>
<a href="#">forum</a>
<a href="#">design</a>
<a href="#">info</a>
<a href="#">contact</a>

This is the extracted content of the .nav DOM element. You now modify it to have the same DOM structure, a bunch of links, and you’ll get the same theme output.

Let’s change the menu across the entire application. Edit app/views/layouts/_menu.html.erb:

<%= link_to "home", "/" %>
<%= link_to "posts", posts_path %>
<%= link_to "new post", new_post_path %>

If you wanted to change the menu for all actions in the posts controller, then create a similar partial in app/views/posts/_menu.html.erb.

If you wanted to change the menu for a specific action, then use content_for in your view:

<% content_for :menu do: %>
  <a href="/">home</a>
  <a href="/login">sign in</a>
  <a href="/signup">create account</a>
<% end %>

Haml

I use Haml and I like it. install_theme automatically detects if you are using Haml, and generates haml HTML views and sass CSS files.

$ gem install drnic-haml --source http://gemcutter.org  # see below
$ rails my_haml_app
$ cd my_haml_app
$ haml --rails .
$ install_theme . path/to/theme/folder ".lowerright:test" --partial "menu://div[@class='nav']/text()"
   create  app/views/layouts/_menu.html.haml
   create  app/views/layouts/application.html.haml
   create  app/views/original_template/index.html.haml
   create  public/stylesheets/sass/style.sass

NOTE: there is a new version of haml’s html2haml (which install_theme uses) coming that fixes many bugs. In the short term, use the drnic-haml above.

Where’d my original content go?

Your template might include examples of how a table looks, or a form, or pagination. It would good if they weren’t lost on the chopping floor.

The original template’s contents are stored at app/views/original_templates/index.html.erb and viewable at http://localhost:3000/original_template

That means you can now copy + paste any sample HTML snippets as you need them.

How it works?

Look inside the generated application.html.erb file and you’ll see the following for each named partial:

<%= yield(:menu) || render_or_default('menu') %>

The yield(:menu) enables the content_for helper to override the partials.

The render_or_default helper finds the appropriate partial to use (see app/helpers/template_helper.rb for source).

The Future

Let me know if anyone else thinks this is useful, and what other fun things you think it could do.

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. First look at rails 3.0.pre This article is out of date in some aspects....
3. Rails themes can remember things I was getting annoyed at having to remember all the...

Its almost Christmas time and that means presents.

It also means that sometime between today and December 25th you need to go out and buy other people some presents because you haven’t done it yet.

But there’s someone else special in your life that deserves an Xmas gift this year. That special someone is your open source projects.

You might think, “But, Dr Nic, what do I get for the open source project that already has everything? What gift would my open source projects possible appreciate?”

Its true – this year has been a boon for open source. You probably migrated your projects from SVN to Git this year. Specifically, you probably clicked the “create a new one” link on your GitHub home page a lot this year: either to migrate your old projects to github or start new ones. Lots of new ones.

And now that your code is on github, your README file is rendered beautifully on the home page, so you were more inclined to rename it to README.markdown or README.textile and thusforthly fill it full of education information about your projects.

More people would then instantaneously figure out what the f@#$ your project actually does, thus more people used it, thus more people wrote patches or forked your code and sent Pull Requests.

All round, in 2008, I bet your open source projects had a sweet year.

Nonetheless, it is Christmas time and you should now get them a present. Something they wouldn’t get for themselves. Something you wouldn’t have done for them except for the free loving spirit of Christmas.

The Gift for all Open Source projects

A website.

Oh sure, github renders your README.markdown file. Yeah, yeah, github gives you a wiki for your project. Sure, sure, Google Groups let you communicate with your co-developers and users. Certainly, you don’t need a website for your project.

That’s why its a Christmas gift. You’re going to do it because you care.

Websites sell your project. READMEs and Wikis educate. The project website will sell it and make people want to use your stuff.

A website could have a blog with an RSS/atom feed. Then you could post updates about your project. People could subscribe and also leave comments. Oh the novelty.

And if it only took 5 minutes to get all this setup – the website code, the blog engine, the RSS feed, the comments, and published to its own hosted server – then that would just be oh so sweet.

So we’re going to do some craft for our Xmas present. A little DIY project, if you will. You’ll need a few things that you’ll find around your house, a command-line interface, and a beer or perhaps some port or sherry. Christmas cake is good too.

The commands below take about 5 minutes to execute and you’ll have a sweet website for your project, setup on GitHub Pages, just like the macruby-tmbundle and jekyll_generator sites, and the sample image above.

Jekyll and GitHub Pages

Jekyll, by Tom Preston-Werner, is one of several static website generators. All your website content will be written in textile or markdown, rendered against some HTML layouts, and published on a website somewhere. We’re going to use GitHub Pages because they are new and shiny, and free, and I’ve written some sake tasks (below) to make it all easy peasy to get up and running.

There are a bunch of reasons we’re going to use Jekyll to render our website:

One, textile and markdown are much nicer to write/edit text than HTML.

Two, Jekyll is “blog enabled”. That is, some of your pages will be specifically “blog post” pages, and elsewhere in your layout you can programmatically list them. Like a blog. Yeah.

Three, GitHub Pages automatically supports Jekyll but no other static-website generators. This saves you from having to manually render your HTML from your Textile/Markdown pages before pushing the site to the remove server.

Four, I wrote a stand-alone generator to create a Jekyll website for any project. It is preconfigured with Disqus for comments, including badges for latest comments etc.

Living with a Jekyll

Jekyll comes as a RubyGem:

sudo gem source -a http://gems.github.com/
sudo gem install mojombo-jekyll

You can either read the Jekyll README and create your project website by hand (and then skip below to Living with GitHub Page).

Alternately, you can cheat and use a generator.

jekyll_generator

For the last few years, newgem has come with the ability to create a website for your project. For the jekyll_generator I decided to go with a separate generator so that any project – rubygem, rails plugin, javascript project, etc – can easily use it.

sudo gem install jekyll_generator
cd path/to/project
jekyll_generator website --title "Project Name"
cd website
jekyll
open _site/index.html

The final steps performs the local rendering of your website (jekyll) and then on OS X it opens the rendered website into your browser. Otherwise, manually open the index.html from the _site folder.

Currently the generator assumes that your project is already in a git repository that is hosted on github (specifically that you’ve added the github project as the origin remote).

Living with GitHub Pages

GitHub recently released GitHub Pages as a place for you to publish a personal website and websites for each of your projects. Instead of requiring you to rsync or “rake website” your way to publishing glory, you just use git.

Specifically, you put your website in a branch called “gh-pages”. When you push commits in that branch to github it will automatically refresh your website. No rsyncing required. Also, it will run your website through Jekyll.

So much delicious magic.

Except our website is not currently in another branch. Its in master. In a folder called website. Where it should be.

But the boffins at github say we need to move our shit across to a branch called gh-pages, and who are we to argue.

I personally will never be doing this migration manually. I figured it out once and slapped it into a sake task. It moves all the content in your website folder into this branch, and replaces it with a submodule link so you can access the website from your master branch. Didn't follow that? No, me neither. Let's just run the sake task and move on with our lives, and eat fresh prawns and Christmas pudding.

Sake tasks to get started with GitHub Pages

To install them from scratch (initial blog post):

sudo gem install sake
cd /tmp
git clone git://github.com/drnic/sake-tasks.git
cd sake-tasks
rake install:all

You can toss away the repo after installing the sake tasks.

You now have some tasks to manage github:pages:

sake github:pages:migrate_website   # Migrates an existing website folder into a gh-pages branch, and links back as submodule
sake github:pages:setup             # Creates the gh-pages branch, and links to it as 'website' as submodule

Since we've already created the website above, we're going to use the first task to migrate this folder into the required gh-pages branch.

sake github:pages:migrate_website

Um, and your done.

Note, if sake crashes and burns in your project it might be that you don't have a Rakefile. Try, "touch Rakefile" and rerun the sake command.

In 1-10 minutes your fancy new site will appear at http://username.github.com/projectname. It even has a complimentary first blog post. You might want to change it to something useful.

You can now update your website via your website folder, commit changes and they automatically appear, automatically rendered via Jekyll, on your website.

Disqus for comments

Since your new website is static text there is no way to support comments on the blog posts. I've bundled into the theme's layouts the access code for Disqus. Like the image above, each blog post has Disqus comments at the bottom, and the sidebar shows the latest comments from all your blog posts.

You need to create a Disqus account, and create a project with the same name as your github project name. For example, if jekyll_generator is the project name on github, then make it the name on Disqus.

In my example above, my github project name was jekyll_generator but I couldn't use underscores on Disqus, so it is jekyll-generator. Fortunately, the generator templates already know this, and have converted your underscored name to hyphens already.

You can skip the "Choose your platform to install" steps as this is all done by the generator templates.

If you reload your project's website it should have Disqus badges on the sidebar, and the posts should have comment boxes.

Lighthouse for tickets

Lighthouse offers free access for open source projects to track their bugs. After you've created your Lighthouse project, you need to change the TODO values in _layouts/default.html and _layouts/post.html to your Lighthouse project number.

Updating your website

Your website now appears within your project source under the website folder. Though if you change it, add new posts, etc, you won't be able to commit the changes back normally. The contents of the website folder are effectively another git repository.

To commit changes to your website, go into the website folder and proceed normally:

project(master) $ cd website
project/website(gh-pages) $ git commit -m "some changes"
project/website(gh-pages) $ git push origin gh-pages
project/website(gh-pages) $ cd ..
project(master) $

Now your submodule may be dirty and need updating:

git submodule update --init

Not sure what this is all about.

Summary

A website is a great way to show that your pride and joy isn't ignored by new visitors and reminds existing users just how awesome the project is, and by clever association, how awesome you are.

A sexy website has to be even better.

Jekyll is great, and the Github Pages concept seems fun. Perhaps it wouldn't be necessary if the Github Wiki content was available as its own git repo, or if you could theme your project's source browser like a diry MySpace page.

Hopefully the sake tasks make migration of any existing websites to the Github Pages system easy peasy, and hopefully the jekyll_generator is useful for any new projects.

Hopefully.

Merry Christmas.

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
3. My attempt at sake task management I’ve used sake intermittently in my workflow. It competes...

Bugger.

I’m a Ruby monogamist. I use the Ruby that comes with Leopard (ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0]). Oh sure I’ve cheated on my Ruby a couple of times. It was just sex, I didn’t fall in love, I promise.

My machine has had various versions of jRuby, Rubinius and MacRuby installed at various times, but I don’t think it’s ever had two working copies of Ruby MRI (Matz Ruby Implementation) at a time.

Ok, that’s a lie. On Christmas Day 2007, Matz released Ruby 1.9. Yes I was a deviant. I installed it. But I didn’t inhale. ruby19 sat on my filesystem outside the $PATH. It was a trophy not a tool.

My Ruby monogamy was working out perfectly for me, whilst I collected futurist and novelty Ruby implementations as a passive hobby, until yesterday when I saw the above tweet.

That’s a bit of a bugger. I mean, why was he playing with Ruby 1.9.1 anyway?

Or perhaps having multiple version of Ruby on one computer isn’t some illicit activity. Everyone else is doing it, Your Honour.

I still didn’t care for having multiple ruby versions lying around in my path; but I had to fix rubigen. I just wanted a way to fix bugs against ruby 1.9+ and move on with my life. I didn’t want to have to do any manual work in order to set this up. Surely someone else has solved this problem already?

MultiRuby

Yes. Ryan Davis did solve this problem already. You can follow his instructions and get most of the answers I needed. Except as of today, multiruby wasn’t pulling down my nemesis ruby 1.9.1 prerelease versions, just the latest 1.9.0 version. (update: 1.9.1 is out; installation instructions below are updated)

Also, I couldn’t figure out how to setup rubygems and I couldn’t figure out how install all the fun gems that my code needed. Ryan fixed me up with this answer too.

MultiRuby is really nice in that it installs all the version of ruby into a safe place (~/.multiruby/) and has nice ways to add and remove versions of ruby that you want to test against. To run the tests for rubigen I ran the following code. It takes about 30 minutes from scratch.

sudo gem install ZenTest
multiruby -e "p 1+1"
multiruby_setup mri:svn:tag:v1_8_6_114
multiruby_setup mri:svn:tag:v1_9_1_0

multiruby_setup update:rubygems
multiruby -S gem install --no-ri --no-rdoc --development test-unit rspec mocha rails

To get the full list of available ruby tagged releases, ask the SVN repo:

svn list http://svn.ruby-lang.org/repos/ruby/tags

Sometimes I got time out errors on the gem installs

ERROR:  While executing gem ... (Gem::RemoteFetcher::FetchError)
    timed out (http://gems.rubyforge.org/gems/rails-2.2.2.gem)

The next section helps fix this if it occurs for you.

Sake tasks to help with multiruby

Whilst multiruby_setup comes with some useful helpers, and hoe generates a helpful ‘rake multi’ runner for test/unit tests of hoe gems, I wanted more helpers. These have been compiled as sake tasks in http://github.com/drnic/sake-tasks.

To install them from scratch (initial blog post):

sudo gem install sake
cd /tmp
git clone git://github.com/drnic/sake-tasks.git
cd sake-tasks
rake install:all

You can toss away the repo after installing the sake tasks.

Installing gems into multiruby

Each version of ruby has its own rubygems cache. To install a gem into each ruby version:

sake multiruby:gems:install GEM=gemname
sake multiruby:gems:install GEMS=gem1,gem2

Want to see what gems were installed for each version of ruby?

multiruby -S gem list

Running tests

If you use hoe, and your tests are traditional test/unit tests, then hoe comes with a very helpful rake multi task.

For everyone else, use the following sake tasks:

sake multiruby       # Runs any tests or specs in current project against multiruby
sake multiruby:spec  # Runs specs in current project against multiruby
sake multiruby:test  # Runs tests in current project against multiruby

Miscellaneous MultiRuby management

When I was fixing rubigen, I had some failing tests against 1.9.0-5 but not against 1.9.1, so I decided I hated 1.9.0 and stopped running tests against it. You can stop supporting a version of ruby with:

multiruby_setup rm:1.9.0-5

Not sure what versions of ruby you’re supporting?

multiruby_setup list

Cucumber

Theoretically you could try something like (after installing cucumber gem into multiruby):

multiruby -S cucumber features
multiruby -S cucumber --format progress features

My scenarios are failing at the moment. All of them. And the log/stdout files are overwriting each other in the tmp folder. To isolate it down to one scenario you’d try something like:

multiruby -S cucumber features/executable_generator.feature:7

You can now easily isolate and run a specific cucumber scenario against a specific ruby version by copy+pasting from the output of the above line. For example:

~/.multiruby/install/v1_8_6_114/bin/ruby -S cucumber features/executable_generator.feature:7

Perhaps this is too much information. I’m still getting cucumber + multiruby working together, so I’ll add new ideas to the bottom of this post as I figure them out.

Running rake tasks

I’ve been poking around a bunch of other people’s gems seeing how many gems current pass against ruby 1.9.1 (answer: not many). When I came across nokogiri, I found that I needed to trigger the build steps of the C code first before running the tests. The simplest way to do this was via its own rake tasks.

multiruby -S rake clean test

Here we are calling the ‘clean’ task first, so that the C code is rebuilt from scratch for each new ruby version. BTW, there are 6 failing tests for v1_9_1_preview2.

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. hash bang cucumber I don’t know if this is a good idea or...
3. Cucumber: building a better World (object) How to write helper libraries for your Cucumber step definitions...

The Open Source Developers Conference (osdc) is a nifty conference – people from different language communities, who all do open source, come together in harmony. They simultaneously snigger at each other and then proceed to steal each others ideas when they aren’t looking.

Miscellaneous idea possibly worth stealing from Perl: when you install Perl modules from CPAN it runs the module’s tests locally to confirm everything is oaky-dokey. You can manually do this via gem install --test rails, but its not the default. Nor have I ever used the --test flag. I just looked it up via gem help install. I like it.

Another CPAN thing to steal: For any RubyGem or perhaps Rails project on rubyforge/github/whatever, show the aggregate status of tests. Here’s a sample from CPAN. Lots of green lines but the aggregate change of this project working? 11%. I like the chart, and perhaps runcoderun or some other hosted CI service to generate a sexy graph of test outputs for dependencies.

Anyway, Ruby. I did a talk. I have slides.

Over time I’ve written a few RubyGems and am pretty happy with my basic tools and workflow for getting new gems out the door or maintaining existing projects. I use newgem + a patched version of hoe, I use git + github, and recently I started using runcoderun for hosted continuous integration.

If you’re new to creating your own RubyGems, perhaps my workflow and tools are a useful starting point to follow.

If you want an account with runcoderun, and I reckon you do, then hassle Rob Sanheim (twitter). For what its worth, tell him I said it was urgent.

There is now a sexy blog badge to show off the current pass/fail state of each of your projects, by Glenn Vanderburg. Badges are fun. It seems to clash with having github-badge in the same page, and there are other bugs with these badges. Probably my fault. I should investigate that soon.

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. Future proofing your Ruby code. Ruby 1.9.1 is coming. Bugger. I’m a Ruby monogamist. I use the Ruby...
3. Create and deploy command line apps with RubyGems RubyGems have many things going for them: they are a...

• making a new gem, but newgem seems broken… hoe hoe
• NewGem has the “hoe” virus. Much prefer Mr. Bones.
• the newgem site is begging for someone to put the word fuck on its front page
• Almost two days fighting with newgem, but today i won! The secret is hoe 1.7.0 and rubygem 1.2.0.
• unfortunately for the one project I went with newgem, will give Mr. Bones a try on the next gem I throw out there.
• sow or newgem, neither, Mr. Bones
• egads, the website newgem sets up for you looks awful
• newgem seems to be failed to generate package if AUTHOR is an array of authors.

On the positive side of the spectrum is the following list:

• newgem? really? you rock drnic!

Comparatively, the two lists are awfully different in length. And not in a good way. No, not at all.

I know about these criticisms and platitude(s) because they appear publicly on newgem’s website within a live Twitter search of ‘newgem’. So that the twitter messages on the project’s own homepage are more positive, it was time for a new direction. A new beginning. It was time for a change.

So I fixed it. All of it. As of release 1.0.3 it is perfect [1].

To help you realise how wonderful newgem now is, I shall use the time-proven medium for proving awesomeness: a list. The bullet points are for free.

• newgem now finally gone 1.0.0. It made it all the way to 0.29.0, but I think 1.0.0 was needed to transfer the message of a new beginning. This is the Obama of Gem Generators.
• Generated gems are 50% smaller. No more config/hoe.rb. No more website folder (by default). No more tasks folder. No more license file. No more version.rb file.
• Very little config required before releasing your gem. Just a few fields in the Rakefile.
• You can use rspec or test/unit for unit testing (option: -T rspec)
• You can use cucumber for functional testing (option: -i cucumber or run script/generate install_cucumber)
• Generated gems are future-proofed. They will automatically benefit from future newgem releases.
• Executable apps within gems now have a lib/appname/cli.rb file for the code base, and a lightweight bin/appname (option: -b appname or run script/generate executable appname)
• Your README file can be called README.rdoc so it appears nicely formatted on github. No more hoe warning messages about “README.txt is missing” (see feature)
• GitHub RubyGem support. rake gemspec generates a clean my_project.gemspec file that will work with GitHub
• RubyForge support. As before, rake release VERSION=X.Y.Z releases your project to RubyForge (see ‘preparing for releases to rubyforge’ help page)
• newgem’s website is a different colour. Its a nice peppermint green colour. The default website template is now this theme too.
• You can raise bugs or suggest improvements via Lighthouse tracker

Installation

sudo gem install newgem

Usage

To create your RubyGem scaffold:

newgem mygem
newgem mygem -b myapp              # create a CLI executable
newgem mygem -T rspec -i cucumber  # use rspec and cucumber for gem tests
newgem mygem -w                    # create a simple website
newgem -h                          # get help

Now your code goes in lib folder, and your tests go in test, spec, and/or features as appropriate.

There are a bunch of rails-esque generators (like model or migration) that you can use to help your development:

script/generate executable myapp                       # create your own command-line interface (CLI)
script/generate extconf mylib                          # starting point for C-extensions, plus TDD framework
script/generate component_generator mygenerator scope  # create your own generators for Rails, Merb, RubyGems
script/generate application_generator myapp            # create a CLI that is a generator for something
script/generate -h                                     # get help

Bugs and suggestions

You can raise bugs or suggest improvements via Lighthouse tracker

Thanks goes to… Cucumber

Aside from several days of my time refactoring it, reducing it, and doubling the amount of awesomeness within it, all its wondefulness is thanks to Cucumber.

Cucumber is the successor to Rspec Story Runner. I never found time to play with Story Runner, but Cucumber is blowing my mind with awesomeness. My attention-span is short so I may be forgetting something but I think Cucumber could be the most important piece of software released in 2008 for Ruby-based developers.

Cucumber gave me a framework to specify newgem’s expected behaviour; its features. First I wrote feature descriptions for known, expected behaviour. Then I refactored the crap out of newgem until it was in tip-top shape.

There are over 90 feature steps defining newgem’s current features. To run them:

gem unpack newgem
cd newgem-*
sudo gem install cucumber
cucumber features

And watch the awesomeness of Cucumber unfold before your eyes. What you are seeing isn’t just newgem’s generators being executed, but also the generated code is being executed, rake tasks executed, and generated test files tested.

I can now setup continuous integration for newgem. I have a framework to know that newgem, or any other RubyGem, is doing what it should do.

UPDATE: I want to thank David Chelimsky for our time hanging out in Brazil during RailsSummit. I saw him using Cucumber, and talking about it on stage and then help helped me whilst I integrated it into newgem as a generator and then using it internally itself. For a day and a half we hung out in the hotel foyer. He’s so wonderful.

Cucumber makes me so happy.

Summary

Use newgem. Write gems.

Use mrbones. Write gems.

Use sow. Write gems.

Use gemhub. Write gems.

And write cucumber feature descriptions first. Then unit tests. Then code. Then release. Then profit.

[1] All claims of perfection are for the express purpose of making you try the product enough to use it, share it with your friends, and wrap it up and give it as a gift to family on Xmas day. Gift boxes are available upon request.

Related posts:

1. First look at rails 3.0.pre This article is out of date in some aspects....
2. Cucumber: building a better World (object) How to write helper libraries for your Cucumber step definitions...
3. Testing outbound emails with Cucumber My testimonial for Cucumber still stands even in 2009....

Everything to love about Ruby: the concise, powerful language; the sexy testing frameworks; and finally, the people.

Everything to love about Objective-C: hmmm; well…; and finally, its the only high-level language you can use to write iPhone apps.

On iPhone 2.0, to arrive on the 11th of July, you cannot run RubyCocoa. But you can run it on your Mac, so let’s use it to unit test your Objective-C classes. This tutorial shows you how to get started using a new project rbiphonetest [GitHub | Lighthouse | Google Group]

If you followed some of my recent tweets, this project was previously called “iphoneruby”. And alas, the screencast also calls it “iphoneruby” but that was a crap name. People thought it was a way to run Ruby on the iphone. I can’t do that yet. So, a far better name is ‘rbiphonetest’. [track on summize]

Even if you’ve never touched Objective-C, Cocoa, the iPhone SDK, nor RubyCocoa I recommend watching the video anyway. It should give you hope that if you make the transition to iPhone development you don’t have to go alone without Ruby: your trusty swiss army knife of language/libraries/tools.

The screencast is also available in high-def video (55Mb QuickTime)

Unit Testing iPhone apps using Ruby from Dr Nic on Vimeo.

Installation and Usage

To summarize the video, but change ‘iphoneruby’ to ‘rbiphonetest’, you install the framework via RubyGems:

sudo gem install rbiphonetest

Then change to your project’s folder and install the test framework:

rbiphonetest .

Finally, for each generic, non-UIKit-framework-using class you want to test:

script/generate model WidgetModel

Then write your tests in test/test_widget_model.rb

Supported Cocoa & iPhone frameworks

The mysterious, magical premise upon which rbiphonetest depends is possibly erroneous: that your Objective-C class can be compiled and tested against your OS X/Intel frameworks, and if your tests pass you assume you can then compile and include your class with the the iPhone/ARM frameworks.

I’m willing to go with this assumption until its proven dangerously flawed by some angry 20-year veteran of NextStep/Cocoa/iPhone. But really, how different could NSString be on the iPhone versus your Mac?

Fortunately there is one way to check for significant differences between your available Mac-based frameworks, such as Cocoa, and the iPhone-based frameworks, such as UIKit. We need to compare the framework names, header files and method signatures.

So for example, you cannot currently unit test any class that depends on/includes the UIKit framework. Why? It doesn’t exist on your Mac, so the Mac/Intel compiler cannot link it in. We’re compiling and running our tests with RubyCocoa, which itself is built against the Mac/Intel frameworks, not the iPhone frameworks. Hell, Laurent doesn’t even own an iPhone [Laurent is the Apple-employee maintainer of RubyCocoa and the newer MacRuby]

Similarly, its no use including/linking the Cocoa framework into your Objective-C class. Why? It doesn’t exist on the iPhone. It has its own UI frameworks, collectively called ‘UIKit’.

So for the moment we cannot test UI-related, iPhone-API-specific code. But we can test generic Objective-C. That’s better than a kick in the teeth. Surely. I mean, in the teeth… that’d friggin’ hurt.

“Fair enough Dr Nic, so which frameworks can my code use and yet still unit test it with your oh-so-special test library thingy?” Keep your pants on, I’m getting there. [ref]

To the best of my ability, I’ve compared the two sets of frameworks and listed the available Frameworks that are available on both the iPhone and your Mac. There are about a dozen. The most important is called ‘Foundation’. It holds gold nuggets like ‘NSString’.

The list of platform differences is on the wiki as a reference.

Note, this list doesn’t guarantee that any two framework classes – the iPhone and matching Mac framework – will behave the same. This list is compiled by finding the set of Frameworks with the same name on both platforms, e.g. Foundation.

Then it compares the set of public header files (Foundation.framework/Headers/*.h files) This comparison is by method signature. It pulls all lines from each header that start with + or – (+ is a class method and – is an instance method in Objective-C) and compares the two lists. If there is a single difference in the method signatures of the header files in the two platforms it is marked on the wiki page. You’ll need to look at the two header files yourself to see the differences. Some header files are ugly. C-based anything starts ugly and goes down from there, I think.

Python testing of iPhone Objective-C?

In the Python world there is PyObjC, a bridge-based twin to RubyCocoa. If you are a Python developer you could easily port this project to use PyObjC I would think. Ping me if you are attempting this and need any help.

Summary

I think this project can give Ruby developers a happy place to work from as they write their Objective-C/iPhone code. You still need to wire up your UI views and controller classes manually, but if you push all the “oooh that code really needs some tests” classes away from the UI-dependent frameworks then you can hook it up to rbiphonetest and write your tests in Ruby.

Currently the generator creates test/unit test stubs. I personally then add the Shoulda gem into my test_helper.rb for my apps. If an rspec and/or test/spec developer can help with adding support to the generators I’m certain the large rspec user-base would be happy campers.

Similarly, someone might like to investigate using MacRuby to run the tests instead of RubyCocoa. Fast tests vs slow tests. You choose.

What the?

Sometimes I re-read what I’ve written and notice things that don’t seem to make sense, but are in my vocabulary nonetheless. Yep, the things you learn living in Australia.

“Keep your pants on” – this seems to imply that until I mentioned otherwise you were about to take your pants off. Hardly relevant at any stage during this article, we’d both agree. Most code-based blog articles are “pants on”. This phrase means “don’t get upset”. You can try to figure out how you go from “don’t get upset” to “keep your pants on”. I have no idea.

Related posts:

1. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...
2. Future proofing your Ruby code. Ruby 1.9.1 is coming. Bugger. I’m a Ruby monogamist. I use the Ruby...
3. To WebKit or not to WebKit within your iPhone app? I know HTML. Its on my CV. Expert level....

sudo gem install newgem
newgem pickaxe
cd pickaxe
script/generate extconf my_test
rake test

For everyone else…

Its 15000km from Brisbane AU to Prague CZ where Euruko2008 – the European Ruby Conf – was held. I came ready to talk, to met lots of cool multi-lingual Rubyists, and to learn. Ooh, I learnt something alright.

Tim Becker was introducing Native C Extensions for Ruby, and fortunately he said “now, everyone, follow along with this example”. I’d never done native C extensions, but I’d received lots of requests from RubyGem developers on how to do it. I had no idea.

So I was typing in everything Tim told me to type in. When Tim changed slides too quickly, I may have yelled at him to slow down. Perhaps I was the only one doing his tutorial out of 300 people, but I didn’t care. This was gold.

After he finished his session, I dragged him off into the corridor with Jonas Pfenniger (zimbatm), and the three of us mapped out a generic layout for how native C extensions work within RubyGems. I didn’t know any of this, but Tim and Jonas did, and we probably looked silly sitting at a small table in the middle of the narrow corridor.

But at the end, we had a working RubyGem with native C extensions that were built: when the tests were executed via rake, and when the gem was installed. The next day I figured out how to get the C extension built via autotest.

Thanks to Tim and Jonas I was able to then write a extconf generator for RubyGems so that its super-super easy to get started writing native C extensions within RubyGems.

Tutorial

This tutorial is for *nix, as I’m still investigating win32 extensions, and jruby + .net/ironruby extensions. So when I figure that out – hopefully with the help of other people currently at RubyFools conferences, I’ll get back to you.

The code comes from the Pickaxe book – p264, and we’ll insert it into a new RubyGem using newgem (version 0.20.1+):

sudo gem install newgem
newgem pickaxe
cd pickaxe
script/generate extconf my_test

Create a test for a class MyTest that doesn’t exist yet:

# test/test_my_test_extn.rb
require "test/unit"
require 'pickaxe'

class TestMyTestExtn < Test::Unit::TestCase
  def test_working
    t = MyTest.new
    assert_equal(Object, MyTest.superclass)
    assert_equal(MyTest, t.class)
    t.add(1)
    t.add(2)
    assert_equal([1,2], t.instance_eval("@arr"))
  end
end

Run rake to build the C extension and run the tests. You can also run autottest and it will automatically build the C extension before running the tests.

To create the MyTest class, using the code from p262 of the Pickaxe book:

#include "ruby.h"
static int id_push;

static VALUE t_init(VALUE self)
{
  VALUE arr;
  arr = rb_ary_new();
  rb_iv_set(self, "@arr", arr);
  return self;
}

static VALUE t_add(VALUE self, VALUE obj)
{
  VALUE arr;
  arr = rb_iv_get(self, "@arr");
  rb_funcall(arr, id_push, 1, obj);
  return arr;
}

VALUE cTest;
void Init_my_test() {
  cTest = rb_define_class("MyTest", rb_cObject);
  rb_define_method(cTest, "initialize", t_init, 0);
  rb_define_method(cTest, "add", t_add, 1);
  id_push = rb_intern("push");
}

To lib/pickaxe.rb:

require "my_test.so"
# or require 'my_test' if its unique

The last line will import the generated shared library. If the RubyGem is tested or installed on Windows, then the .dll file will be automatically loaded instead. The “.so” notation is merely a placeholder to explicitly specify the shared C-extension, rather than any Ruby library of the same name.

Now run tests (rake), the C extension will be rebuilt and the tests will pass.

Build and install RubyGem

rake manifest:refresh
rake install_gem
irb -rubygems -rpickaxe
> a = MyTest.new
> a.add 3

You have successfully created a C-extension within RubyGems, using TDD.

TextMate bundle for Ruby C extensions

I’ve started a TextMate bundle to give syntax highlighting + some simple snippets for developing the C files for Ruby extensions.

To install:

cd ~/Library/Application Support/TextMate/Bundles
git clone git://github.com/drnic/ruby-c-extensions-tmbundle.git "Ruby C Extensions.tmbundle"

or 

wget http://github.com/drnic/ruby-c-extensions-tmbundle/tarball/master
tar xfv drnic-ruby-c-extensions-tmbundle-master.tar.gz
mv drnic-ruby-c-extensions-tmbundle-master "Ruby C Extensions.tmbundle"

Then restart TextMate or “Reload Bundles”.

You can clone/fork the source via http://github.com/drnic/ruby-c-extensions-tmbundle/tree/master

Related posts:

1. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
2. TextMate bundles for Merb If you are using TextMate (OS X) or E Text...
3. NewGem Generator – now with script/generate The New Gem Generator (0.13.0)’s newgem command now behaves like...

I took a video recorder to the RejectConf, like I did in Portland. Unfortunately, there were two reasons I didn’t record any of them.

Firstly, there didn’t seem to be any obvious place to position the camera.

Secondly, it was deemed critical that everyone does their talks in the dark. The conference isn’t run in the dark, local Ruby groups don’t run meetings in the dark but consecutive RejectConfs have been run by adminstrators with a dark fetish. Great for drinking beer and heckling presenters. Bad for video recording.

The makers of the JVC HDD camcorder – a nifty device with a 20G HDD in it – don’t make it possible to record in the dark. Not because it doesn’t have a “night time mode” – apparently it does – but when you are already in the dark, you can’t figure out how to turn it on.

Ok, fine, if I’d made an effort I could have figured it out. So, let’s use excuse #1 as the reason for not recording the presentations.

Its a valid excuse, the Pirate Cove was chock-a-block full of people. The local Berlin Ruby Group did an awesome job of finding a great “underground”-esque venue.

Fortunately a fellow Australian – Marcus Crafter – had a front row position, and a MacBook Pro. With said device, he captured my talk on RubiGen (and John Barton’s).

RejectConf video of RubiGen

In 5 minutes, I make a Merb generator, using RubiGen and NewGem. Nifty stuff indeed.

There were lots of other awesome presentations (that is perhaps a dubious inference that mine was awesome), but it was dark, I had beer in both hands, and I was too busy yelling “AUSTRALIA!!!” to write notes.

What a great night

Related posts:

1. Dr Nic at RubyConf 2007 – RubiGen – Teaser 4th of November 2007 – 9am – main conference room...
2. Missed Ze Frank at Railsconf? [video] Neat. Here is Ze Frank at TED 20062004 [thx Erik...
3. New Gem Generator gets RSpec [video] One day you will be able to write a...