From 42ac32e1500be1b8781cf6a58678ede33bb2a5a4 Mon Sep 17 00:00:00 2001 From: Alex Coles Date: Fri, 27 Nov 2009 14:35:56 +0100 Subject: [PATCH] Start adding documentation for Java to README Signed-off-by: Alex Coles --- README.rdoc | 85 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 31 deletions(-) diff --git a/README.rdoc b/README.rdoc index bec416f..a0d8cb0 100644 --- a/README.rdoc +++ b/README.rdoc @@ -1,14 +1,14 @@ = 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 @@ -18,9 +18,12 @@ Let's summarize what rake-compiler provides: * 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). @@ -32,13 +35,6 @@ 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. @@ -46,11 +42,12 @@ 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 its 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 @@ -63,20 +60,28 @@ to find code and also contribute back to your project more easily. 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 @@ -91,6 +96,10 @@ 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 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. + === Generate native gems A common usage scenario of rake-compiler is generate native gems that bundles @@ -141,6 +150,23 @@ Plus, you have the functionality to build native versions of the 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 @@ -163,7 +189,7 @@ personalize several settings for Rake::ExtensionTask: 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? @@ -171,16 +197,19 @@ different OS (hosts). Besides having the development tool chain installed (GCC), you should install also mingw32 cross compilation package. -This depends on your operating system distribution, a simple -apt-get install mingw32 will be enough. +Installation depends will depend on your operating system/distribution. On +Ubuntu and Debian machines, a simple apt-get install mingw32 will be +enough. -Please check OSX documentation about installing mingw32 from macports. +On OSX, mingw32 is available via MacPorts: port install i386-mingw32-gcc +(ensure you update your ports tree before hand as mingw32 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 @@ -262,12 +291,6 @@ Blog: http://blog.mmediasys.com RubyForge: http://rubyforge.org/projects/rake-compiler GitHub: http://github.com/luislavena/rake-compiler -=== Some of the desired features - -* Rake::JavaJarTask to generate jar packages and gems for JRuby. - - $ rake java gem - == Disclaimer If you have any trouble, don't hesitate to contact the author. As always,