ritual 0.1.1 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,7 @@
+== 0.2.0 2011-02-08
+
+ * Extension support.
+
 == 0.1.1 2011-01-21
 
  * Support custom code in version file. Only the "VERSION =" line is

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 George Ogata
+Copyright (c) George Ogata
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -1,48 +1,110 @@
 # Ritual
 
-Adds tasks and helpers to your Rakefile to manage releases.
+Sweet, simple Rakefiles for your gem.
 
-Much more lightweight than [Jeweler][jeweler] or [Newgem][newgem]. Way less
-flexible, as it's only geared towards my workflow so far.
+Picks up where Bundler leaves off, reducing the entire release ritual
+to a single command.
 
-Like the idea? Feel free to fork and send patches!
+## Example
 
-[jeweler]: http://github.com/technicalpickles/jeweler
-[newgem]: http://github.com/drnic/newgem
+For a plain ruby gem (no extensions), this is usually enough for your
+`Rakefile`:
 
-## Usage
+    require 'ritual'
 
-In `Rakefile`:
+To release a new patch version of your gem:
 
-    gem 'ritual'
-    require 'ritual'
+    rake patch release
+
+The `release` task just runs these tasks:
+
+    rake repo:bump    # Bump and commit the version file and changelog.
+    rake repo:tag     # Tag the release with the current version.
+    rake repo:push    # Push updates upstream.
+    rake gem:build    # Build the gem.
+    rake gem:push     # Push the gem to the gem server.
 
-Adds some shortcuts:
+Select which component to bump with one of these:
 
- * `cucumber_task(*args, &block)`: Define a Cucumber task. Noop if
-   Cucumber cannot be loaded.
- * `spec_task(*args, &block)`: Define an RSpec task. Noop if RSpec
-   cannot be loaded.
- * `rdoc_task(*args, &block)`: Define an rdoc task.
+    rake patch        # Select a patch version bump.
+    rake minor        # Select a minor version bump.
+    rake major        # Select a major version bump.
 
-And some tasks:
+For example:
 
- * `rake major release` 
- * `rake minor release` 
- * `rake patch release` 
-   * Perform the release ritual:
-     * Bump the major/minor/patch version. This is defined in
-       `lib/<library-name>/version.rb.`
-     * Tag the release in git.
-     * Push the git repo to origin.
-     * Build the gem from the gemspec.
-     * Push the gem to Gemcutter.
+ * `rake patch release` will bump 1.2.3 to 1.2.4 and release.
+ * `rake minor release` will bump 1.2.3 to 1.3.0 and release.
+ * `rake major release` will bump 1.2.3 to 2.0.0 and release.
+
+"Release early, release often" has never been so easy!
+
+## Gemspec
 
 You [maintain the gemspec directly][using-gemspecs-as-intended], rather than via
 a wrapper like Jeweler or Hoe.
 
 [using-gemspecs-as-intended]: http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended
 
+## Extensions
+
+Use `extension` to define an extension-building task. Use one of two
+conventions.
+
+### Unnamed extensions
+
+If you only need a single extension, say if you're simply wrapping a C
+library, then use an unnamed extension. In your Rakefile, do:
+
+    extension
+
+This defines a task `ext` to build your extension. Source files live
+in `ext/`, and the extension is named after the gem.
+
+So if the gem is `my_gem`, then Ritual configures your extension with
+`ext/extconf.rb`, runs `make`, and installs `ext/my_gem.DLEXT` to
+`lib/my_gem/my_gem.DLEXT`. (`DLEXT` is the shared library extension,
+which varies from system to system.) `extconf.rb` should contain:
+
+    create_makefile "my_gem"
+
+And the extension entry point is `Init_my_gem`.
+
+### Named extensions
+
+If you need more than one extension, you better name them. Do:
+
+    extension :my_ext
+
+The task is named `ext:my_ext`. Source files live in
+`ext/my_ext/`. Ritual configures the extension with
+`ext/my_ext/extconf.rb`, and installs `ext/my_ext/my_gem.DLEXT` to
+`lib/my_gem/my_ext.DLEXT`. `extconf.rb`, should contain:
+
+    create_makefile "my_gem/my_ext"
+
+And the extension entry point is `Init_my_ext`.
+
+### Customizing
+
+Both `extension` calls above can take options:
+
+ * `:build_as` - The path of the shared library that gets built.
+ * `:install_as` - The path the shared library is installed to.
+
+Both are relative to the Rakefile's directory, and should omit the
+shared library extension.
+
+### JRuby extensions
+
+JRuby doesn't support extensions in the traditional sense (using
+`mkmf`). Instead, you typically build a `.jar` which is packaged into
+the gem.
+
+To build a JRuby extension, pass `:type => :jruby` to
+`extension`. JRuby extensions can be named or unnamed, as above. All
+`.java` files are fed to `javac` simultanously to build the `.jar`,
+which is bundled into the gem by `gem:build`.
+
 ## Note on Patches/Pull Requests
  
  * Bug reports: http://github.com/oggy/ritual/issues
@@ -53,4 +115,4 @@ a wrapper like Jeweler or Hoe.
 
 ## Copyright
 
-Copyright (c) 2010 George Ogata. See LICENSE for details.
+Copyright (c) George Ogata. See LICENSE for details.

data/Rakefile

@@ -1,4 +1,2 @@
 $:.unshift File.expand_path('lib', File.dirname(__FILE__))
 require 'ritual'
-
-spec_task :spec

data/lib/ritual/extension/base.rb

@@ -0,0 +1,56 @@
+module Ritual
+  module Extension
+    class Base
+      DLEXT = Config::CONFIG['DLEXT']
+
+      def initialize(name, params={})
+        @name = name ? name.to_sym : nil
+        library_name = params[:library_name]
+
+        build_path = params[:build_as] and
+          @build_path = "#{build_path}.#{DLEXT}"
+        install_path = params[:install_as] and
+          @install_path = "#{install_path}.#{DLEXT}"
+
+        if name
+          @task_name = "ext:#{name}"
+          @path = params[:path] || "ext/#{name}"
+          @build_path ||= "#{path}/#{name}.#{DLEXT}"
+          @install_path ||= "lib/#{library_name}/#{name}.#{DLEXT}"
+        else
+          @task_name = 'ext'
+          @path = params[:path] || 'ext'
+          @build_path ||= "#{path}/#{library_name}.#{DLEXT}"
+          @install_path ||= "lib/#{library_name}/#{library_name}.#{DLEXT}"
+        end
+
+        CLEAN.include(compiled_paths)
+        CLOBBER.include(@install_path)
+      end
+
+      attr_reader :name, :task_name, :path, :build_path, :install_path
+
+      def define_tasks
+        raise NotImplementedError, 'abstract'
+      end
+
+      protected
+
+      def source_paths
+        raise NotImplementedError, 'abstract'
+      end
+
+      def compiled_path_for(source_path)
+        raise NotImplementedError, 'abstract'
+      end
+
+      def compiled_paths
+        @compiled_paths ||= source_paths.map { |s| compiled_path_for(s) }
+      end
+
+      def relative_path(absolute_path)
+        Pathname(absolute_path).relative_path_from(Pathname(path))
+      end
+    end
+  end
+end