blackwinter-rake-compiler 0.9.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 38763b3b7fe07b27a0e9e4c9d87ea2056b8278f9
+  data.tar.gz: 50ef7e99b03b3bcabb8cc3b47efe7327d162e519
+SHA512:
+  metadata.gz: 204d2a3e19651d45d2a5c693444aae12c6b25a40f0241a9ff4617aeac508e60ef64d70022f578bd7048ddea77dc63507f042d655a875a9572fbfef1d8ec55f68
+  data.tar.gz: 8f64a3f44ae3b070ad4aeb90983b30d188429d81f4c6277fe54be6823bc8bb8b8d245d50a3dde585192da7b18edbc0064619b321478e523152cd3e5aba761944

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gem "rake"
+
+group :development do
+  gem "rspec",    "~> 2.8.0"
+  gem "cucumber", "~> 1.1.4"
+end

data/History.txt

@@ -0,0 +1,308 @@
+=== 0.9.2 / 2013-11-14
+
+* Bugfixes:
+  * Pre-load resolver to avoid Bundler blow up during cross-compilation
+    Pull #83 [larskanis]
+
+=== 0.9.1 / 2013-08-03
+
+* Bugfixes:
+  * Restore compatibility with RubyGems platforms for cross-compilation
+    (i386-mingw32 and x86-mingw32 are the same and supported)
+
+=== 0.9.0 / 2013-08-03
+
+* Enhancements:
+  * Add support for cross-builds and multiple platforms (x86/x64).
+    Pull #74 [larskanis]
+
+      $ rake-compiler cross-ruby VERSION=1.8.7-p371
+      $ rake-compiler cross-ruby VERSION=1.9.3-p392
+      $ rake-compiler cross-ruby VERSION=2.0.0-p0
+      $ rake-compiler cross-ruby VERSION=2.0.0-p0 HOST=x86_64-w64-mingw32
+      $ rake cross compile RUBY_CC_VERSION=1.8.7:1.9.3:2.0.0
+
+      # Rakefile
+      ext.cross_platform = %w[i386-mingw32 x64-mingw32]
+
+  * Support for cross-platform specific options. Pull #74 [larskanis]
+
+      # Rakefile
+      ext.cross_config_options << "--with-common-option"
+      ext.cross_config_options << {"x64-mingw32" => "--enable-64bits"}
+
+* Bugfixes:
+  * Correct fat-gems support caused by RubyGems issues. Pull #76 [knu]
+
+* Deprecations:
+  * Requires minimum Ruby 1.8.7 and RubyGems 1.8.25
+  * Usage of 'i386-mswin32' needs to be changed to 'i386-mswin32-60'
+
+=== 0.9.0.pre.1 / 2013-05-05
+
+See 0.9.0 changes.
+
+=== 0.8.3 / 2013-02-16
+
+* Bugfixes:
+  * Support FreeBSD 'mingw32-gcc' cross compiler. Closes #72 [knu]
+
+=== 0.8.2 / 2013-01-11
+
+* Bugfixes:
+  * Unset CC, LDFLAGS and CPPFLAGS prior cross-compiling. Closes #55
+
+=== 0.8.1 / 2012-04-15
+
+* Bugfixes:
+  * Raise error when either make or gmake could be found. Closes #53, #54
+
+=== 0.8.0 / 2012-01-08
+
+* Enhancements:
+  * Invocation from command line now support extra options similar to RubyGems.
+    Closes #4 from Pull #47 [jonforums]
+
+      $ rake compile -- --with-opt-dir=/opt/local
+
+* Bugfixes:
+  * Only emit cross-compilation warnings for C when `cross` is invoked.
+    Closes #16 from Pull #48 [mvz]
+  * Only emit warnings when invoking cross-compilation tasks for JRuby.
+    Pull #45 [jfirebaugh]
+  * Use x86 MinGW cross-compiler. Pull #49 [larskanis]
+
+=== 0.7.9 / 2011-06-08
+
+* Enhancements:
+  * Consistently use RubyGems features available since version 1.3.2 and avoid
+    deprecation warnings with Rake > 0.8.7.
+
+* Bugfixes:
+  * Use correct platform in fake.rb. Pull #39 [kou]
+  * Workaround Gem::Specification and Gem::PackageTask limitations. Closes #43
+
+=== 0.7.8 / 2011-04-26
+
+* Enhancements:
+  * Bump default cross-ruby version to 1.8.7-p334.
+  * ExtensionTask now support config_includes to load additional directories.
+    [jfinkhaeuser]
+
+    Rake::ExtensionTask.new("myext", GEM_SPEC) do |ext|
+      ext.config_includes << File.expand_path("my", "custom", "dir")
+    end
+
+* Bugfixes:
+  * Warn if compiled files exists in extension's source directory. Closes GH-35
+  * Workaround issue with WINE using proper build option. Closes GH-37
+  * Use FileUtils#install instead of cp. Closes GH-33 [Eric Wong]
+  * Update README instructions for OSX. Closes GH-29 [tmm1]
+
+=== 0.7.7 / 2011-04-04
+
+* Bugfixes:
+  * Use Winsock2 as default to match Ruby 1.9.2 library linking.
+
+=== 0.7.6 / 2011-02-04
+
+* Bugfixes:
+  * Prefer Psych over Syck for YAML parsing on Ruby 1.9.2. [tenderlove]
+
+=== 0.7.5 / 2010-11-25
+
+* Enhancements:
+  * Promoted stable version for cross-compilation to 1.8.6-p398. Closes GH-19
+
+* Bugfixes:
+  * Generate a fake.rb compatible with Ruby 1.9.2. Closes GH-25
+  * fake.rb will not try to mimic Ruby's own fake to the letter. Closes GH-28
+  * Expand symlinks for tmp_dir. Closes GH-24
+  * Silence make output during rake-compiler invocation.
+  * Usage of Gem.ruby instead of RbConfig ruby_install_name
+    This solve issues with ruby vs. ruby.exe and jruby.exe
+
+* Experimental:
+  * Allow setting of HOST during cross-compilation. This enable usage
+    of mingw-w64 compiler and not the first one found in the PATH.
+
+      rake-compiler cross-ruby VERSION=1.9.2-p0 HOST=i686-w64-mingw32
+      rake-compiler cross-ruby HOST=i386-mingw32 (OSX mingw32 port)
+      rake-compiler cross-ruby HOST=i586-pc-mingw32 (Debian/Ubuntu mingw32)
+
+=== 0.7.1 / 2010-08-07
+
+* Bugfixes:
+  * Update gem files to make "gem install -t" works. Closes GH-14
+  * Update mocks to work under 1.8.7. Closes GH-15 [luisparravicini]
+  * Do not allow cross-ruby be executed under Windows. Closes GH-22
+
+* Experimental:
+  * Allow JRuby to compile C extensions [timfel].
+    It is now possible compile C extensions using latest JRuby. Offered
+    in experimental mode since JRuby cext hasn't been officially released.
+
+=== 0.7.0 / 2009-12-08
+
+* Enhancements
+  * Allow generation of JRuby extensions. Thanks to Alex Coles (myabc) for the
+    contribution.
+    This will allow, with proper JDK tools, cross compilation of JRuby gems
+    from MRI.
+
+      Rake::JavaExtensionTask.new('my_java_extension', GEM_SPEC) do |ext|
+        # most of ExtensionTask options can be used
+        # plus, java_compiling:
+        ext.java_compiling do |gem_spec|
+          gem_spec.post_install_message = "This is a native JRuby gem!"
+        end
+      end
+
+    Please note that cross-compiling JRuby gems requires either JRUBY_HOME or
+    JRUBY_PARENT_CLASSPATH environment variables being properly set.
+
+  * Allow alteration of the Gem Specification when cross compiling. Closes GH-3
+    This is useful to indicate a custom requirement message, like DLLs
+    installation or similar.
+
+      Rake::ExtensionTask.new('my_extension', GEM_SPEC) do |ext|
+        ext.cross_compile = true
+        # ...
+        ext.cross_compiling do |gem_spec|
+          gem_spec.post_install_message = "You've installed a binary version of this gem"
+        end
+      end
+
+* Bugfixes
+  * Detect GNU make independently of distribution based naming.
+    Thanks to flori for patches.
+  * Usage of #dup to duplicate gemspec instead of YAML dumping.
+  * No longer support Ruby older than 1.8.6
+  * No longer support RubyGems older than 1.3.5
+  * Force definition of binary directory and executables. Closes GH-11
+  * Workaround path with spaces issues using relative paths. Closes GH-6
+  * Removed gemspec, GitHub gems no more
+
+* Known issues
+  * Usage of rake-compiler under projects with Jeweler requires some tweaks
+    Please read issue GH-73 for Jeweler:
+    http://github.com/technicalpickles/jeweler/issues#issue/73
+
+    For a workaround, look here:
+    http://gist.github.com/251663
+
+=== 0.6.0 / 2009-07-25
+
+* Enhancements
+  * Implemented 'fat-binaries' generation for cross compiling
+    (for now). Thanks to Aaron Patterson for the suggestion and
+    original idea.
+
+      rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.1
+
+    Will package extensions for 1.8 and 1.9 versions of Ruby.
+  * Can now cross compile extensions for 1.9 using 1.8.x as base.
+    Be warned: works from 1.8 to 1.9, but not if your default ruby is 1.9
+
+      rake cross compile RUBY_CC_VERSION=1.9.1
+
+  * Allow simultaneous versions of Ruby to compile extensions.
+    This change allow 1.8.x compiles co-exist with 1.9.x ones
+    and don't override each other.
+
+    Please perform <tt>rake clobber</tt> prior compiling again.
+  * Allow optional source file URL for cross-compile tasks.
+    (Thanks to deepj for the patches)
+
+      rake-compiler cross-ruby VERSION=1.9.1-p0 SOURCE=http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.1-p0.tar.bz2
+
+* Bugfixes
+  * Removed strict versioning for gems since it clash with fat binaries.
+    From now on, if your gem only targets a specific version of Ruby, please
+    indicate it in the Gem::Specification (<tt>required_ruby_version</tt>)
+
+=== 0.5.0 / 2009-04-25
+
+* Enhancements
+  * Allow generation of multiple gems for Windows (EXPERIMENTAL)
+    This allows build gems for both VC6 and MinGW builts of Ruby
+    (Thanks to Jonathan Stott for the suggestion)
+
+      Rake::ExtensionTask.new('my_extension', GEM_SPEC) do |ext|
+        ext.cross_compile = true
+        ext.cross_platform = ['i386-mswin32', 'i386-mingw32']
+      end
+
+=== 0.4.1 / 2009-04-09
+
+* Enhancements
+  * Target specific versions of Ruby when generating binaries.
+    This avoids installing a 1.8.x binary gem in 1.9.x and viceversa.
+    (Thanks to Aaron Patterson for the patches)
+
+* Bugfixes
+  * No longer raises error if rake-compiler configuration is missing.
+    Not all users of a project would have it installed.
+    (Thanks to Aaron Patterson for the patch)
+
+=== 0.4.0 / 2009-04-03
+
+* Enhancements
+  * Bended the convention for extension folder.
+    Defining <tt>ext_dir</tt> for custom extension location.
+
+      Rake::ExtensionTask.new('my_extension') do |ext|
+        ext.ext_dir = 'custom/location'         # look into custom/location
+      end                                       # instead of ext/my_extension
+
+  * Better detection of mingw target across Linux/OSX.
+    Exposed it as Rake::ExtensionCompiler
+  * Display list of available tasks when calling rake-compiler script
+  * Track Ruby full versioning (x.y.z).
+    This will help the compilation of extensions targetting 1.8.6/7 and 1.9.1
+
+* Bugfixes
+  * Better output of Rake development tasks (Thanks to Luis Parravicini).
+  * Proper usage of Gem::Platform for native gems (Thanks to Dirkjan Bussink).
+  * Don't use autoload for YAML (present problems with Ruby 1.9.1).
+
+=== 0.3.1 / 2009-01-09
+
+* Enhancements
+  * Download cross-ruby source code using HTTP instead of FTP.
+  * Disabled Tcl/Tk extension building on cross-ruby (helps with 1.9).
+
+* Bugfixes
+  * Workaround bug introduced by lack of Gem::Specification cloning. Fixes DM LH #757.
+  * Use proper binary extension on OSX (reported by Dirkjan Bussink).
+  * Ensure lib/binary task is defined prior clear of requisites.
+
+=== 0.3.0 / 2008-12-07
+
+* New features
+  * Let you specify the Ruby version used for cross compilation instead
+    of default one.
+
+      rake cross compile RUBY_CC_VERSION=1.8
+
+* Enhancements
+  * Properly update rake-compiler configuration when new version is installed.
+  * Automated release process to RubyForge, yay!
+
+* Bugfixes
+  * Corrected documentation to reflect the available options
+
+=== 0.2.1 / 2008-11-30
+
+* New features
+
+  * Allow cross compilation (cross compile) using mingw32 on Linux or OSX.
+  * Allow packaging of gems for Windows on Linux or OSX.
+
+* Enhancements
+
+  * Made generation of extensions safe and target folders per-platform
+
+* Bugfixes
+
+  * Ensure binaries for the specific platform are copied before packaging.

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2011 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,415 @@
+= What is rake-compiler?
+
+rake-compiler is first and foremost a productivity tool for Ruby developers.
+It's goal is to make the busy developer's life easier by simplifying the building
+and packaging of Ruby extensions by simplifying code and reducing duplication.
+
+It follows *convention over configuration* by advocating a standardized build and
+package structure for both C and Java based RubyGems.
+
+rake-compiler is the result of many hard-won experiences dealing with several
+diverse RubyGems that provided native extensions for different platforms and
+different user configurations in different ways. Details such as differences in
+code portability, differences in code clarity, and differences in project directory
+structure often made it very difficult for newcomers to those RubyGems.
+
+From these challenges, rake-compiler was born with the single-minded goal of
+making the busy RubyGem developer's life much less difficult.
+
+== Feature Overview
+
+Some of the benefits rake-compiler provides include:
+
+* No custom rake tasks required. Less code duplication and errors.
+
+* Painlessly build extensions on different platforms (Linux, OSX and Windows).
+
+* Painlessly build extensions for different Ruby implementations (JRuby,
+  Rubinius and MRI).
+
+* Allow multiple extensions to be compiled inside the same gem.
+
+* Painlessly build "fat" native gems for Windows users (from Linux or OSX).
+
+* Mimics RubyGems standard installation process, helping as a test environment.
+
+* Simplifies cross platform extension compilation (targeting Windows from Linux).
+
+== OK, I'm sold! Show me how to install it!
+
+Simple:
+
+  $ gem install rake-compiler
+
+== That's easy. How do I use it?
+
+Now that you have installed rake-compiler, it's time to give your project a
+standardized structure.
+
+=== Using a standardized project structure
+
+Let's say you want to compile an extension called 'hello_world'. Organizing
+your project's code tree in the following way will help rake-compiler do
+its job:
+
+    |-- ext
+    |   `-- hello_world
+    |       |-- extconf.rb
+    |       |-- HelloWorldService.java
+    |       `-- hello_world.c
+    |-- lib
+    `-- Rakefile
+
+TIP: Having a consistent project directory structure will help developers and
+newcomers find and understand your code, making it easier for them to
+contribute back to your project.
+
+=== Adding the code to enable rake-compiler
+
+Now the fun part. It's time to introduce the code to your projects Rakefile
+to tell it to use rake-compiler to build your extension:
+
+    # File: extconf.rb
+
+    # these lines must exist already
+    require 'mkmf'
+    create_makefile('hello_world')
+
+
+    # File: Rakefile
+
+    require 'rake/extensiontask'
+
+    Rake::ExtensionTask.new('hello_world')
+
+That's it? Yes, that's it! No other lines of code are needed for
+rake-compiler to work its magic.
+
+Though, you need to make sure the parameter to <tt>create_makefile</tt>
+and <tt>ExtensionTask.new</tt> are the same or rake-compiler will not mimic
+the RubyGems standard install process. You can override this standard
+behaviour if needed, see the instructions for "non-standard project structure"
+below for details.
+
+If you want to do the same for a JRuby extension written in Java, it's just
+as easy:
+
+    # File: Rakefile
+
+    require 'rake/javaextensiontask'
+
+    Rake::JavaExtensionTask.new('hello_world')
+
+=== The simple process
+
+Those *two* simple lines of code automatically added the Rake tasks needed to
+build your 'hello_world' extension. For example, checking the Rake tasks on
+MRI Ruby 1.8.x/1.9 returns something similar to:
+
+  $ rake -T
+  (in /home/user/my_extension)
+  rake compile                # Compile the extension(s)
+  rake compile:hello_world    # Compile just the hello_world extension
+
+Simply calling <tt>compile</tt> like
+
+  $ rake compile
+
+performs the entire compile and build process for you and places the resulting
+extension inside the <tt>lib</tt> directory of your project.
+
+NOTE: Please be aware that building C extensions requires the proper
+development environment for your Platform, including libraries, headers
+and build tools. Check your distro / vendor documentation on how to install
+these development resources.
+
+NOTE: Building Java extensions requires the <tt>javac</tt>, part of the Java
+Development Kit (JDK). This should be included by default on Mac OS X, and
+downloadable from http://java.sun.com for other operating systems.
+
+=== Generating native RubyGems
+
+A common usage scenario for rake-compiler is generating native gems that
+bundle your extensions. As mentioned above, if you have your development
+environment configured correctly, the following examples work even when
+building native gems on Windows systems.
+
+Creating native gems is really easy with rake-compiler's <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
+    Gem::PackageTask.new(spec) do |pkg|
+    end
+
+    # feed the ExtensionTask with your spec
+    Rake::ExtensionTask.new('hello_world', spec)
+
+As expected, you can still build your pure-ruby gem in the usual way
+(standard output) by running:
+
+  $ 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, rake-compiler tasks give you the extra functionality needed to build
+native gems by running:
+
+  # 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
+
+Did you notice that you get two gems for the price of one? How's that for a
+time saver?
+
+Similarly, it's just as easy to do the same thing for JRuby extensions:
+
+  # rake java 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-java.gem
+  mv my_gem-0.1.0-java.gem pkg/my_gem-0.1.0-java.gem
+
+
+=== Great, but can I use a non-standard project structure?
+
+Yes you can! While the conventional project structure is recommended, you may
+want, or need, to tweak those conventions. Rake-compiler allows you to customize
+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 the default 'extconf.rb'.
+      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 options to configure script.
+      ext.gem_spec = spec                     # optionally indicate which gem specification
+                                              # will be used.
+    end
+
+== Cross compilation - the future is now.
+
+Rake-compiler also provides a standardized way to generate, from either Linux
+or OSX, extensions and gem binaries for your Windows users!
+
+How can this be you say? Simple, rake-compiler's cross compilation features
+take advantage of GCC's host/target capabilities to build 'target' binaries on
+different 'host' OS's.
+
+=== How do I do this from Linux or OSX?
+
+==== The Easy Way
+
+Use rake-compiler-dev-box, a virtual machine provisioned with all the necessary
+build tools.  With one command, you can cross-compile and package your gem into
+native, Java, and Windows fat binaries (with 1.8, 1.9, and 2.0 support).  See
+https://github.com/tjschuck/rake-compiler-dev-box for more information.
+
+==== The Manual Way
+
+In addition to having the development tool chain installed (GCC), you also need to
+install your platform's <tt>mingw32</tt> cross compilation package.
+
+Installation depends upon your operating system/distribution. On Ubuntu and Debian
+host machines, a simple <tt>apt-get install mingw32</tt> will be enough.
+
+On Arch, <tt>mingw32</tt> is installed by running <tt>pacman -S mingw32-gcc</tt>
+
+On OSX, we no longer recommend the usage of MacPorts <tt>mingw32</tt> package because
+it stagnated in GCC version 3.4.5.
+
+Instead we recommend you download mingw-w64 automated build packages available at
+SourceForge:
+
+http://sourceforge.net/downloads/mingw-w64/
+
+Browse into <em>Toolchains targetting Win32</em> and then <em>Automated Builds</em>.
+
+Files will be ordered by recency, find the latest one with version 1.0 in it,
+like this one:
+
+  mingw-w32-1.0-bin_i686-darwin_20110422.tar.bz2
+
+Download and extract. After that, make sure the bin directory is added to the PATH, eg:
+
+  export PATH=~/mingw-w64/w32/bin:$PATH
+
+You can add this to your <tt>.profile</tt> to avoid the repitition.
+
+==== I've got my tool-chain installed, now what?
+
+First, you need to build Ruby for Windows on your Linux or OSX system.
+
+Relax, no need to freak out! Let rake-compiler do all the heavy lifting for you:
+
+  rake-compiler cross-ruby
+
+And you're done. It will automatically download, configure and compile the latest
+stable version of Ruby for Windows, and place it into your <tt>~/.rake-compiler</tt>
+directory.
+
+This will create <tt>~/.rake-compiler/config.yml</tt> file so that rake-compiler
+knows where to find the <tt>rbconfig.rb</tt> file that matches the Ruby version
+on the Windows host system you're cross-compiling for. An example:
+
+  # File: ~/.rake-compiler/config.yml
+
+  rbconfig-i386-mingw32-1.8.6: /path/to/ruby-1.8.6/rbconfig.rb
+  rbconfig-i386-mingw32-1.8.7: /path/to/ruby-1.8.7/rbconfig.rb
+  rbconfig-i386-mingw32-1.9.2: /path/to/ruby-1.9.2/rbconfig.rb
+
+If, instead, you want to build a different Ruby version than the default one, please
+supply a <tt>VERSION</tt>:
+
+  rake-compiler cross-ruby VERSION=1.8.6-p114
+
+If you, like me, have multiple versions of MinGW packages installed, you can
+specify the HOST that will be used to cross compile Ruby:
+
+  rake-compiler cross-ruby HOST=i386-mingw32 # (OSX mingw32 port)
+
+The host will vary depending on provider (mingw32 versus mingw-w64 projects).
+Please consult the documentation and website of the MinGW package provider before
+reporting any issues.
+
+==== OK, let's cross compile some gems!
+
+Now, you only need specify a few additional options in your extension definition:
+
+    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-60'     # forces the Windows platform instead of the default one
+                                              # configure options only for cross compile
+      ext.cross_config_options << '--with-something'
+
+      # perform alterations on the gemspec when cross compiling
+      ext.cross_compiling do |gem_spec|
+        gem_spec.post_install_message = "You installed the binary version of this gem!"
+      end
+    end
+
+By default, cross compilation targets 'i386-mingw32' which is the default GCC
+platform for Ruby.
+
+To target gems for MRI Ruby's current official distribution, please force the
+platform to the one (i386-mswin32-60) previously shown.
+
+==== Warning, magician about to do some tricks, don't blink!
+
+Cross compiling is still very simple:
+
+  rake cross compile
+
+And now, building gems for your Windows users is just 5 more letters:
+
+  rake cross native gem
+
+And you're done, yeah.
+
+==== But wait, there's more
+
+You can specify which version of Ruby to build the extension against:
+
+  rake cross compile RUBY_CC_VERSION=1.8.6
+
+For example, if you installed <tt>1.9.2</tt>, you can do:
+
+  rake cross compile RUBY_CC_VERSION=1.9.2
+
+Even better, you can target multiple versions (ie. 1.8.6 and 1.9.2) in
+the same gem via:
+
+  rake cross compile RUBY_CC_VERSION=1.8.6:1.9.2
+
+And better yet, you can bundle both binary extensions into one so-called "fat"
+gem via:
+
+  rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.2
+
+That will place binaries for both the 1.8 and 1.9 versions of your Ruby
+extensions inside your project's <tt>lib_dir</tt> directory:
+
+  lib/1.8/my_extension.so
+  lib/1.9/my_extension.so
+
+NOTE: building "fat" gems is currently only supported by rake-compiler when
+cross compiling from a Linux or OSX host. Patches are welcome if building
+"fat" gems from Windows hosts is desired, or natively for your platform :-)
+
+Now is up to you to make your gem load the proper binary at runtime:
+
+  begin
+    RUBY_VERSION =~ /(\d+.\d+)/
+    require "#{$1}/my_extension"
+  rescue LoadError
+    require "my_extension"
+  end
+
+The above technique will lookup first for 1.8 or 1.9 version of the extension
+and when not found, will look for the plain extension.
+
+This approach catch the cases of provided fat binaries or gems compiled by the
+end user installing the gem. It has also been implemented successfully in
+several projects.
+
+== What are you talking about? (Give me examples)
+
+I know all the above sounds like a complete foreign language (it does even for me!).
+So, what if I show you some examples?
+
+Check our wiki with links to the proper rake files used by many developers and
+projects and how they use rake-compiler.
+
+http://github.com/luislavena/rake-compiler/wiki/projects-using-rake-compiler
+
+== Future
+
+rake-compiler is a work in progress and we appreciate any and all feedback
+during the development of it! (and contributions too!)
+
+You can find more information about rake-compiler:
+
+* GitHub:    https://github.com/luislavena/rake-compiler
+* Issues:    https://github.com/luislavena/rake-compiler/issues
+* Blog:      http://blog.mmediasys.com
+* Docs:      http://rubydoc.info/gems/rake-compiler
+* Wiki:      https://github.com/luislavena/rake-compiler/wiki
+
+== 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.