Skip to content
Generate helpful rake tasks from your gemspec.
Find file
Pull request Compare This branch is 65 commits behind jdleesmiller:develop.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin
lib
template
test
.gitignore
README.rdoc
Rakefile.rb
gemma.gemspec

README.rdoc

gemma

github.com/jdleesmiller/gemma

SYNOPSIS

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

gemma new

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.

REQUIREMENTS

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.

INSTALLATION

On *nix:

sudo gem install gemma

DEVELOPMENT

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.

RELATED PROJECTS

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:

TODO

  • 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)

  • contributions welcome!

HISTORY

1.0.0

  • added templates

  • changed rdoc and yard tasks to use require_paths instead of files

  • more tests

  • more documentation

0.0.2

  • minor fixes

0.0.1

  • first release

LICENSE

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.

Something went wrong with that request. Please try again.