luislavena-rake-compiler 0.1.1

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,191 @@
+= 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.
+
+
+== 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.additional_options << '--with-foo'  # supply addition configure options to config script-
+      ext.gem_spec = spec                     # optional indicate which gem specification
+                                              # will be used to based on.
+    end
+
+
+== 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
+GitHub:    http://github.com/luislavena/rake-compiler
+
+
+=== Some of the features already underworks
+
+* <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 /extension_one/
+
+  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/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 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 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,27 @@
+Given /^a extension named '(.*)'$/ do |extension_name|
+  generate_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 /^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/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