README.rdoc in rake-compiler-0.6.0 vs README.rdoc in rake-compiler-0.7.0

- old
+ new

@@ -1,28 +1,31 @@ = rake-compiler -rake-compiler aims to help Gem developers while dealing with Ruby C -extensions, simplifying the code and reducing the duplication. +rake-compiler aims to help Gem developers deal with Ruby extensions, simplifying +code and reducing duplication. -It follows *convention over configuration* and set an standardized -structure to build and package C extensions in your gems. +It followss *convention over configuration* and sets a standardized structure to +build and package both C and Java extensions in your gems. -This is the result of experiences dealing with several Gems that required -native extensions across platforms and different user configurations -where details like portability and clarity of code were lacking. +This is the result of experiences 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). +* Painlessly build extensions for different Ruby implementations (JRuby, + Rubinius and MRI). + * Allow multiple extensions be compiled inside the same gem. -* Mimics RubyGems installation process, so helps as test environment. +* Mimics RubyGems installation process, so helps as a test environment. * Simplify cross platform compilation of extensions (target Windows from Linux). == I'm sold! show me how to use it! (Installation) @@ -30,29 +33,23 @@ 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: +organize the code and folders that will help rake-compiler do its job: |-- ext | `-- hello_world | |-- extconf.rb + | |-- HelloWorldService.java | `-- hello_world.c |-- lib `-- Rakefile TIP: Having a consistent folder structure will help developers and newcomers @@ -61,24 +58,32 @@ === 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. +If we wanted to do the same for a JRuby extension (written in Java): + + # File: Rakefile + + require 'rake/javaextensiontask' + + Rake::JavaExtensionTask.new('hello_world') + === Compile process Those *two* lines of code automatically added the needed rake tasks to build -the hello_world extension: +the hello_world extension. Running Rake on 1.8.x/1.9 (MRI): $ rake -T - (in /home/user/my_extesion) + (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>: @@ -89,10 +94,14 @@ 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. +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. + === Generate native gems A common usage scenario of rake-compiler is generate native gems that bundles your extensions. @@ -139,10 +148,27 @@ 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. +And the same 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 + + === 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>: @@ -161,28 +187,31 @@ == Future is now: Cross compilation rake-compiler provides now an standardized way to generate, from Linux or OSX both extensions and gem binaries for Windows! -It takes advantages from GCC host/target to build binaries (for target) on +It takes advantages from GCC host/target to build binaries (for target) on different OS (hosts). === How I enjoy this? Besides having the development tool chain installed (GCC), you should install also <tt>mingw32</tt> cross compilation package. -This depends on your operating system distribution, a simple -<tt>apt-get install mingw32</tt> will be enough. +Installation depends will depend on your operating system/distribution. On +Ubuntu and Debian machines, a simple <tt>apt-get install mingw32</tt> will be +enough. -Please check OSX documentation about installing mingw32 from macports. +On OSX, mingw32 is available via MacPorts: <tt>port install i386-mingw32-gcc</tt> +(ensure you update your ports tree before hand as <tt>mingw32</tt> has been +been broken). === I have my tool-chain, now what? You need to build Ruby for Windows. -Relax, no need to freak out. rake-compiler do it for you: +Relax, no need to freak out! Let rake-compiler do it for you: rake-compiler cross-ruby And you're done. It will automatically download, configure and compile latest stable version of Ruby for Windows, and place it into <tt>~/.rake-compiler</tt> @@ -199,10 +228,15 @@ 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' # 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 default GCC platform for Ruby. @@ -254,15 +288,9 @@ You can find more information about rake-compiler: Blog: http://blog.mmediasys.com RubyForge: http://rubyforge.org/projects/rake-compiler GitHub: http://github.com/luislavena/rake-compiler - -=== Some of the desired features - -* <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