File: README

Description

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 which can be used to build Java projects.

Jerbil uses Rjb (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 and hibernate.

Requirements

Jerbil requires rubygems, Rake, Rjb, builder 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: 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. Jerbil::JavacTask.new(:compile, FILES) defines a new task (:compile) 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/ subdirectory in the repository. 

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

Advantages over Ant

See Martin Fowler‘s article 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

FAQ

See FAQ.

Project homepage

code.trampolinesystems.com/jerbil

Contact

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.