gemma 1.0.0 → 2.0.0

data/README.rdoc

@@ -2,18 +2,27 @@
 
 http://github.com/jdleesmiller/gemma
 
+http://github.com/jdleesmiller/gemma/wiki
+
 == 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
++gemspec+ in a <tt>.gemspec</tt> file, instead of in a +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 http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended for more
-background.
+See http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended for some reasons
+why you probably want a <tt>.gemspec</tt> file in your gem's repository.
+
+=== Usage
+
+See the project wiki for tutorials and guides:
+https://github.com/jdleesmiller/gemma/wiki
+
+Briefly:
 
-=== To Create a New Gem
+==== Create a New Gem
 
 Gemma has a simple interactive gem scaffolding tool; run
   gemma new
@@ -21,57 +30,59 @@ and follow the prompts. (Run with -h for help.)
 
 This gives you a simple gem template like the following:
 
-  my_new_gem
+  my_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)
+  |   `-- my_gem           # executable (optional)
+  |-- Gemfile              # for bundler (see below)
+  |-- lib                  
+  |   |-- my_gem           # most of your code goes here
+  |   |   `-- version.rb   # the version constant
+  |   `-- my_gem.rb        # the main code file
+  |-- my_gem.gemspec       # gem metadata
+  |-- Rakefile.rb          # development tasks
+  |-- README.rdoc          # documentation
+  `-- test                 # unit tests go here
+      `-- my_gem
+          `-- my_gem_test.rb
 
 Things you need to change in the template are marked with a +TODO+ tag.
 
-=== To Modify an Existing Gem to use Gemma
+==== To Modify an Existing Gem to use Gemma
 
-First you have to have a <tt>.gemspec</tt> file. See
-http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended
-for a template and advice, and see
-http://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 <tt>.gemspec</tt> file.
+The main thing you need is a <tt>.gemspec</tt> file. 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 <tt>.gemspec</tt> 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
+
+  require 'rubygems'
+  require 'bundler/setup'
+  require 'gemma'
+
+  Gemma::RakeTasks.with_gemspec_file 'my_gem.gemspec'
+
+  task :default => :test
 
 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.)
+yourself.
+
+==== The Standard Tasks
+
+Run <tt>rake -T</tt> for a full list of tasks.
 
+  % rake -T
+  rake build         # Build my_gem-0.0.1.gem into the pkg directory
   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 clobber_rdoc  # Remove RDoc HTML files
+  rake install       # Build and install my_gem-0.0.1.gem into system gems
+  rake my_gem[args]  # run my_gem
+  rake rdoc          # Build RDoc HTML files
+  rake release       # Create tag v0.0.1 and build and push my_gem-0.0.1.gem ...
+  rake rerdoc        # Rebuild RDoc HTML files
   rake test          # Run tests
   rake yard          # Generate YARD Documentation
-  ... and more!
-
-Run <tt>rake -T</tt> for a full list of tasks.
 
 You can customize the standard tasks by passing a block to +with_gemspec_file+:
 
@@ -83,68 +94,27 @@ See the gemma API docs for more information.
 
 == REQUIREMENTS
 
-You must have ruby, rubygems and rake installed. Tasks are also included for
-rcov (http://eigenclass.org/hiki.rb?rcov) and yard (http://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.
+* ruby 1.9.2p290 (2011-07-09 revision 32553) [i686-linux] and [x86_64-linux]
+* ruby 1.8.7 (2011-06-30 patchlevel 352) [i686-linux] and [x86_64-linux]
+
+Gemma has not yet been tested on Windows or Mac OS X.
 
 == INSTALLATION
 
-On *nix:
+On RVM:
+  gem install gemma
 
+On a system ruby:
   sudo gem install gemma
 
 == DEVELOPMENT
 
-To get the source and development depencies:
+  gem install bundler
   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.
-
-* http://seattlerb.rubyforge.org/hoe/
-* http://github.com/technicalpickles/jeweler 
-* http://codeforpeople.rubyforge.org/bones/ 
-
-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.)
-* http://gembundler.com
-* http://gembundler.com/rubygems.html
-
-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.
-
-* http://github.com/markryall/gemesis/tree/master/lib/gemesis
-
-rake-compiler provides support for compiling native extensions from a
-gemspec, and it looks like it should work fairly well with gemma.
-
-* http://github.com/luislavena/rake-compiler
-
-
-Other helpful articles:
-
-* http://rubygems.rubyforge.org/rubygems-update/Gem/Version.html
-* http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ 
+  bundle
+  rake -T # list development tasks
 
 == TODO
 
@@ -156,11 +126,20 @@ Other helpful articles:
       g.yard_dev.options.push('--protected', '--private')
     end
 * more tasks (e.g. to publish docs)
-* tasks for version control? (see http://github.com/nvie/gitflow)
+* more tasks to support C extensions
+* hooks for the rcov and/or simplecov coverage tools
+* tasks for version control? (e.g. based on http://github.com/nvie/gitflow)
 * contributions welcome!
 
 == HISTORY
 
+<em>2.0.0</em>
+* now relies on bundler
+* now specifies particular gem version that must be used for rake, rdoc and
+  yard; the old approach was to try to work with whatever was already installed,
+  but this proved too fragile
+* removed rcov support, because it doesn't work on 1.9.x (see simplecov)
+
 <em>1.0.0</em>
 * added templates
 * changed rdoc and yard tasks to use +require_paths+ instead of +files+ 

data/bin/gemma

@@ -111,7 +111,7 @@ end
 templates = opts['--template']
 if templates.empty?
   if interactive
-    templates << 'base' << 'test_unit'
+    templates << 'base' << 'minitest'
     hl.choose do |menu|
       menu.prompt = "type of gem: "
       menu.shell = true

data/lib/gemma.rb

@@ -1,3 +1,5 @@
+require 'shellwords'
+
 require 'gemma/version'
 require 'gemma/utility'
 require 'gemma/options'
@@ -5,11 +7,11 @@ require 'gemma/rake_tasks'
 
 # Load default Rakefile plugins:
 require 'gemma/rake_tasks/plugin'
-require 'gemma/rake_tasks/rcov_tasks'
 require 'gemma/rake_tasks/rdoc_tasks'
 require 'gemma/rake_tasks/run_tasks'
 require 'gemma/rake_tasks/yard_tasks'
-require 'gemma/rake_tasks/test_unit_tasks'
+require 'gemma/rake_tasks/minitest_tasks'
+require 'gemma/rake_tasks/gem_tasks'
 
 require 'gemma/conventions'
 require 'gemma/gem_from_template'

data/lib/gemma/conventions.rb

@@ -1,37 +1,32 @@
 module Gemma
   #
-  # A home for conventions, advice and best practices.
+  # Methods to check input against accepted conventions.
+  #
+  # For help on extensions:
+  # * http://nokogiri.org/tutorials/installing_nokogiri.html explains how to
+  # prepare several unices to build native extensions. 
+  #
+  # General objectives for gemma:
+  # * follow and promote accepted conventions where obvious
+  # * make the outputs from rdoc, test, etc. work like they do in rubygems
+  # * avoid load path noise ($: << ...)
+  # * make it easy to start hacking on an existing gem that uses gemma
+  #   - git clone ...
+  #   - gem install bundle
+  #   - bundle # install both gemma dependencies and the gem's dependencies
+  #   - rake -T # should now work
   #
   module Conventions
-    #
-    # References:
-    # http://stackoverflow.com/questions/221320/standard-file-naming-conventions-in-ruby
-    # http://containerdiv.wordpress.com/2009/05/24/ruby-gems-vs-rails-plugins/
-    #
-    # There is probably a required format (regex) for names, but I've never
-    # figured out what it is. It should be a valid file/directory name on
-    # Windows.
-    #
-    GOOD_GEM_NAME_TIPS = <<-STRING
-    Some tips for good gem names:
-      * use lower case
-      * separate words with _ (underscore)
-      * don't put 'ruby' in the name; this is implied, because it's a rubygem
-
-    It is also common to use a hyphen (-) to separate words.
-
-    If your gem name is my_new_gem, it can be installed with
-      sudo gem install my_new_gem
-    used in scripts with
-      require 'rubygems'
-      require 'my_new_gem'
-    and its contents should be contained in a module or class called MyNewGem.
-    STRING
-
     #
     # Check gem naming conventions; this is sufficient but not necessary for
     # the gem name to be valid.
     #
+    # References:
+    # * http://guides.rubygems.org/patterns/
+    # * http://blog.segment7.net/articles/2010/11/15/how-to-name-gems
+    # * http://stackoverflow.com/questions/221320/standard-file-naming-conventions-in-ruby
+    # * http://containerdiv.wordpress.com/2009/05/24/ruby-gems-vs-rails-plugins/
+    #
     # @return [Boolean]
     #
     def self.good_gem_name? gem_name

data/lib/gemma/gem_from_template.rb

@@ -17,7 +17,7 @@ module Gemma
     # there are files that occur in multiple templates (files in earlier
     # templates are overwritten by those in later templates, at present).
     #
-    BUILTIN_TEMPLATES = %w(base executable test_unit)
+    BUILTIN_TEMPLATES = %w(base executable minitest)
 
     def initialize
       @gem_name = nil
@@ -78,18 +78,12 @@ module Gemma
       File.expand_path(File.join('.',self.dir_name))
     end
 
-    #
-    # Gem version requirement for the development dependency on gemma.
-    #
-    # @return [String]
-    #
-    def gemma_version_requirement 
-      "~> #{Gemma::VERSION.split(/\./).take(2).join('.')}"
-    end
-
     #
     # Copy given templates to +destination_path+ and run erb where needed.
     #
+    # @param [Array<String>] template_paths absolute paths of the template
+    #        directories to copy
+    #
     def create_gem template_paths, destination_path=self.destination_path
       raise "destination #{destination_path} exists" if File.exists?(
         destination_path)

data/lib/gemma/options.rb

@@ -33,20 +33,24 @@ module Gemma
     # Matching options that appear after a `--` terminator are not extracted;
     # they remain in the {ExtractResult#remaining_options} list.
     #
+    # The +options+ parameter takes an array of arguments; to split a string
+    # into the appropriate form, you can use the +Shellwords+ module in the ruby
+    # standard library.  
+    #
     # @example
     #   Gemma::Options.extract(%w(-a), %w(-a foo bar.txt))
     #   #=> #<struct Gemma::Options::ExtractResult argument="foo",
     #   #     remaining_options=["bar.txt"]>
     #
     # @param [Array<String>] names one or more names for the option to extract
-    # (`['--file','-f']`, for example)
+    #        (`['--file','-f']`, for example)
     #
     # @param [Array<String>] options to extract from; you should ensure that
-    # there isn't leading/trailing whitespace (strip), because this method
-    # doesn't detect it
+    #        there isn't leading/trailing whitespace (strip), because this
+    #        method doesn't detect it
     #
     # @return [ExtractResult] contains the argument for the given option and the
-    # rest of the options
+    #         rest of the options
     #
     def self.extract names, options
       options = options.dup

data/lib/gemma/rake_tasks.rb

@@ -8,6 +8,7 @@ module Gemma
   # @example To create the default tasks based on your _mygem_.gemspec file:
   #   # At the top of Rakefile.rb.
   #   require 'rubygems'
+  #   require 'bundler/setup'
   #   require 'gemma'
   #
   #   Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec'
@@ -22,7 +23,7 @@ module Gemma
     end
 
     #
-    # Constructor for internal use; you should usually use the
+    # Constructor mainly for internal use; you should usually use the
     # `with_gemspec_file` alias (see examples in {RakeTasks}).
     #
     # @param [String, Gem::Specification] gemspec either the name of a gemspec
@@ -43,7 +44,7 @@ module Gemma
         @gemspec_file_name = nil
         @gemspec = gemspec
       else
-        raise ArgumentError
+        raise ArgumentError, 'bad gemspec argument'
       end
 
       @plugins = {}
@@ -82,11 +83,6 @@ module Gemma
     #
     attr_reader :plugins
 
-    #
-    # @return [RcovTasks] 
-    #
-    def rcov; @plugins[:rcov] end
-
     #
     # @return [RDocTasks] 
     #
@@ -98,7 +94,7 @@ module Gemma
     def run; @plugins[:run] end
 
     #
-    # @return [TestUnitTasks]
+    # @return [MinitestTasks]
     #
     def test; @plugins[:test] end
 
@@ -107,14 +103,19 @@ module Gemma
     #
     def yard; @plugins[:yard] end
 
+    #
+    # @return [GemTasks]
+    #
+    def gem; @plugins[:gem] end
+
     protected
 
     def create_default_plugins
-      @plugins[:rcov] = Gemma::RakeTasks::RcovTasks.new(gemspec)
       @plugins[:rdoc] = Gemma::RakeTasks::RDocTasks.new(gemspec)
       @plugins[:run]  = Gemma::RakeTasks::RunTasks.new(gemspec)
-      @plugins[:test] = Gemma::RakeTasks::TestUnitTasks.new(gemspec)
+      @plugins[:test] = Gemma::RakeTasks::MinitestTasks.new(gemspec)
       @plugins[:yard] = Gemma::RakeTasks::YardTasks.new(gemspec)
+      @plugins[:gem] = Gemma::RakeTasks::GemTasks.new(gemspec,gemspec_file_name)
     end
   end
 end

data/lib/gemma/rake_tasks/gem_tasks.rb

@@ -0,0 +1,38 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks for building and releasing gems.
+    #
+    # Note that the +release+ task is git-specific, but the other tasks are not
+    # specific to any particular version control system.
+    #
+    # This plugin just calls <tt>Bundler::GemHelper</tt> with the given gemspec.
+    #
+    class GemTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      # @param [String, nil] gemspec_file_name
+      #
+      def initialize gemspec, gemspec_file_name
+        super(gemspec)
+        @gemspec_file_name = gemspec_file_name
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks
+        require 'bundler/gem_helper'
+        dir = File.dirname(@gemspec_file_name) if @gemspec_file_name
+        Bundler::GemHelper.install_tasks(:dir => dir,
+                                         :name => gemspec.name)
+        nil
+      end
+    end
+  end
+end
+