rake-compiler 0.3.0

data/History.txt

@@ -0,0 +1,32 @@
+=== 0.3.0 / 2008-12-07
+
+* 1 Major Enhancement:
+
+  * Let you specify the Ruby version used for cross compilation instead 
+    of default one.
+
+      rake cross compile RUBY_CC_VERSION=1.8
+
+* 2 Minor Enhancements:
+
+  * Properly update rake-compiler configuration when new version is installed.
+  * Automated release process to RubyForge, yay!
+
+* 1 Bug fix:
+
+  * Corrected documentation to reflect the available options
+
+=== 0.2.1 / 2008-11-30
+
+* 2 Major Enhancements:
+
+  * Allow cross compilation (cross compile) using mingw32 on Linux or OSX.
+  * Allow packaging of gems for Windows on Linux or OSX.
+
+* 1 Minor Enhancement:
+
+  * Made generation of extensions safe and target folders per-platform
+
+* 1 Bug Fix:
+
+  * Ensure binaries for the specific platform are copied before packaging.

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Luis Lavena.
+
+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.

data/README.rdoc

@@ -0,0 +1,258 @@
+= rake-compiler
+
+rake-compiler aims to help Gem developers while dealing with Ruby C
+extensions, simplifiying the code and reducing the duplication.
+
+It follows *convention over configuration* and set an standarized 
+structure to build and package C extensions in your gems.
+
+This is the result of expriences dealing with several Gems that required 
+native extensions across platforms and different user configurations 
+where details like portability and clarity of code were lacking.
+
+== An Overview
+
+Let's summarize what rake-compiler provides:
+
+* No custom rake tasks required. Less code duplication and errors.
+
+* Painlessly build extensions on different platforms (Linux, OSX and Windows).
+
+* Allow multiple extensions be compiled inside the same gem.
+
+* Mimics RubyGems installation process, so helps as test environment.
+
+* Simplify cross platform compilation of extensions (target Windows from Linux).
+
+== I'm sold! show me how to use it! (Installation)
+
+Usage of rake-compiler is pretty much straight forward.
+
+First, you need to install the gem:
+
+  $ gem install rake-compiler
+
+Since this package is in constant evolution, you could try installing it
+from GitHub:
+
+  $ gem install luislavena-rake-compiler --source http://gems.github.com
+
+The development gem is usually in pretty good shape actually.
+
+== Now what? (Usage)
+
+Now that you have the gem installed, let's give your project some structure.
+
+=== Structure
+
+Let's say we want to compile an extension called 'hello_world', so we should
+organize the code and folders that will help rake-compiler do it's job:
+
+    |-- ext
+    |   `-- hello_world
+    |       |-- extconf.rb
+    |       `-- hello_world.c
+    |-- lib
+    `-- Rakefile
+
+TIP: Having a consistent folder structure will help developers and newcomers
+to find code and also contribute back to your project more easily.
+
+=== Adding the code
+
+So now it's time to introduce the code to compile our extension:
+
+    # File: Rakefile
+    
+    require 'rake/extensiontask'
+    
+    Rake::ExtensionTask.new('hello_world')
+
+Ok, that's it. No other line of code.
+
+=== Compile process
+
+Those *two* lines of code automatically added the needed rake tasks to build
+the hello_world extension:
+
+  $ rake -T
+  (in /home/user/my_extesion)
+  rake compile                # Compile the extension(s)
+  rake compile:hello_world    # Compile just the hello_world extension
+
+Simply calling <tt>compile</tt>:
+
+  $ rake compile
+
+Will do all the compile process for us, putting the result extension inside
+<tt>lib</tt> directory.
+
+NOTE: Please be aware that building C extensions requires the proper
+development environment for your Platform, which includes libraries, headers
+and build tools. Check your distro / vendor documentation on how to install it.
+
+=== Generate native gems
+
+A common usage scenario of rake-compiler is generate native gems that bundles
+your extensions.
+
+This got over-simplified with <tt>Rake::ExtensionTask</tt>:
+
+    # somewhere in your Rakefile, define your gem spec
+    spec = Gem::Specification.new do |s|
+      s.name = "my_gem"
+      s.platform = Gem::Platform::RUBY
+      s.extensions = FileList["ext/**/extconf.rb"]
+    end
+
+    # add your default gem packing task
+    Rake::GemPackageTask.new(spec) do |pkg|
+    end
+
+    # feed your ExtensionTask with your spec
+    Rake::ExtensionTask.new('hello_world', spec)
+
+Now, as usual, you can build your pure-ruby gem (standard output):
+
+  $ rake gem
+  (in /projects/oss/my_gem.git)
+  mkdir -p pkg
+    Successfully built RubyGem
+    Name: my_gem
+    Version: 0.1.0
+    File: my_gem-0.1.0.gem
+  mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
+
+Plus, you have the functionality to build native versions of the gem:
+
+  # rake native gem
+  (... compilation output ...)
+  mkdir -p pkg
+    Successfully built RubyGem
+    Name: my_gem
+    Version: 0.1.0
+    File: my_gem-0.1.0.gem
+  mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
+    Successfully built RubyGem
+    Name: my_gem
+    Version: 0.1.0
+    File: my_gem-0.1.0-x86-mingw32.gem
+  mv my_gem-0.1.0-x86-mingw32.gem pkg/my_gem-0.1.0-x86-mingw32.gem
+
+You get two gems for the price of one.
+
+=== What about breaking the standards? (Customization)
+
+In case you want to bend the convention established, rake-compiler let you
+personalize several settings for <tt>Rake::ExtensionTask</tt>:
+
+    Rake::ExtensionTask.new do |ext|
+      ext.name = 'hello_world'                # indicate the name of the extension.
+      ext.ext_dir = 'ext/weird_world'         # search for 'hello_world' inside it.
+      ext.lib_dir = 'lib/my_lib'              # put binaries into this folder.
+      ext.config_script = 'custom_extconf.rb' # use instead of 'extconf.rb' default
+      ext.tmp_dir = 'tmp'                     # temporary folder used during compilation.
+      ext.source_pattern = "*.{c,cpp}"        # monitor file changes to allow simple rebuild.
+      ext.config_options << '--with-foo'      # supply additional configure options to config script.
+      ext.gem_spec = spec                     # optional indicate which gem specification
+                                              # will be used to based on.
+    end
+
+== Future is now: Cross compilation
+
+rake-compiler provides now an standarized way to generate, from Linux or OSX
+both extensions and gem binaries for Windows!
+
+It takes advantages from GCC host/target to build binaries (for target) on 
+different OS (hosts).
+
+=== How I enjoy this?
+
+Besides having the development tool chain installed (GCC), you should install
+also <tt>mingw32</tt> cross compilation package.
+
+Dependending on your operating system distribution, a simple <tt>apt-get install mingw32</tt>
+will be enough.
+
+Please check OSX documentation about installing mingw32 from macports.
+
+=== I have my toolchain, now what?
+
+You need to build Ruby for Windows.
+
+Relax, no need to freak out. rake-compiler do it for you:
+
+  rake-compiler cross-ruby
+
+And you're done. It will automatically download, configure and compile latest
+stable version of Ruby for Windows, and place it into <tt>~/.rake-compiler</tt>
+
+If, instead, you want to build another version than the default one, please
+supply a <tt>VERSION</tt>:
+
+  rake-compiler cross-ruby VERSION=1.8.6-p114
+
+=== Let's build some gems!
+
+Now, you only need to use additional options in your extension defintion:
+
+    Rake::ExtensionTask.new('my_extension', gem_spec) do |ext|
+      ext.cross_compile = true                # enable cross compilation (requires cross compile toolchain)
+      ext.cross_platform = 'i386-mswin32'     # forces the Windows platform instead of the default one
+                                              # configure options only for cross compile
+      ext.cross_config_options << '--with-something'
+    end
+
+By default, cross compilation targets 'i386-mingw32' which is default GCC platform
+for Ruby.
+
+To target gems for current Ruby official distribution, please force the platform
+to the one shown before.
+
+=== Magician doing some tricks, don't blink!
+
+Compiles keeps being simple:
+
+  rake cross compile
+
+And now, build your gems for Windows is just 5 more letters:
+
+  rake cross native gem
+
+And you're done, yeah.
+
+=== Take it even further
+
+You can specify against with version of Ruby you want to build the extension:
+
+  rake cross compile RUBY_CC_VERSION=1.8
+
+If you installed <tt>1.9.1</tt>, you can do:
+
+  rake cross compile RUBY_CC_VERSION=1.9
+
+== Future
+
+rake-compiler is a work in progress and we will appreciate feedback during the
+development of it! (and contributions too!)
+
+You can find more information about rake-compiler:
+
+Blog:      http://blog.mmediasys.com
+RubyForge: http://rubyforge.org/projects/rake-compiler
+GitHub:    http://github.com/luislavena/rake-compiler
+
+=== Some of the desired features
+
+* <tt>Rake::JavaJarTask</tt> to generate <tt>jar</tt> packages and gems for JRuby.
+
+  $ rake java gem
+
+== Disclaimer
+
+If you have any trouble, don't hesitate to contact the author. As always,
+I'm not going to say "Use at your own risk" because I don't want this library
+to be risky.
+
+If you trip on something, I'll share the liability by repairing things
+as quickly as I can. Your responsibility is to report the inadequacies.

data/Rakefile

@@ -0,0 +1,23 @@
+#--
+# Copyright (c) 2008 Luis Lavena
+#
+# This source code is released under the MIT License.
+# See LICENSE file for details
+#++
+
+#
+# NOTE: Keep this file clean.
+# Add your customizations inside tasks directory.
+# Thank You.
+#
+
+begin
+  require 'rake'
+rescue LoadError
+  require 'rubygems'
+  gem 'rake', '~> 0.8.3.1'
+  require 'rake'
+end
+
+# load rakefile extensions (tasks)
+Dir['tasks/*.rake'].each { |f| import f }

data/bin/rake-compiler

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright (c) 2008 Luis Lavena
+#
+# This source code is released under the MIT License.
+# See LICENSE file for details
+#++
+
+begin
+  require 'rake'
+rescue LoadError
+  require 'rubygems'
+  require 'rake'
+end
+
+# Initialize 'rake-compiler' application
+Rake.application.init('rake-compiler')
+
+# Load the already cooked tasks ;-)
+load File.join(File.dirname(__FILE__), %w{.. tasks bin cross-ruby.rake})
+
+# delegate control to Rake
+Rake.application.top_level

data/cucumber.yml

@@ -0,0 +1 @@
+autotest: --format progress features

data/features/compile.feature

@@ -0,0 +1,71 @@
+Feature: Compile C code into Ruby extensions.
+
+  In order to automate compilation process.
+  As a Gem developer.
+  I want rake tasks compile source code for me.
+
+  Scenario: compile single extension
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And 'tmp' folder is deleted
+    When rake task 'compile' is invoked
+    Then rake task 'compile' succeeded
+    And binary extension 'extension_one' do exist in 'lib'
+    And 'tmp' folder is created
+
+  Scenario: not recompile unmodified extension
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    And not changed any file since
+    When rake task 'compile' is invoked
+    Then rake task 'compile' succeeded
+    And output of rake task 'compile' do not contain /gcc|cl/
+
+  Scenario: recompile extension when source is modified
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    When touching 'source.c' file of extension 'extension_one'
+    And rake task 'compile' is invoked
+    Then rake task 'compile' succeeded
+    And output of rake task 'compile' contains /extension_one/
+
+  Scenario: compile multiple extensions
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And a extension named 'extension_two'
+    And 'tmp' folder is deleted
+    When rake task 'compile' is invoked
+    Then rake task 'compile' succeeded
+    And binary extension 'extension_one' do exist in 'lib'
+    And binary extension 'extension_two' do exist in 'lib'
+    And 'tmp' folder is created
+
+  Scenario: compile one extension instead of all present
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And a extension named 'extension_two'
+    When rake task 'compile:extension_one' is invoked
+    Then rake task 'compile:extension_one' succeeded
+    And output of rake task 'compile:extension_one' do not contain /extension_two/
+    And binary extension 'extension_one' do exist in 'lib'
+    And binary extension 'extension_two' do not exist in 'lib'
+
+  Scenario: removing temporary files
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    When rake task 'clean' is invoked
+    Then rake task 'clean' succeeded
+    And binary extension 'extension_one' do exist in 'lib'
+    And no left over from 'extension_one' remains in 'tmp'
+
+  Scenario: clobbering binary and temporary files
+    Given a safe project directory
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    When rake task 'clobber' is invoked
+    Then rake task 'clobber' succeeded
+    And binary extension 'extension_one' do not exist in 'lib'
+    And 'tmp' folder do not exist

data/features/cross-compile.feature

@@ -0,0 +1,13 @@
+Feature: Cross-compile C extensions
+
+  In order to avoid bitching from Windows users
+  As a Ruby developer on Linux
+  I want some rake tasks that take away the pain of compilation
+
+  Scenario: compile single extension
+    Given that all my source files are in place
+    And I'm running a POSIX operating system
+    And I've installed cross compile toolchain
+    When rake task 'cross compile' is invoked
+    Then rake task 'cross compile' succeeded
+    And binaries for platform 'i386-mingw32' get generated

data/features/cross-package.feature

@@ -0,0 +1,14 @@
+Feature: Generate Windows gems from Linux
+
+  In order to keep sanity in the Ruby world
+  As a Gem developer on Linux
+  I want more rake magic that turns monotony into joy.
+
+  Scenario: package a gem for Windows
+    Given that my gem source is all in place
+    And I'm running a POSIX operating system
+    And I've installed cross compile toolchain
+    And I've already successfully executed rake task 'cross compile'
+    When rake task 'cross native gem' is invoked
+    Then rake task 'cross native gem' succeeded
+    And gem for platform 'x86-mingw32' get generated

data/features/package.feature

@@ -0,0 +1,40 @@
+Feature: Distribute native extension with gems
+
+  In order to avoid compiler toolchain requirement during installation
+  As a Gem developer.
+  I want rake tasks generate platform specific gems for me
+
+  Scenario: generate pure ruby gem
+    Given a safe project directory
+    And a gem named 'my_project'
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    And 'pkg' folder is deleted
+    When rake task 'gem' is invoked
+    Then rake task 'gem' succeeded
+    And 'pkg' folder is created
+    And ruby gem for 'my_project' version '0.1.0' do exist in 'pkg'
+
+  Scenario: generate native gem
+    Given a safe project directory
+    And a gem named 'my_project'
+    And a extension named 'extension_one'
+    And I've already successfully executed rake task 'compile'
+    And 'pkg' folder is deleted
+    When rake task 'native gem' is invoked
+    Then rake task 'native gem' succeeded
+    And 'pkg' folder is created
+    And ruby gem for 'my_project' version '0.1.0' do exist in 'pkg'
+    And binary gem for 'my_project' version '0.1.0' do exist in 'pkg'
+
+  Scenario: generate forced native gem
+    Given a safe project directory
+    And a gem named 'my_project'
+    And a extension 'extension_one' with forced platform 'universal-unknown'
+    And I've already successfully executed rake task 'compile'
+    And 'pkg' folder is deleted
+    When rake task 'native:universal-unknown gem' is invoked
+    Then rake task 'native:universal-unknown gem' succeeded
+    And 'pkg' folder is created
+    And ruby gem for 'my_project' version '0.1.0' do exist in 'pkg'
+    And a gem for 'my_project' version '0.1.0' platform 'universal-unknown' do exist in 'pkg'

data/features/step_definitions/compilation.rb

@@ -0,0 +1,43 @@
+Given /^a extension named '(.*)'$/ do |extension_name|
+  generate_extension_task_for extension_name
+  generate_source_code_for extension_name
+end
+
+Given /^a extension cross-compilable '(.*)'$/ do |extension_name|
+  generate_cross_compile_extension_task_for extension_name
+  generate_source_code_for extension_name
+end
+
+Given /^a extension '(.*)' with forced platform '(.*)'$/ do |extension_name, forced_platform|
+  generate_extension_task_for extension_name, forced_platform
+  generate_source_code_for extension_name
+end
+
+Given /^that all my source files are in place$/ do
+  Given "a safe project directory"
+  Given "a extension cross-compilable 'extension_one'"
+end
+
+Given /^that my gem source is all in place$/ do
+  Given "a safe project directory"
+  Given "a gem named 'gem_abc'"
+  Given "a extension cross-compilable 'extension_one'"
+end
+
+Given /^not changed any file since$/ do
+  # don't do anything, that's the purpose of this step!
+end
+
+When /^touching '(.*)' file of extension '(.*)'$/ do |file, extension_name|
+  Kernel.sleep 1
+  FileUtils.touch "ext/#{extension_name}/#{file}"
+end
+
+Then /^binary extension '(.*)' (do|do not) exist in '(.*)'$/ do |extension_name, condition, folder|
+  ext_for_platform = File.join(folder, "#{extension_name}.#{RbConfig::CONFIG['DLEXT']}")
+  if condition == 'do'
+    File.exist?(ext_for_platform).should be_true
+  else
+    File.exist?(ext_for_platform).should be_false
+  end
+end

data/features/step_definitions/cross_compilation.rb

@@ -0,0 +1,21 @@
+# Naive way of looking into platforms, please include others like FreeBSD?
+Given %r{^I'm running a POSIX operating system$} do
+  unless RUBY_PLATFORM =~ /linux|darwin/ then
+    raise Cucumber::Pending.new("You need a POSIX operating system, no cheating ;-)")
+  end
+end
+
+Given %r{^I've installed cross compile toolchain$} do
+  compiler = 'i586-mingw32msvc-gcc'
+  found = false
+  ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
+    next unless File.exist?(File.join(path, compiler))
+    found = true
+  end
+  raise "Cannot locate '#{compiler}' in the PATH." unless found
+end
+
+Then /^binaries for platform '(.*)' get generated$/ do |platform|
+  ext_for_platform = Dir.glob("tmp/#{platform}/**/*.#{RbConfig::CONFIG['DLEXT']}")
+  ext_for_platform.should_not be_empty
+end

data/features/step_definitions/execution.rb

@@ -0,0 +1,30 @@
+Given %r{^I've already successfully executed rake task '(.*)'$} do |task_name|
+  emptyness = `rake #{task_name} 2>&1`
+  unless $?.success?
+    warn emptyness
+    raise "rake failed with #{$?.exitstatus}"
+  end
+end
+
+When /^rake task '(.*)' is invoked$/ do |task_name|
+  @output ||= {}
+  @result ||= {}
+  @output[task_name] = `rake #{task_name} 2>&1`
+  @result[task_name] = $?.success?
+end
+
+Then /^rake task '(.*)' succeeded$/ do |task_name|
+  if @result.nil? || !@result.include?(task_name) then
+    raise "The task #{task_name} should be invoked first."
+  else
+    @result[task_name].should be_true
+  end
+end
+
+Then /^output of rake task '(.*)' (contains|do not contain) \/(.*)\/$/ do |task_name, condition, regex|
+  if condition == 'contains' then
+    @output[task_name].should match(%r(#{regex}))
+  else
+    @output[task_name].should_not match(%r(#{regex}))
+  end
+end

data/features/step_definitions/folders.rb

@@ -0,0 +1,32 @@
+Given /^a safe project directory$/ do
+  # step back to ROOT
+  Dir.chdir ROOT_PATH
+  tmp_name = "project.#{Process.pid}"
+  @safe_dir = File.join(ROOT_PATH, 'tmp', tmp_name)
+  FileUtils.rm_rf @safe_dir
+  FileUtils.mkdir_p @safe_dir
+  Dir.chdir @safe_dir
+
+  generate_scaffold_structure
+end
+
+Given /^'(.*)' folder (exist|is deleted)$/ do |folder, condition|
+  case condition
+    when 'exist'
+      raise "Folder #{folder} do not exist" unless File.exist?(folder) && File.directory?(folder)
+    when 'is deleted'
+      FileUtils.rm_rf folder
+  end
+end
+
+Then /^'(.*)' folder is created$/ do |folder|
+  File.directory?(folder).should be_true
+end
+
+Then /^'(.*)' folder do not exist$/ do |folder|
+  File.directory?(folder).should_not be_true
+end
+
+Then /^no left over from '(.*)' remains in '(.*)'$/ do |name, folder|
+  Dir.glob("#{folder}/**/#{name}").should be_empty
+end

data/features/step_definitions/gem.rb

@@ -0,0 +1,29 @@
+Given /^a gem named '(.*)'$/ do |gem_name|
+  generate_gem_task gem_name
+end
+
+Then /^ruby gem for '(.*)' version '(.*)' do exist in '(.*)'$/ do |name, version, folder|
+  File.exist?(gem_file(folder, name, version)).should be_true
+end
+
+Then /^binary gem for '(.*)' version '(.*)' do exist in '(.*)'$/ do |name, version, folder|
+  File.exist?(gem_file_platform(folder, name, version)).should be_true
+end
+
+Then /^a gem for '(.*)' version '(.*)' platform '(.*)' do exist in '(.*)'$/ do |name, version, platform, folder|
+  File.exist?(gem_file_platform(folder, name, version, platform)).should be_true
+end
+
+Then /^gem for platform '(.*)' get generated$/ do |platform|
+  Then "a gem for 'gem_abc' version '0.1.0' platform '#{platform}' do exist in 'pkg'"
+end
+
+def gem_file(folder, name, version)
+  "#{folder}/#{name}-#{version}.gem"
+end
+
+def gem_file_platform(folder, name, version, platform = nil)
+  file = "#{folder}/#{name}-#{version}"
+  file << "-" << (platform || Gem::Platform.local.to_s)
+  file << ".gem"
+end

data/features/support/env.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'cucumber'
+require 'spec'
+require 'fileutils'
+require 'rbconfig'
+
+ROOT_PATH = File.expand_path(File.join(File.dirname(__FILE__), '../..'))