README.rdoc in rake-compiler-0.9.5 vs README.rdoc in rake-compiler-0.9.6
- old
+ new
@@ -1,9 +1,9 @@
= 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
+Its 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.
@@ -116,10 +116,14 @@
$ 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.
+To pass <tt>dir_config</tt> options to the compilation, add to the command line:
+
+ $ rake compile -- --with-foo-[dir|lib|bin|...]=/path/to/foo
+
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.
@@ -228,14 +232,15 @@
=== 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.
+Use rake-compiler-dock, a gem that makes use of a virtual machine provisioned with
+all the necessary build tools. You can add a task to your Rakefile, that
+cross-compiles and packages your gem into Windows fat binaries (with 1.8 to 2.2
+and x86/x64 support). See https://github.com/rake-compiler/rake-compiler-dock 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.
@@ -282,57 +287,76 @@
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
+ rbconfig-x86-mingw32-1.8.6: /path/to/ruby-1.8.6/rbconfig.rb
+ rbconfig-x86-mingw32-1.8.7: /path/to/ruby-1.8.7/rbconfig.rb
+ rbconfig-x86-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)
+ rake-compiler cross-ruby HOST=x86-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'
+ # enable cross compilation (requires cross compile toolchain)
+ ext.cross_compile = true
+ # set a single platform or an array of platforms to target
+ ext.cross_platform = ['x86-mingw32', 'x64-mingw32']
+
+ # cross-compile options will be passed to extconf.rb for each
+ # platform build, with platform-specific options in a hash.
+ ext.cross_config_options << '--with-common-option'
+ ext.cross_config_options << {
+ 'x86-mswin32-60 => '--with-some-option',
+ 'x64-mingw32' => '--enable-64bits',
+ }
+ ext.cross_config_options << '--with-final-option'
+
# perform alterations on the gemspec when cross compiling
ext.cross_compiling do |gem_spec|
+ # such as packaging a file that isn't specified in the gemspec
+ gem_spec.files << 'lib/generated_file.rb'
+ # or adding a new installation message
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.
+By default, cross compilation targets 'i386-mingw32' which is the default
+GCC platform for Ruby. MRI Ruby's current official distribution uses
+<tt>i386-mswin32-60</tt>. The RubyInstaller distribution uses
+<tt>x86-mingw32</tt> and <tt>x64-mingw32</tt> for 32-bit and 64-bit
+Windows targets, respectively. Note that <tt>i386</tt> and <tt>x86</tt>
+are synonymous here; <tt>x86</tt> is preferred going forward.
-To target gems for MRI Ruby's current official distribution, please force the
-platform to the one (i386-mswin32-60) previously shown.
+The format for <tt>cross_config_options</tt> is an array of strings and
+hashes. Hashes will be fetched for each value of <tt>cross_platform</tt>
+as the build iterates, or ignored if there is no value for that platform.
+You can mix-and-match strings and hashes to get desired option ordering.
==== 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:
+And now, building gems for your Windows users is just 6 more letters:
rake cross native gem
And you're done, yeah.
@@ -364,10 +388,10 @@
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:
+Now it's up to you to make your gem load the proper binary at runtime:
begin
RUBY_VERSION =~ /(\d+.\d+)/
require "#{$1}/my_extension"
rescue LoadError