提供一种标准且简化的方法,使用 Rake 作为粘合剂来构建和打包 Ruby C 和 Java 扩展。
rake-compiler is first and foremost a productivity tool for Ruby developers. 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.
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.
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).
Simple:
$ gem install rake-compilerNow that you have installed rake-compiler, it's time to give your project a standardized 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
`-- RakefileTIP: 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.
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 create_makefile
and ExtensionTask.new 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')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 extensionSimply calling compile like
$ rake compileperforms the entire compile and build process for you and places the resulting
extension inside the lib directory of your project.
To pass dir_config options to the compilation, add to the command line:
$ rake compile -- --with-foo-[dir|lib|bin|...]=/path/to/fooNOTE: 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 javac, 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.
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
Rake::ExtensionTask:
# 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.gemPlus, 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.gemDid 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.gemYes 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 Rake::ExtensionTask:
…By default, cross compilation targets 'i386-mingw32' which is the default
GCC platform for Ruby. MRI Ruby's current official distribution uses
i386-mswin32-60. The RubyInstaller distribution uses
x86-mingw32 and x64-mingw32 for 32-bit and 64-bit
Windows targets, respectively. Note that i386 and x86
are synonymous here; x86 is preferred going forward.
The format for cross_config_options is an array of strings and
hashes. Hashes will be fetched for each value of cross_platform
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.
Cross compiling is still very simple:
rake cross compileAnd now, building gems for your Windows users is just 6 more letters:
rake cross native gemAnd you're done, yeah.
You can specify which version of Ruby to build the extension against:
rake cross compile RUBY_CC_VERSION=1.8.6For example, if you installed 1.9.2, you can do:
rake cross compile RUBY_CC_VERSION=1.9.2Even 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.2And 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.2That will place binaries for both the 1.8 and 1.9 versions of your Ruby
extensions inside your project's lib_dir directory:
lib/1.8/my_extension.so
lib/1.9/my_extension.soNOTE: 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 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
require "my_extension"
endThe 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.
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/rake-compiler/rake-compiler/wiki/projects-using-rake-compiler
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:
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.
暂无开放 Issues,或尚未同步最近议题。