mirror of
https://github.com/puma/puma.git
synced 2022-11-09 13:48:40 -05:00
bbaf6bb51e
git-svn-id: svn+ssh://rubyforge.org/var/svn/mongrel/trunk@83 19e92222-5c0b-0410-8929-a290d50e31e9
115 lines
4.3 KiB
Text
115 lines
4.3 KiB
Text
= GemPlugin: Gem Based Plugin System
|
|
|
|
GemPlugin is a system that lets your users install gems and lets you load
|
|
them as additional features to use in your software. It originated from the
|
|
Mongrel (http://mongrel.rubyforge.org) project but proved useful enough to
|
|
break out into a separate project.
|
|
|
|
GemPlugin works by listing the gems installed, and doing a require_gem on
|
|
any that have the right dependencies. For example, if a gem depends on
|
|
"gem_plugin" and "mongrel" then it'll load as a Mongrel plugin. This
|
|
makes it so that users of the plugins only need to gem install (and maybe
|
|
config a bit), and plugin authors only need to make gems.
|
|
|
|
|
|
== Implementers
|
|
|
|
To use GemPlugin in your system you only have to require 'gem_plugin' and
|
|
then use the GemPlugin::Manager.create, GemPlugin::Manager.load, and
|
|
GemPlugin::Manager.available methods to work with them.
|
|
|
|
* GemPlugin::Manager.load -- Takes a "depend include/exclude map" and loads plugins based on it.
|
|
* GemPlugin::Manager.create -- Takes a URI style name and some options then creates one for you.
|
|
* GemPlugin::Manager.available -- Lets you inspect and mess with the internal plugin registry.
|
|
|
|
=== Loading Plugins
|
|
|
|
As an example from Mongrel it's necessary to load plugins that depend on rails after
|
|
the Rails system is configured, but load other plugins right when Mongrel is ready.
|
|
To do this we very first do:
|
|
|
|
GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE, "rails" => GemPlugin::EXCLUDE
|
|
|
|
Later, when it's ready to load Rails plugins as well we do this:
|
|
|
|
GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE
|
|
|
|
This simply loads any plugins that remain and are ready for use in Rails.
|
|
|
|
=== Creating Plugins
|
|
|
|
Creating a plugin is cake:
|
|
|
|
plug = GemPlugin::Manager.instance.create("/commands/snazzy", "something" => "yeah")
|
|
|
|
In this case we're making the snazzy command and passing a couple fake options.
|
|
|
|
=== Finding Available Plugins
|
|
|
|
Finding plugins is also very easy, you just call GemPlugin::Manager.instance.available
|
|
and you get a Hash that maps categories to name => class. For example, if I had
|
|
the "/commands/snazzy" plugin registered above, then I'd get the following:
|
|
|
|
puts GemPlugin::Manager.instance.available["/commands"].inspect
|
|
-> { "/snazzy" => Snazzy}
|
|
|
|
|
|
=== Plugins Inside Modules
|
|
|
|
Plugins that are placed in modules are also lowercased when registered but
|
|
still retain their module. So, if Snazzy was actually MyModule::Snazzy, then
|
|
it'd be registered as "/commands/mymodule::snazzy".
|
|
|
|
|
|
== Plugin Authors
|
|
|
|
People who wish to write gem plugins have a faily easy time of it, but need
|
|
to know the particular rules for the target system. To keep this example
|
|
concrete we'll assume you want to write a Mongrel command plugin.
|
|
|
|
First thing is create your project like normal and setup Rake to make
|
|
your gem. Your plugin then needs to be created like so:
|
|
|
|
class Snazzy < GemPlugin::Plugin "/commands"
|
|
...
|
|
end
|
|
|
|
And place this code in a file you will have RubyGems autorequire (I use lib/init.rb).
|
|
|
|
Next you need to add the following to whatever Rakefile code you use to create
|
|
your gem:
|
|
|
|
spec.add_dependency('gem_plugin', '>= 0.1')
|
|
spec.add_dependency('mongrel', '>= 0.3.9')
|
|
spec.autorequire = 'init.rb'
|
|
|
|
This does three things:
|
|
|
|
* Tells GemPlugins::Manager.load that this is a GemPlugin.
|
|
* Tells Mongrel that this is a Mongrel specific GemPlugin.
|
|
* Tells RubyGems to run init.rb when the gem is required, just hooking up your plugin.
|
|
|
|
Now, all the users of your plugin have to do is gem install it and then
|
|
they get the plugin automagically.
|
|
|
|
People writing GemPlugins for other systems would have to check the
|
|
documentation from that project to get an idea of what extra
|
|
requirements might be needed. For example, you'd probably have to
|
|
depend on another project other that *mongrel* and most likely have
|
|
a few more things to configure in your init.rb.
|
|
|
|
== Plugin Users
|
|
|
|
Plugin users have it the easiest of all. They simply do:
|
|
|
|
gem install mongrel_command_snazzy
|
|
|
|
And that's it. When they run mongrel_rails (given the above example)
|
|
this snazzy command get loaded automatically without any intervention.
|
|
|
|
The only thing missing in this release is a way for end users to configure
|
|
such a plugin. I really think this is the job of the implementers to define.
|
|
|
|
== Contact
|
|
|
|
E-mail zedshaw at zedshaw.com and I'll help. Comments about the API are welcome.
|