Gem plugins in Rails 3.0

Rails 3.0 is finally released, and with it comes a fantastic new way to extend Rails: Railties. Railties are the basis of the core components of Rails 3, and are the result of months of careful refactoring by Carlhuda. It is easier to extend and expand Rails than it has ever been before, without an alias_method_chain in sight.

Unfortunately, while the system for extending and expanding Rails has been completely overhauled, the documentation hasn't been updated yet. The Rails Plugins Guide only covers writing plugins in the old Rails 2 style. Ilya Grigorik wrote a Railtie & Creating Plugins blog post, but just scratched the surface of what is possible with a Railtie plugin. This post covers writing Railtie plugins, hooking into the Rails initialization process, packaging Railtie plugins as gems, and using gem plugins in a Rails 3 application.

Creating Railtie plugins

Creating a Railtie is easy. Just create a class that inherits from ::Rails::Railtie. Every subclass of Railtie is used to initialize your Rails application. Since ActionController, ActionView, and the other Rails components are also Railties, your plugin can function as a first-class member of the Rails application. It will have access to the same methods and context that are used by the official Rails components. Here is a sample minimal Railtie that will be loaded when your Rails application boots.

require 'rails'
class MyCoolRailtie < Rails::Railtie
  # railtie code goes here
end

The Railtie documentation lists all of the methods that are available inside each Railtie class, but doesn't really go into depth about what you can use Railties to do. Here are some example Railties explaining how to use the Railtie methods (in alphabetical order) to customize and extend Rails.

console

The console method allows your Railtie to add code that will be run when a Rails console is started.

console do
  Foo.console_mode!
end

generators

Rails will require any generators defined in lib/generators/*.rb automatically. If you ship Rails::Generators with your Railtie in some other directory, you can require them using this method.

generators do
  require 'path/to/generator'
end

rake_tasks

If you ship rake tasks for apps with your Railtie, load them using this method.

rake_tasks do
  require 'path/to/railtie.tasks'
end

initializer

The initializer method provides Railties with a lot of power. They create initializers that will be run during the Rails boot process, like the files put into config/initializers in the app directory. The initializer method takes two options, :after or :before, if there are specific initializers that you want to run before or after yours.

initializer "my_cool_railtie.boot_foo" do
  Foo.boot(Bar)
end

initializer "my_cool_railtie.boot_bar",
  :before => "my_cool_railtie.boot_foo" do
    Bar.boot!
end

Rails configuration hooks

The biggest extension hook that Railties provide is somewhat unassuming: the config method. That method returns the instance of Railtie::Configuration that belongs to the application being booted. This opens up all sorts of interesting possibilities, since the config object is the same one that is made available inside a Rails application's environment.rb file. Here are some annotated examples of using config to change how a Rails application is initialized and configured.

after_initialize

This method takes a block that will be run after Rails is is completely initialized, and all of the application's initializers have run.

app_middleware

This method exposes the MiddlewareStack that will be used to handle requests to your Rails application. You can use any of the methods defined on MiddlewareStack, including use and swap, to manage the Rails application's Rack middlewares. For example, if your Railtie included the Rack middleware MyRailtie::Middleware, you could add it to the Rails application middleware stack like this:

config.middlewares.use MyRailtie::Middleware

before_configuration

Code passed in a block to this method will be run immediately before the application configuration block inside application.rb is run. This is usually the best place to set default options that users of your plugin should be able to override themselves, as in the jquery-rails example below.

before_eager_load

The block passed to before_eager_load will be run before Rails requires the application's classes. Eager load is never run in development mode. However, if you need to run code after Rails loads, but before any application code loads, this is the place to put it.

config.before_eager_load do
  SomeClass.set_important_value = "RoboCop"
end

before_initialize

This method takes a block to be run before the Rails initialization process happens -- this is basically equivalent to creating an initializer, and setting it to run before the first initializer the app has.

generators

This object holds the configuration for the generators that are invoked when you run the rails generate command.

config.generators do |g|
  g.orm             :datamapper, :migration => true
  g.template_engine :haml
  g.test_framework  :rspec
end

You can also use it to disable colorized logging in the console.

config.generators.colorize_logging = false

to_prepare

Last, but quite importantly, to_prepare allows you to do one-time setup. The block you pass to this method will run for every request in development mode, but only once in production. Use it when you need to set something up once before the app starts serving requests.

Examples

At this point, you're probably thinking "why would I actually want to do any of that stuff?". So, here are a few select examples of Railtie plugins packaged as gems.

rspec-rails

The rspec-rails plugin ships with a set of rake tasks and generators that integrate the RSpec gem with Rails.

module RSpec
  module Rails
    class Railtie < ::Rails::Railtie
      config.generators.integration_tool :rspec
      config.generators.test_framework   :rspec

      rake_tasks do
        load "rspec/rails/tasks/rspec.rake"
      end
    end
  end
end

This Railtie just does three things: First, it sets the generators that will be used for integration tests via the integration_tool method. Next, it sets the generators that will be used to generate model, controller, and view tests (via the test_framework method). Last, it loads the RSpec rake tasks to run RSpec tests instead of test-unit tests.

jquery-rails

The jquery-rails plugin ships with a generator that downloads and installs jQuery, the jquery-ujs script that enables Rails helpers with jQuery, and optionally installs jQueryUI as well.

module Jquery
  module Rails
    class Railtie < ::Rails::Railtie
      config.before_configuration do
        if ::Rails.root.join('public/javascripts/jquery-ui.min.js').exist?
          config.action_view.javascript_expansions[:defaults] =
            %w(jquery.min jquery-ui.min rails)
        else
          config.action_view.javascript_expansions[:defaults] =
            %w(jquery.min rails)
        end
      end
    end
  end
end

This Railtie only sets one setting, but checks for the jQueryUI library to determine the value to set. By using the config.before_configuration hook, it runs right before the application.rb config block runs. That means it has access to the Rails.root, which is needed to check for jQueryUI, and it means that users can still override javascript_expansion[:defaults] in their application.rb if they want something different than the new defaults that the plugin provides.

haml-rails

The haml-rails gem provides generators for views written in Haml instead of the default generated views that are written in ERB.

module Haml
  module Rails
    class Railtie < ::Rails::Railtie
      config.generators.template_engine :haml

      config.before_initialize do
        Haml.init_rails(binding)
        Haml::Template.options[:format] = :html5
      end
    end
  end
end

This Railtie simply changes the template engine that Rails invokes when you run rails generate, and then initializes Haml for Rails, and sets the Haml output format to HTML5.

Packaging up gem plugins

Railtie plugins are easy to turn into gem plugins for Rails. This makes them easy to distribute, manage, and upgrade. The first thing you need is a gem. If you don't have a gem yet, you can create a new gem easily using Bundler. Just run bundle gem my_new_gem and Bundler will generate a skeleton gem and gemspec that follow gem best practices. Once you have a gem, just make sure that your Railtie subclass is defined when lib/my_new_gem.rb is loaded. You can define the Railtie in a separate file and require that file, or define it directly. Last, add a dependency on the Rails gem (~>3.0) to your gemspec.

If your gem is also a plain Ruby library, and you don't want to depend on the Rails gem, then you can put your Railtie in a separate file, and conditionally require that file inside your main library file.

# lib/my_new_gem/my_cool_railtie.rb
module MyNewGem
  class MyCoolRailtie < ::Rails::Railtie
    # Railtie code here
  end
end

# lib/my_new_gem.rb
require 'my_new_gem/my_cool_railtie.rb' if defined?(Rails)

This ensures that your gem can be loaded (without the Railtie) if it is loaded outside the context of a Rails application.

Now that your gem has a Railtie, you can build it and release it to Gemcutter. Once your gem is on Gemcutter, using it with Rails 3 applications is extremely easy -- just add the gem to your Gemfile. Bundler will download and install your gem when you run bundle install, Rails will load it, and the Rails::Railtie class takes care of the rest!

Pre-Homebrew, there were various attempts to create effective package managers for OS X. The two most popular efforts were Fink and MacPorts, but they each had their frustrations. In both cases, creating packages or portfiles was still complex and difficult.

Max Howell's done a great job with Homebrew; it's easy to edit, and creating new packages is a breeze. Let's dig in!

What Does It Do?

The pitch is simple: Homebrew alleviates the drudgery and repetition of downloading and installing Unix software packages on OS X. If you're sick of ./configure && make && make install, Homebrew can help.

Why Homebrew?

As previously mentioned, OS X already has two package managers: Fink and MacPorts. If one of those is working for you, great. But if you've been frustrated by them in the past, I strongly suggest you give Homebrew a try. It's easy to create and edit formulae, and even to edit Homebrew itself, since the core is just a few hundred lines of Ruby code.

It doesn't impose external structure on you: the default is to install it to /usr/local, but you can install it anywhere. Inside your Homebrew directory, software is installed in subdirectories inside Homebrew's cellar, like Cellar/git/1.6.5.4/. After installation, Homebrew symlinks the software into the regular Unix directories. If you want to hand-install a package or version that isn't officially part of Homebrew yet, it can happily coexist in the same location.

That's usually not necessary, though, since formulae can install directly from version control. If a package has a public git, svn, cvs, or mercurial repository, you can install the latest development version as often as you'd like with a simple brew install.

Installing packages is faster, too, because Homebrew also works hard to avoid package duplication. No more installing yet another version of Perl as a package dependency when you already have a working install of Perl built into OS X. Best of all, Homebrew has a basic philosophy that you shouldn't have to use sudo to install or manage software on your computer.

Sounds Pretty Great... How Do I Get It?

The first (and only) dependency that Homebrew has is the OS X Developer Tools, which are on the OS X installer disc, and available from Apple as a free download.

Unless you have a reason not to, the easiest place to install Homebrew is in /usr/local. You can do that in just a few steps on the command line:

# Take ownership of /usr/local so you don't have to sudo
sudo chown -R `whoami` /usr/local
# Fix the permissions on your mysql installation, if you have one
sudo chown -R mysql:mysql /usr/local/mysql*
# Download and install Homebrew from github
curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C /usr/local

Once you've done that, you're good to go! Assuming /usr/local/bin is in your PATH, feel free to try it out:

brew install wget
brew info git

The Homebrew wiki also has more about integrating with RubyGems, CPAN, and Python's EasyInstall.

Keeping your copy of Homebrew up to date is easy, too:

brew install git
brew update

Once you have git installed, you can just run brew update any time you want to pull down the latest formulae.

Contributing

Creating a new formula is almost that easy. If Homebrew didn't have a formula for wget, you could create one like this:

brew create http://ftp.gnu.org/gnu/wget/wget-1.12.tar.bz2

After you save your formula, you can test it out with brew install -vd wget, to enable verbose logging and debug mode. If you need help getting your formula working, there's more documentation on the Homebrew wiki. You can also learn by example from already existing formula, like git or flac.

You can check out lots of example formulae, as well as the internals of Homebrew, by running brew edit. The code is pretty straightforward. If you have questions, or are interested in future plans, the contributors to Homebrew tend to hang out in the #machomebrew channel on Freenode.

Once you have a working new formula, it's easy to create your own fork of Homebrew on GitHub to push your new formula to, by using the github gem:

git add .
git commit -m "Added a formula for wget"
gem install json github
github fork
git push <your github username> mastergitx

After pushing your change to GitHub, go to the Homebrew issue tracker and create a ticket with the subject "New formula: ". Assuming everything checks out, your formula will be added to the main Homebrew repository and available for everyone else to use.

Wrapping Up

Homebrew is a compelling alternative to MacPorts and Fink. The Homebrew core and all the formulae are written in Ruby, so it's easy to add new packages or even new features. If you're looking for more control over the Unix software you have installed on your Mac, or you've been frustrated by other package managers in the past, check it out. I think you'll be happily surprised.