Gemma is a gem development helper like hoe and jeweler, but it keeps the gemspec in a gemspec file, where it belongs, instead of in your Rakefile. This helps your gem to play nicely with commands like gem and bundle, and it allows gemma to provide rake tasks with sensible defaults for many common gem development tasks.
See also yehudakatz.com/2010/04/02/using-gemspecs-as-intended for more background.
To Create a New Gem
Gemma has a simple interactive gem scaffolding tool; run
and follow the prompts. (Run with -h for help.)
This gives you a simple gem template like the following:
my_new_gem |-- bin | +-- my_new_gem # executable (optional) |-- .gitignore # helpful if you're using git |-- lib | |-- my_new_gem | | +-- version.rb # the one and only version constant | +-- my_new_gem.rb # the main code file |-- my_new_gem.gemspec # gem metadata |-- Rakefile.rb # development tasks |-- README.rdoc # documentation +-- test +-- test_my_new_gem.rb # unit tests with test/unit (optional)
Things you need to change in the template are marked with a TODO tag.
To Modify an Existing Gem to use Gemma
First you have to have a .gemspec file. See yehudakatz.com/2010/04/02/using-gemspecs-as-intended for a template and advice, and see docs.rubygems.org/read/chapter/20 for reference material. If you have been using hoe or jeweler, you already have all of the information in your Rakefile, so you just have to move it into a .gemspec file.
Gemma provides rake tasks with sensible defaults based on the contents of your gemspec; to enable them, add the following to the top of your Rakefile:
begin require 'rubygems' require 'gemma' Gemma::RakeTasks.with_gemspec_file 'my_gem.gemspec' rescue LoadError # Gemma is not installed; print an (optional) message: puts "Install gemma (sudo gem install gemma) for standard rake tasks." end
This gives you some standard rake tasks, in addition to any that you define yourself. (Note that the yard task only appears if you have the yard (yardoc) gem installed.)
rake clean # Remove any temporary products. rake clobber # Remove any generated file. rake rcov # Analyze code coverage with tests rake rdoc # Build the rdoc HTML Files rake test # Run tests rake yard # Generate YARD Documentation ... and more!
Run rake -T for a full list of tasks.
You can customize the standard tasks by passing a block to with_gemspec_file:
Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec' do |g| g.rdoc.title = 'My Gem Is Great' end
See the gemma API docs for more information.
You must have ruby, rubygems and rake installed. Tasks are also included for rcov (eigenclass.org/hiki.rb?rcov) and yard (yardoc.org/), if you have them installed. Other dependencies are handled automatically.
Gemma has been tested on:
x86-linux (Ubuntu 10.10) with Ruby 1.8.7p299
x86-linux (rvm) with Ruby 1.9.2p0 (2010-08-18 revision 29036)
x86_64-linux (CentOS) with Ruby 1.8.7p72
with yard 0.5.8 and 0.6.3
with rcov 0.9.7.1 and 0.9.9
Gemma has not yet been tested on Windows.
sudo gem install gemma
To get the source and development depencies:
git clone git://github.com/jdleesmiller/gemma.git cd gemma gem build gemma.gemspec sudo gem install gemma-X.X.X.gem --development
where X.X.X is the current gemma version.
There are many projects that help to automate common gem development tasks. Hoe and Jeweler are the most popular; they generate the gemspec and tasks using a configuration specified in the Rakefile, which is the opposite to what gemma does. Mr Bones is a gem template generator that appears to be similar to Hoe and Jeweler, but I haven't used it myself.
Bundler also provides some support for gem development. It includes a simple gem scaffolding generator, and the results are compatible with gemma. It also includes some rake extensions for building, installing and releasing gems (Bundler::GemHelper). (As of version 1.0.7.)
gemesis provides tasks for building, releasing and installing gems based on the gemspec, but (at the time of writing) it doesn't provide tasks for tests and documentation, etc.
rake-compiler provides support for compiling native extensions from a gemspec, and it looks like it should work fairly well with gemma.
Rhesus is a generic generate-from-template tool:
Other helpful articles:
make it easier to add custom tasks and / or new task generators, as in
# DOES NOT WORK YET Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec' do |g| g.yard_dev = Gemma::RakeTasks::YardTasks.new(g.gemspec, :yard_dev) g.yard_dev.output = 'dev_docs' g.yard_dev.options.push('--protected', '--private') end
more tasks (e.g. to publish docs)
tasks for version control? (see github.com/nvie/gitflow)
changed rdoc and yard tasks to use require_paths instead of files
Copyright © 2010 John Lees-Miller
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.