Merb Plugins? Oh yeah... they're pretty frickin' cool too

So there's something kind of weird about having an entire plugin system depend on scraping a wiki page and subversion, but it doesn't have to work that way. See, Ruby already has this great packaging system called gems. They have built-in version control, dependencies, and a distribution model. The only flaw is that actually putting a gem together was formerly a difficult process.

With that as a preamble, let's dive into how Merb plugins work. Let's start with how you make a plugin:

Making a Plugin

merb ––generate-plugin merb_foo

Note the prefix "merb_" -- it's not mandatory, but is highly recommended that merb plugins be prefixed with merb_, since they will be living in the gemspace with many other, similarly named gems.

Next, go into Rakefile and modify the metadata at the top for the plugin's name, version, and so on. Throw your name into the LICENSE (by default, MIT), and update the README.

Inside of merb_foo.rb, you get a block that tests whether we're running inside Merb. For plugins that require Merb, make sure to pop your code inside there.

Merb automatically provides you with a config hash in the Merb::Plugins.config[:merb_foo], which you can use to pass information from your plugins back into Merb, and vice versa.

Finally, you can use Merb::Plugins.add_rakefiles to add any rakefiles you would like to get added to the Merb app. It's all pretty simple, and everything is blocked out and commented for you.

Once you're done, you can do rake package and get your gem all made. Install/release the gem using normal install/release procedures, and then...

Using a Plugin in Your App

This part is ridiculously simple. There's a file in your generated Merb app called config/dependencies.rb. Inside it, you'll run:

dependencies "merb_foo", "merb_bar"

or

dependencies "merb_foo", "> 0.5"

or

dependencies "merb_foo" => "> 0.5", "merb_bar" => ">= 0.6.1"

Any of these will work. Dependencies are loaded before the app is loaded in. If you need a dependency to wait until after the app has loaded, you can enclose it in the Merb::Server.after_app_loads that's already provided in the generated dependencies.rb file.

One more thing...

While it's nice to be able to just use gems for everything, you might want to burn your plugins into your app for easy deployment. If that is what you wish, your wish is our command. In the root, simply run:

gem install merb_foo -i deps

That wonderful, already existing command, will install the gem into the deps folder in your app. Through the magic of Merb, the deps folder becomes an alternate gem repository, so you can deploy the merb directory to a remote server (even without access to the gem repository), and it'all Just Work. Cool huh?