root/trunk/README

= Jerbil -- Java build extensions for Rake

  "If I knew then what I know now, I would have tried using a real
  scripting language, such as JavaScript via the Rhino component or
  Python via JPython, with bindings to Java objects which implemented
  the functionality expressed in todays tasks. Then, there would be a
  first class way to express logic and we wouldn't be stuck with XML as
  a format that is too bulky for the way that people really want to use
  the tool."
  
    -- James Duncan Davidson, creator of Apache Ant
 
This package contains several tasklibs for Rake[http://rake.rubyforge.org] which can be
used to build Java projects. 

Jerbil uses Rjb[http://rjb.rubyforge.org/]
(Ruby-Java-Bridge) to load a Java virtual machine into the Ruby process running Rake.

The JVM is then used to compile Java source files, create javadocs etc.
It is not a complete replacement for ant (yet), but has several advantages such as
extremly compact build files and easy scriptability.

The main focus at the moment are small to medium-sized projects using 
testng[http://testng.org] and hibernate[http://hibernate.org].

== Requirements

Jerbil requires rubygems[http://rubygems.org], Rake, Rjb[http://rjb.rubyforge.org/],
builder[http://builder.rubyforge.org/] and JDK 1.5. 

== Installation

You need to have Ruby and rubygems installed. The Windows version of Ruby already ships with rubygems 
preinstalled. On Debian systems (testing) you can install it using apt-get:
  
  % apt-get install rubygems
  
Rake, Rjb and builder are best installed using gem:

  % gem install rake
  % gem install builder
  % gem install rjb
  
The installation of Rjb can be a bit tricky for non-Windows users because 
JAVA_HOME needs to be set up correctly. Also, a C compiler is required in order to 
build the JNI extension for Ruby.

Finally jerbil needs to be installed:

  % gem install jerbil --source http://code.trampolinesystems.com

Jerbil might become an 'official' rubygem at some later point. Note that some tasks require additional
jar files, for example Jerbil::TestNG::TestNGTask.

The source code is available via subversion: http://svn.trampolinesystems.com/jerbil/trunk
  
== Usage

A minimal Rakefile to compile Java files could look like this:

        require 'jerbil'
        
        CLASSPATH = FileList[ "./lib/*.jar" ]
        BUILD_DIR = "build"
        FILES     = JavaFileList.new("src", BUILD_DIR)
        
        load_jvm(CLASSPATH, BUILD_DIR)
        
        Jerbil::JavacTask.new(:compile, FILES) 

The JVM gets loaded once via the Jerbil::JavaHelper load_jvm method. This initialization step is
required, otherwise the task will fail. <tt>Jerbil::JavacTask.new(:compile, FILES)</tt>
defines a new task (<tt>:compile</tt>) which will compile all Java files found in directory
+src+ to +build+.

=== Debugging

As all the code runs in a single JVM, debugging can only be enabled on a global level.
Just add the environment variable +JAVA_DEBUG+. 

  % JAVA_DEBUG='1' rake test

This will load the JVM in debug mode, listening on port 8000. To specify a different port,
use JAVA_DEBUG='port=33333'. Adding +suspend+ to the +JAVA_DEBUG+ environment will suspend execution
until the debugging client connects.

=== Specifiying additional jvm options

  % JAVA_OPTS = '-Xmx=256M' rake test
or
  load_jvm(CLASSPATH, BUILD, :java_opts=>"-Xmx=256M")
  
== Example

See the example/[http://svn.trampolinesystems.com/jerbil/trunk/example] subdirectory
in the repository.

  % svn co http://svn.trampolinesystems.com/jerbil/trunk/example

== Advantages over Ant

See Martin Fowler's article[http://www.martinfowler.com/articles/rake.html] for a detailed
discussion on Rake vs. Ant. Besides the more compact build scripts you also get ability to
implement arbitrary Java interfaces in Ruby (see Jerbil::TestNG::DefaultTestListener for an example).
Another possibility is build script metaprogramming, i.e. creating your tasks programmatically:

  MODULES = [ "common", "core", "server" ]
  MODULES.each_with_index do |m,i|
    Jerbil::JavacTask.new("compile_#{m}") do |t|
      t.java_files = JavaFileList.new(File.join(m,SRC_DIR), DST_DIR)
      MODULES[0..i-1].each {
        |prev| t.depends_on "compile_#{prev}" 
      } if i>0
    end
  end

This snippet creates several build targets (+:compile_common+, +:compile_core+,
+:compile_server+) including correct dependency setup.

Lastly, all the tasks run in one single JVM, speeding up the build significantly.
However this is actually a trade-off as state isolation is not guaranteed between
subsequently run tasks. This shouldn't be a problem in most cases though.

== Related projects

* Raven[http://raven.rubyforge.org/]: similar to Jerbil in scope, but different approach (invokes 
  javac externally, no Java-Ruby integration).
 
== FAQ

See FAQ[http://code.trampolinesystems.com/jerbil/wiki/FAQ].

== Project homepage

http://code.trampolinesystems.com/jerbil
 
== Contact

mailto:jan@trampolinesystems.com

== License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 
or implied. See the License for the specific language governing permissions and limitations under 
the License. 

== 3dparty code / MIT License

This product contains portions of Rails (activesupport/inflector.rb,
activesupport/inflections.rb) which are licensed as follows:

Copyright (c) 2004-2006 David Heinemeier Hansson

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.Copyright (c) 2004-2006 David Heinemeier Hansson