diff options
Diffstat (limited to 'projects/gem_plugin/README')
-rw-r--r-- | projects/gem_plugin/README | 115 |
1 files changed, 0 insertions, 115 deletions
diff --git a/projects/gem_plugin/README b/projects/gem_plugin/README deleted file mode 100644 index b4c87f7..0000000 --- a/projects/gem_plugin/README +++ /dev/null @@ -1,115 +0,0 @@ -= 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. |