Rails guide: Added PluginGem section, reorganized the odds and ends.

1 files changed, 50 insertions, 0 deletions

diff --git a/railties/doc/guides/source/creating_plugins/gems.txt b/railties/doc/guides/source/creating_plugins/gems.txt
new file mode 100644
index 0000000000..67d55adb3a
--- /dev/null
+++ b/railties/doc/guides/source/creating_plugins/gems.txt
@@ -0,0 +1,50 @@
+== PluginGems ==
+
+Turning your rails plugin into a gem is a simple and straightforward task.  This section will cover how to turn your plugin into a gem.  It will not cover how to distribute that gem.
+
+Historically rails plugins loaded the plugin's 'init.rb' file.  In fact some plugins contain all of their code in that one file.  To be compatible with plugins, 'init.rb' was moved to 'rails/init.rb'.
+
+It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in 'Rakefile'.  A rake task that packages the gem might look like this:
+
+*vendor/plugins/yaffle/Rakefile:*
+
+[source, ruby]
+----------------------------------------------
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'generators/**/*', 
+  'lib/**/*', 
+  'rails/**/*',
+  'tasks/**/*', 
+  'test/**/*'
+]
+
+spec = Gem::Specification.new do |s| 
+  s.name = "yaffle"
+  s.version = "0.0.1"
+  s.author = "Gleeful Yaffler"
+  s.email = "yaffle@example.com"
+  s.homepage = "http://yafflers.example.com/"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Sharing Yaffle Goodness"
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"
+  s.has_rdoc = false
+  s.extra_rdoc_files = ["README"]
+end
+
+desc 'Turn this plugin into a gem.'
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end 
+----------------------------------------------
+
+To build and install the gem locally, run the following commands:
+
+----------------------------------------------
+cd vendor/plugins/yaffle
+rake gem
+sudo gem install pkg/yaffle-0.0.1.gem
+----------------------------------------------
+
+To test this, create a new rails app, add 'config.gem "yaffle"' to environment.rb and all of your plugin's functionality will be available to you.
\ No newline at end of file