rake-compiler-sgonyea 0.8.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (43) hide show
  1. data/History.txt +254 -0
  2. data/Isolate +6 -0
  3. data/LICENSE.txt +20 -0
  4. data/README.rdoc +393 -0
  5. data/Rakefile +21 -0
  6. data/bin/rake-compiler +24 -0
  7. data/cucumber.yml +4 -0
  8. data/features/compile.feature +79 -0
  9. data/features/cross-compile.feature +22 -0
  10. data/features/cross-package-multi.feature +15 -0
  11. data/features/cross-package.feature +14 -0
  12. data/features/java-compile.feature +22 -0
  13. data/features/java-no-native-compile.feature +33 -0
  14. data/features/java-package.feature +24 -0
  15. data/features/package.feature +40 -0
  16. data/features/step_definitions/compilation.rb +70 -0
  17. data/features/step_definitions/cross_compilation.rb +25 -0
  18. data/features/step_definitions/execution.rb +52 -0
  19. data/features/step_definitions/folders.rb +32 -0
  20. data/features/step_definitions/gem.rb +46 -0
  21. data/features/step_definitions/java_compilation.rb +7 -0
  22. data/features/support/env.rb +6 -0
  23. data/features/support/file_template_helpers.rb +137 -0
  24. data/features/support/generator_helpers.rb +123 -0
  25. data/features/support/platform_extension_helpers.rb +27 -0
  26. data/lib/rake/baseextensiontask.rb +90 -0
  27. data/lib/rake/extensioncompiler.rb +53 -0
  28. data/lib/rake/extensiontask.rb +431 -0
  29. data/lib/rake/javaextensiontask.rb +226 -0
  30. data/spec/lib/rake/extensiontask_spec.rb +481 -0
  31. data/spec/lib/rake/javaextensiontask_spec.rb +182 -0
  32. data/spec/spec.opts +3 -0
  33. data/spec/spec_helper.rb +15 -0
  34. data/spec/support/capture_output_helper.rb +22 -0
  35. data/tasks/bin/cross-ruby.rake +196 -0
  36. data/tasks/bootstrap.rake +11 -0
  37. data/tasks/common.rake +10 -0
  38. data/tasks/cucumber.rake +23 -0
  39. data/tasks/gem.rake +53 -0
  40. data/tasks/news.rake +39 -0
  41. data/tasks/release.rake +26 -0
  42. data/tasks/rspec.rake +9 -0
  43. metadata +145 -0
@@ -0,0 +1,254 @@
1
+ === 0.8.1 / 2012-04-15
2
+
3
+ * Bugfixes:
4
+ * Raise error when either make or gmake could be found. Closes #53, #54
5
+
6
+ === 0.8.0 / 2012-01-08
7
+
8
+ * Enhancements:
9
+ * Invocation from command line now support extra options similar to RubyGems.
10
+ Closes #4 from Pull #47 [jonforums]
11
+
12
+ $ rake compile -- --with-opt-dir=/opt/local
13
+
14
+ * Bugfixes:
15
+ * Only emit cross-compilation warnings for C when `cross` is invoked.
16
+ Closes #16 from Pull #48 [mvz]
17
+ * Only emit warnings when invoking cross-compilation tasks for JRuby.
18
+ Pull #45 [jfirebaugh]
19
+ * Use x86 MinGW cross-compiler. Pull #49 [larskanis]
20
+
21
+ === 0.7.9 / 2011-06-08
22
+
23
+ * Enhancements:
24
+ * Consistently use RubyGems features available since version 1.3.2 and avoid
25
+ deprecation warnings with Rake > 0.8.7.
26
+
27
+ * Bugfixes:
28
+ * Use correct platform in fake.rb. Pull #39 [kou]
29
+ * Workaround Gem::Specification and Gem::PackageTask limitations. Closes #43
30
+
31
+ === 0.7.8 / 2011-04-26
32
+
33
+ * Enhancements:
34
+ * Bump default cross-ruby version to 1.8.7-p334.
35
+ * ExtensionTask now support config_includes to load additional directories.
36
+ [jfinkhaeuser]
37
+
38
+ Rake::ExtensionTask.new("myext", GEM_SPEC) do |ext|
39
+ ext.config_includes << File.expand_path("my", "custom", "dir")
40
+ end
41
+
42
+ * Bugfixes:
43
+ * Warn if compiled files exists in extension's source directory. Closes GH-35
44
+ * Workaround issue with WINE using proper build option. Closes GH-37
45
+ * Use FileUtils#install instead of cp. Closes GH-33 [Eric Wong]
46
+ * Update README instructions for OSX. Closes GH-29 [tmm1]
47
+
48
+ === 0.7.7 / 2011-04-04
49
+
50
+ * Bugfixes:
51
+ * Use Winsock2 as default to match Ruby 1.9.2 library linking.
52
+
53
+ === 0.7.6 / 2011-02-04
54
+
55
+ * Bugfixes:
56
+ * Prefer Psych over Syck for YAML parsing on Ruby 1.9.2. [tenderlove]
57
+
58
+ === 0.7.5 / 2010-11-25
59
+
60
+ * Enhancements:
61
+ * Promoted stable version for cross-compilation to 1.8.6-p398. Closes GH-19
62
+
63
+ * Bugfixes:
64
+ * Generate a fake.rb compatible with Ruby 1.9.2. Closes GH-25
65
+ * fake.rb will not try to mimic Ruby's own fake to the letter. Closes GH-28
66
+ * Expand symlinks for tmp_dir. Closes GH-24
67
+ * Silence make output during rake-compiler invocation.
68
+ * Usage of Gem.ruby instead of RbConfig ruby_install_name
69
+ This solve issues with ruby vs. ruby.exe and jruby.exe
70
+
71
+ * Experimental:
72
+ * Allow setting of HOST during cross-compilation. This enable usage
73
+ of mingw-w64 compiler and not the first one found in the PATH.
74
+
75
+ rake-compiler cross-ruby VERSION=1.9.2-p0 HOST=i686-w64-mingw32
76
+ rake-compiler cross-ruby HOST=i386-mingw32 (OSX mingw32 port)
77
+ rake-compiler cross-ruby HOST=i586-pc-mingw32 (Debian/Ubuntu mingw32)
78
+
79
+ === 0.7.1 / 2010-08-07
80
+
81
+ * Bugfixes:
82
+ * Update gem files to make "gem install -t" works. Closes GH-14
83
+ * Update mocks to work under 1.8.7. Closes GH-15 [luisparravicini]
84
+ * Do not allow cross-ruby be executed under Windows. Closes GH-22
85
+
86
+ * Experimental:
87
+ * Allow JRuby to compile C extensions [timfel].
88
+ It is now possible compile C extensions using latest JRuby. Offered
89
+ in experimental mode since JRuby cext hasn't been officially released.
90
+
91
+ === 0.7.0 / 2009-12-08
92
+
93
+ * Enhancements
94
+ * Allow generation of JRuby extensions. Thanks to Alex Coles (myabc) for the
95
+ contribution.
96
+ This will allow, with proper JDK tools, cross compilation of JRuby gems
97
+ from MRI.
98
+
99
+ Rake::JavaExtensionTask.new('my_java_extension', GEM_SPEC) do |ext|
100
+ # most of ExtensionTask options can be used
101
+ # plus, java_compiling:
102
+ ext.java_compiling do |gem_spec|
103
+ gem_spec.post_install_message = "This is a native JRuby gem!"
104
+ end
105
+ end
106
+
107
+ Please note that cross-compiling JRuby gems requires either JRUBY_HOME or
108
+ JRUBY_PARENT_CLASSPATH environment variables being properly set.
109
+
110
+ * Allow alteration of the Gem Specification when cross compiling. Closes GH-3
111
+ This is useful to indicate a custom requirement message, like DLLs
112
+ installation or similar.
113
+
114
+ Rake::ExtensionTask.new('my_extension', GEM_SPEC) do |ext|
115
+ ext.cross_compile = true
116
+ # ...
117
+ ext.cross_compiling do |gem_spec|
118
+ gem_spec.post_install_message = "You've installed a binary version of this gem"
119
+ end
120
+ end
121
+
122
+ * Bugfixes
123
+ * Detect GNU make independently of distribution based naming.
124
+ Thanks to flori for patches.
125
+ * Usage of #dup to duplicate gemspec instead of YAML dumping.
126
+ * No longer support Ruby older than 1.8.6
127
+ * No longer support RubyGems older than 1.3.5
128
+ * Force definition of binary directory and executables. Closes GH-11
129
+ * Workaround path with spaces issues using relative paths. Closes GH-6
130
+ * Removed gemspec, GitHub gems no more
131
+
132
+ * Known issues
133
+ * Usage of rake-compiler under projects with Jeweler requires some tweaks
134
+ Please read issue GH-73 for Jeweler:
135
+ http://github.com/technicalpickles/jeweler/issues#issue/73
136
+
137
+ For a workaround, look here:
138
+ http://gist.github.com/251663
139
+
140
+ === 0.6.0 / 2009-07-25
141
+
142
+ * Enhancements
143
+ * Implemented 'fat-binaries' generation for cross compiling
144
+ (for now). Thanks to Aaron Patterson for the suggestion and
145
+ original idea.
146
+
147
+ rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.1
148
+
149
+ Will package extensions for 1.8 and 1.9 versions of Ruby.
150
+ * Can now cross compile extensions for 1.9 using 1.8.x as base.
151
+ Be warned: works from 1.8 to 1.9, but not if your default ruby is 1.9
152
+
153
+ rake cross compile RUBY_CC_VERSION=1.9.1
154
+
155
+ * Allow simultaneous versions of Ruby to compile extensions.
156
+ This change allow 1.8.x compiles co-exist with 1.9.x ones
157
+ and don't override each other.
158
+
159
+ Please perform <tt>rake clobber</tt> prior compiling again.
160
+ * Allow optional source file URL for cross-compile tasks.
161
+ (Thanks to deepj for the patches)
162
+
163
+ 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
164
+
165
+ * Bugfixes
166
+ * Removed strict versioning for gems since it clash with fat binaries.
167
+ From now on, if your gem only targets a specific version of Ruby, please
168
+ indicate it in the Gem::Specification (<tt>required_ruby_version</tt>)
169
+
170
+ === 0.5.0 / 2009-04-25
171
+
172
+ * Enhancements
173
+ * Allow generation of multiple gems for Windows (EXPERIMENTAL)
174
+ This allows build gems for both VC6 and MinGW builts of Ruby
175
+ (Thanks to Jonathan Stott for the suggestion)
176
+
177
+ Rake::ExtensionTask.new('my_extension', GEM_SPEC) do |ext|
178
+ ext.cross_compile = true
179
+ ext.cross_platform = ['i386-mswin32', 'i386-mingw32']
180
+ end
181
+
182
+ === 0.4.1 / 2009-04-09
183
+
184
+ * Enhancements
185
+ * Target specific versions of Ruby when generating binaries.
186
+ This avoids installing a 1.8.x binary gem in 1.9.x and viceversa.
187
+ (Thanks to Aaron Patterson for the patches)
188
+
189
+ * Bugfixes
190
+ * No longer raises error if rake-compiler configuration is missing.
191
+ Not all users of a project would have it installed.
192
+ (Thanks to Aaron Patterson for the patch)
193
+
194
+ === 0.4.0 / 2009-04-03
195
+
196
+ * Enhancements
197
+ * Bended the convention for extension folder.
198
+ Defining <tt>ext_dir</tt> for custom extension location.
199
+
200
+ Rake::ExtensionTask.new('my_extension') do |ext|
201
+ ext.ext_dir = 'custom/location' # look into custom/location
202
+ end # instead of ext/my_extension
203
+
204
+ * Better detection of mingw target across Linux/OSX.
205
+ Exposed it as Rake::ExtensionCompiler
206
+ * Display list of available tasks when calling rake-compiler script
207
+ * Track Ruby full versioning (x.y.z).
208
+ This will help the compilation of extensions targetting 1.8.6/7 and 1.9.1
209
+
210
+ * Bugfixes
211
+ * Better output of Rake development tasks (Thanks to Luis Parravicini).
212
+ * Proper usage of Gem::Platform for native gems (Thanks to Dirkjan Bussink).
213
+ * Don't use autoload for YAML (present problems with Ruby 1.9.1).
214
+
215
+ === 0.3.1 / 2009-01-09
216
+
217
+ * Enhancements
218
+ * Download cross-ruby source code using HTTP instead of FTP.
219
+ * Disabled Tcl/Tk extension building on cross-ruby (helps with 1.9).
220
+
221
+ * Bugfixes
222
+ * Workaround bug introduced by lack of Gem::Specification cloning. Fixes DM LH #757.
223
+ * Use proper binary extension on OSX (reported by Dirkjan Bussink).
224
+ * Ensure lib/binary task is defined prior clear of requisites.
225
+
226
+ === 0.3.0 / 2008-12-07
227
+
228
+ * New features
229
+ * Let you specify the Ruby version used for cross compilation instead
230
+ of default one.
231
+
232
+ rake cross compile RUBY_CC_VERSION=1.8
233
+
234
+ * Enhancements
235
+ * Properly update rake-compiler configuration when new version is installed.
236
+ * Automated release process to RubyForge, yay!
237
+
238
+ * Bugfixes
239
+ * Corrected documentation to reflect the available options
240
+
241
+ === 0.2.1 / 2008-11-30
242
+
243
+ * New features
244
+
245
+ * Allow cross compilation (cross compile) using mingw32 on Linux or OSX.
246
+ * Allow packaging of gems for Windows on Linux or OSX.
247
+
248
+ * Enhancements
249
+
250
+ * Made generation of extensions safe and target folders per-platform
251
+
252
+ * Bugfixes
253
+
254
+ * Ensure binaries for the specific platform are copied before packaging.
data/Isolate ADDED
@@ -0,0 +1,6 @@
1
+ gem "rake"
2
+
3
+ env :development do
4
+ gem "rspec", "~> 2.8.0"
5
+ gem "cucumber", "~> 1.1.4"
6
+ end
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2008-2011 Luis Lavena.
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,393 @@
1
+ = What is rake-compiler?
2
+
3
+ rake-compiler is first and foremost a productivity tool for Ruby developers.
4
+ It's goal is to make the busy developer's life easier by simplifying the building
5
+ and packaging of Ruby extensions by simplifying code and reducing duplication.
6
+
7
+ It follows *convention over configuration* by advocating a standardized build and
8
+ package structure for both C and Java based RubyGems.
9
+
10
+ rake-compiler is the result of many hard-won experiences dealing with several
11
+ diverse RubyGems that provided native extensions for different platforms and
12
+ different user configurations in different ways. Details such as differences in
13
+ code portability, differences in code clarity, and differences in project directory
14
+ structure often made it very difficult for newcomers to those RubyGems.
15
+
16
+ From these challenges, rake-compiler was born with the single-minded goal of
17
+ making the busy RubyGem developer's life much less difficult.
18
+
19
+ == Feature Overview
20
+
21
+ Some of the benefits rake-compiler provides include:
22
+
23
+ * No custom rake tasks required. Less code duplication and errors.
24
+
25
+ * Painlessly build extensions on different platforms (Linux, OSX and Windows).
26
+
27
+ * Painlessly build extensions for different Ruby implementations (JRuby,
28
+ Rubinius and MRI).
29
+
30
+ * Allow multiple extensions to be compiled inside the same gem.
31
+
32
+ * Painlessly build "fat" native gems for Windows users (from Linux or OSX).
33
+
34
+ * Mimics RubyGems standard installation process, helping as a test environment.
35
+
36
+ * Simplifies cross platform extension compilation (targeting Windows from Linux).
37
+
38
+ == OK, I'm sold! Show me how to install it!
39
+
40
+ Simple:
41
+
42
+ $ gem install rake-compiler
43
+
44
+ == That's easy. How do I use it?
45
+
46
+ Now that you have installed rake-compiler, it's time to give your project a
47
+ standardized structure.
48
+
49
+ === Using a standardized project structure
50
+
51
+ Let's say you want to compile an extension called 'hello_world'. Organizing
52
+ your project's code tree in the following way will help rake-compiler do
53
+ its job:
54
+
55
+ |-- ext
56
+ | `-- hello_world
57
+ | |-- extconf.rb
58
+ | |-- HelloWorldService.java
59
+ | `-- hello_world.c
60
+ |-- lib
61
+ `-- Rakefile
62
+
63
+ TIP: Having a consistent project directory structure will help developers and
64
+ newcomers find and understand your code, making it easier for them to
65
+ contribute back to your project.
66
+
67
+ === Adding the code to enable rake-compiler
68
+
69
+ Now the fun part. It's time to introduce the code to your projects Rakefile
70
+ to tell it to use rake-compiler to build your extension:
71
+
72
+ # File: Rakefile
73
+
74
+ require 'rake/extensiontask'
75
+
76
+ Rake::ExtensionTask.new('hello_world')
77
+
78
+ That's it? Yes, that's it! No other lines of code are needed for
79
+ rake-compiler to work its magic.
80
+
81
+ If you want to do the same for a JRuby extension written in Java, it's just
82
+ as easy:
83
+
84
+ # File: Rakefile
85
+
86
+ require 'rake/javaextensiontask'
87
+
88
+ Rake::JavaExtensionTask.new('hello_world')
89
+
90
+ === The simple process
91
+
92
+ Those *two* simple lines of code automatically added the Rake tasks needed to
93
+ build your 'hello_world' extension. For example, checking the Rake tasks on
94
+ MRI Ruby 1.8.x/1.9 returns something similar to:
95
+
96
+ $ rake -T
97
+ (in /home/user/my_extension)
98
+ rake compile # Compile the extension(s)
99
+ rake compile:hello_world # Compile just the hello_world extension
100
+
101
+ Simply calling <tt>compile</tt> like
102
+
103
+ $ rake compile
104
+
105
+ performs the entire compile and build process for you and places the resulting
106
+ extension inside the <tt>lib</tt> directory of your project.
107
+
108
+ NOTE: Please be aware that building C extensions requires the proper
109
+ development environment for your Platform, including libraries, headers
110
+ and build tools. Check your distro / vendor documentation on how to install
111
+ these development resources.
112
+
113
+ NOTE: Building Java extensions requires the <tt>javac</tt>, part of the Java
114
+ Development Kit (JDK). This should be included by default on Mac OS X, and
115
+ downloadable from http://java.sun.com for other operating systems.
116
+
117
+ === Generating native RubyGems
118
+
119
+ A common usage scenario for rake-compiler is generating native gems that
120
+ bundle your extensions. As mentioned above, if you have your development
121
+ environment configured correctly, the following examples work even when
122
+ building native gems on Windows systems.
123
+
124
+ Creating native gems is really easy with rake-compiler's <tt>Rake::ExtensionTask</tt>:
125
+
126
+ # somewhere in your Rakefile, define your gem spec
127
+ spec = Gem::Specification.new do |s|
128
+ s.name = "my_gem"
129
+ s.platform = Gem::Platform::RUBY
130
+ s.extensions = FileList["ext/**/extconf.rb"]
131
+ end
132
+
133
+ # add your default gem packing task
134
+ Gem::PackageTask.new(spec) do |pkg|
135
+ end
136
+
137
+ # feed the ExtensionTask with your spec
138
+ Rake::ExtensionTask.new('hello_world', spec)
139
+
140
+ As expected, you can still build your pure-ruby gem in the usual way
141
+ (standard output) by running:
142
+
143
+ $ rake gem
144
+ (in /projects/oss/my_gem.git)
145
+ mkdir -p pkg
146
+ Successfully built RubyGem
147
+ Name: my_gem
148
+ Version: 0.1.0
149
+ File: my_gem-0.1.0.gem
150
+ mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
151
+
152
+ Plus, rake-compiler tasks give you the extra functionality needed to build
153
+ native gems by running:
154
+
155
+ # rake native gem
156
+ (... compilation output ...)
157
+ mkdir -p pkg
158
+ Successfully built RubyGem
159
+ Name: my_gem
160
+ Version: 0.1.0
161
+ File: my_gem-0.1.0.gem
162
+ mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
163
+ Successfully built RubyGem
164
+ Name: my_gem
165
+ Version: 0.1.0
166
+ File: my_gem-0.1.0-x86-mingw32.gem
167
+ mv my_gem-0.1.0-x86-mingw32.gem pkg/my_gem-0.1.0-x86-mingw32.gem
168
+
169
+ Did you notice that you get two gems for the price of one? How's that for a
170
+ time saver?
171
+
172
+ Similarly, it's just as easy to do the same thing for JRuby extensions:
173
+
174
+ # rake java gem
175
+ (... compilation output ...)
176
+ mkdir -p pkg
177
+ Successfully built RubyGem
178
+ Name: my_gem
179
+ Version: 0.1.0
180
+ File: my_gem-0.1.0.gem
181
+ mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
182
+ Successfully built RubyGem
183
+ Name: my_gem
184
+ Version: 0.1.0
185
+ File: my_gem-0.1.0-java.gem
186
+ mv my_gem-0.1.0-java.gem pkg/my_gem-0.1.0-java.gem
187
+
188
+
189
+ === Great, but can I use a non-standard project structure?
190
+
191
+ Yes you can! While the conventional project structure is recommended, you may
192
+ want, or need, to tweak those conventions. Rake-compiler allows you to customize
193
+ several settings for <tt>Rake::ExtensionTask</tt>:
194
+
195
+ Rake::ExtensionTask.new do |ext|
196
+ ext.name = 'hello_world' # indicate the name of the extension.
197
+ ext.ext_dir = 'ext/weird_world' # search for 'hello_world' inside it.
198
+ ext.lib_dir = 'lib/my_lib' # put binaries into this folder.
199
+ ext.config_script = 'custom_extconf.rb' # use instead of the default 'extconf.rb'.
200
+ ext.tmp_dir = 'tmp' # temporary folder used during compilation.
201
+ ext.source_pattern = "*.{c,cpp}" # monitor file changes to allow simple rebuild.
202
+ ext.config_options << '--with-foo' # supply additional options to configure script.
203
+ ext.gem_spec = spec # optionally indicate which gem specification
204
+ # will be used.
205
+ end
206
+
207
+ == Cross compilation - the future is now.
208
+
209
+ Rake-compiler also provides a standardized way to generate, from either Linux
210
+ or OSX, extensions and gem binaries for your Windows users!
211
+
212
+ How can this be you say? Simple, rake-compiler's cross compilation features
213
+ take advantage of GCC's host/target capabilities to build 'target' binaries on
214
+ different 'host' OS's.
215
+
216
+ === How I do this from Linux or OSX?
217
+
218
+ In addition to having the development tool chain installed (GCC), you also need to
219
+ install your platform's <tt>mingw32</tt> cross compilation package.
220
+
221
+ Installation depends upon your operating system/distribution. On Ubuntu and Debian
222
+ host machines, a simple <tt>apt-get install mingw32</tt> will be enough.
223
+
224
+ On Arch, <tt>mingw32</tt> is installed by running <tt>pacman -S mingw32-gcc</tt>
225
+
226
+ On OSX, we no longer recommend the usage of MacPorts <tt>mingw32</tt> package because
227
+ it stagnated in GCC version 3.4.5.
228
+
229
+ Instead we recommend you download mingw-w64 automated build packages available at
230
+ SourceForge:
231
+
232
+ http://sourceforge.net/downloads/mingw-w64/
233
+
234
+ Browse into <em>Toolchains targetting Win32</em> and then <em>Automated Builds</em>.
235
+
236
+ Files will be ordered by recency, find the latest one with version 1.0 in it,
237
+ like this one:
238
+
239
+ mingw-w32-1.0-bin_i686-darwin_20110422.tar.bz2
240
+
241
+ Download and extract. After that, make sure the bin directory is added to the PATH, eg:
242
+
243
+ export PATH=~/mingw-w64/w32/bin:$PATH
244
+
245
+ You can add this to your <tt>.profile</tt> to avoid the repitition.
246
+
247
+ === I've got my tool-chain installed, now what?
248
+
249
+ First, you need to build Ruby for Windows on your Linux or OSX system.
250
+
251
+ Relax, no need to freak out! Let rake-compiler do all the heavy lifting for you:
252
+
253
+ rake-compiler cross-ruby
254
+
255
+ And you're done. It will automatically download, configure and compile the latest
256
+ stable version of Ruby for Windows, and place it into your <tt>~/.rake-compiler</tt>
257
+ directory.
258
+
259
+ This will create <tt>~/.rake-compiler/config.yml</tt> file so that rake-compiler
260
+ knows where to find the <tt>rbconfig.rb</tt> file that matches the Ruby version
261
+ on the Windows host system you're cross-compiling for. An example:
262
+
263
+ # File: ~/.rake-compiler/config.yml
264
+
265
+ rbconfig-1.8.6: /path/to/ruby-1.8.6/rbconfig.rb
266
+ rbconfig-1.8.7: /path/to/ruby-1.8.7/rbconfig.rb
267
+ rbconfig-1.9.2: /path/to/ruby-1.9.2/rbconfig.rb
268
+
269
+ If, instead, you want to build a different Ruby version than the default one, please
270
+ supply a <tt>VERSION</tt>:
271
+
272
+ rake-compiler cross-ruby VERSION=1.8.6-p114
273
+
274
+ If you, like me, have multiple versions of MinGW packages installed, you can
275
+ specify the HOST that will be used to cross compile Ruby:
276
+
277
+ rake-compiler cross-ruby HOST=i386-mingw32 # (OSX mingw32 port)
278
+
279
+ The host will vary depending on provider (mingw32 versus mingw-w64 projects).
280
+ Please consult the documentation and website of the MinGW package provider before
281
+ reporting any issues.
282
+
283
+ === OK, let's cross compile some gems!
284
+
285
+ Now, you only need specify a few additional options in your extension definition:
286
+
287
+ Rake::ExtensionTask.new('my_extension', gem_spec) do |ext|
288
+ ext.cross_compile = true # enable cross compilation (requires cross compile toolchain)
289
+ ext.cross_platform = 'i386-mswin32' # forces the Windows platform instead of the default one
290
+ # configure options only for cross compile
291
+ ext.cross_config_options << '--with-something'
292
+
293
+ # perform alterations on the gemspec when cross compiling
294
+ ext.cross_compiling do |gem_spec|
295
+ gem_spec.post_install_message = "You installed the binary version of this gem!"
296
+ end
297
+ end
298
+
299
+ By default, cross compilation targets 'i386-mingw32' which is the default GCC
300
+ platform for Ruby.
301
+
302
+ To target gems for MRI Ruby's current official distribution, please force the
303
+ platform to the one (i386-mswin32) previously shown.
304
+
305
+ === Warning, magician about to do some tricks, don't blink!
306
+
307
+ Cross compiling is still very simple:
308
+
309
+ rake cross compile
310
+
311
+ And now, building gems for your Windows users is just 5 more letters:
312
+
313
+ rake cross native gem
314
+
315
+ And you're done, yeah.
316
+
317
+ === But wait, there's more
318
+
319
+ You can specify which version of Ruby to build the extension against:
320
+
321
+ rake cross compile RUBY_CC_VERSION=1.8.6
322
+
323
+ For example, if you installed <tt>1.9.2</tt>, you can do:
324
+
325
+ rake cross compile RUBY_CC_VERSION=1.9.2
326
+
327
+ Even better, you can target multiple versions (ie. 1.8.6 and 1.9.2) in
328
+ the same gem via:
329
+
330
+ rake cross compile RUBY_CC_VERSION=1.8.6:1.9.2
331
+
332
+ And better yet, you can bundle both binary extensions into one so-called "fat"
333
+ gem via:
334
+
335
+ rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.2
336
+
337
+ That will place binaries for both the 1.8 and 1.9 versions of your Ruby
338
+ extensions inside your project's <tt>lib_dir</tt> directory:
339
+
340
+ lib/1.8/my_extension.so
341
+ lib/1.9/my_extension.so
342
+
343
+ NOTE: building "fat" gems is currently only supported by rake-compiler when
344
+ cross compiling from a Linux or OSX host. Patches are welcome if building
345
+ "fat" gems from Windows hosts is desired, or natively for your platform :-)
346
+
347
+ Now is up to you to make your gem load the proper binary at runtime:
348
+
349
+ begin
350
+ RUBY_VERSION =~ /(\d+.\d+)/
351
+ require "#{$1}/my_extension"
352
+ rescue LoadError
353
+ require "my_extension"
354
+ end
355
+
356
+ The above technique will lookup first for 1.8 or 1.9 version of the extension
357
+ and when not found, will look for the plain extension.
358
+
359
+ This approach catch the cases of provided fat binaries or gems compiled by the
360
+ end user installing the gem. It has also been implemented successfully in
361
+ several projects.
362
+
363
+ === What are you talking about? (Give me examples)
364
+
365
+ I know all the above sounds like a complete foreign language (it does even for me!).
366
+ So, what if I show you some examples?
367
+
368
+ Check our wiki with links to the proper rake files used by many developers and
369
+ projects and how they use rake-compiler.
370
+
371
+ http://github.com/luislavena/rake-compiler/wiki/projects-using-rake-compiler
372
+
373
+ == Future
374
+
375
+ rake-compiler is a work in progress and we appreciate any and all feedback
376
+ during the development of it! (and contributions too!)
377
+
378
+ You can find more information about rake-compiler:
379
+
380
+ * GitHub: https://github.com/luislavena/rake-compiler
381
+ * Issues: https://github.com/luislavena/rake-compiler/issues
382
+ * Blog: http://blog.mmediasys.com
383
+ * Docs: http://rubydoc.info/gems/rake-compiler
384
+ * Wiki: https://github.com/luislavena/rake-compiler/wiki
385
+
386
+ == Disclaimer
387
+
388
+ If you have any trouble, don't hesitate to contact the author. As always,
389
+ I'm not going to say "Use at your own risk" because I don't want this library
390
+ to be risky.
391
+
392
+ If you trip on something, I'll share the liability by repairing things
393
+ as quickly as I can. Your responsibility is to report the inadequacies.