Changeset 6104

Show
Ignore:
Timestamp:
11/23/06 18:55:22
Author:
jan
Message:

updated jerbil docs

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk

    • Property svn:ignore changed from pkg html to pkg html rdoc

  • trunk/README

    r6053 r6104  
    1 = Jerbil -- Java build system based on Rake[http://rake.rubyforge.org] and RJB 
     1= Jerbil -- Java build system based on Rake[http://rake.rubyforge.org] and Rjb 
    22 
    33  "If I knew then what I know now, I would have tried using a real 
    …… 
    1111    -- James Duncan Davidson, creator of Apache Ant 
    1212  
    13 This package contains several TaskLibs for Rake which can be 
     13This package contains several TaskLibs for Rake[http://rake.rubyforge.org] which can be 
    1414used to build Java projects.  
    1515 
    16 Jerbil uses RJB[http://raa.ruby-lang.org/project/rjb/] 
    17 (Ruby-Java-Bridge) to load a Java virtual machine into Rake. 
     16Jerbil uses Rjb[http://rjb.rubyforge.org/] 
     17(Ruby-Java-Bridge) to load a Java virtual machine into the Ruby process running Rake. 
    1818 
    19 The jvm is then used to compile Java source files, create javadocs etc. 
     19The JVM is then used to compile Java source files, create javadocs etc. 
    2020It is not a complete replacement for ant (yet), but has several advantages such as 
    21 extremly compact build files and easy scriptability.  
     21extremly compact build files and easy scriptability. 
    2222 
    2323The main focus at the moment are small to medium-sized projects using  
    …… 
    2626== Requirements 
    2727 
    28 Jerbil requires rubygems[http://rubygems.org], Rake, RJB and JDK 1.5.  
     28Jerbil requires rubygems[http://rubygems.org], Rake, Rjb, builder[http://builder.rubyforge.org/] 
     29and JDK 1.5.  
    2930 
    3031== Installation 
    …… 
    3435  % apt-get install rubygems 
    3536   
    36 Rake and rjb are best installed using gem: 
     37Rake, Rjb and builder are best installed using gem: 
    3738 
    3839  % gem install rake 
    3940  % gem install rjb 
     41  % gem install builder 
    4042   
    41 The installation of rjb requires that the JDK is installed and JAVA_HOME set up 
     43The installation of Rjb requires that the JDK is installed and JAVA_HOME set up 
    4244accordingly. Finally jerbil needs to be installed: 
    4345 
    …… 
    4749jar files, for example Jerbil::TestNG::TestNGTask. 
    4850 
    49 The source code is available via subversion: http://svn.trampolinesystems.com/jerbil/ 
     51The source code is available via subversion: http://svn.trampolinesystems.com/jerbil/trunk 
    5052   
     53== Usage 
     54 
     55A minimal Rakefile to compile Java files looks like this: 
     56 
     57        require 'jerbil' 
     58         
     59        CLASSPATH = FileList[ "./lib/*.jar" ] 
     60        BUILD_DIR = "build" 
     61        FILES     = JavaFileList.new("src", BUILD_DIR) 
     62         
     63        load_jvm(CLASSPATH, BUILD_DIR) 
     64         
     65        Jerbil::JavacTask.new(:compile, FILES)  
     66 
     67The JVM gets loaded once via the +load_jvm+ method. This initialization step is 
     68required, otherwise the task will fail. <tt>Jerbil::JavacTask.new(:compile, FILES)</tt> 
     69defines a new task (<tt>:compile</tt>) which will compile all Java files found in directory 
     70+src+ to +build+. 
     71 
    5172== Example 
    5273 
    53 See the example/[http://svn.trampolinesystems.com/jerbil/trunk/example] subdirectory in the repository. 
     74See the example/[http://svn.trampolinesystems.com/jerbil/trunk/example] subdirectory 
     75in the repository. 
    5476 
    5577  % svn co http://svn.trampolinesystems.com/jerbil/trunk/example 
    …… 
    5779== Advantages over Ant 
    5880 
    59 Well, it's based on Ruby :) Additionally, RJB allows Ruby code to implement arbitary 
    60 Java interfaces which you can then pass into compiled Java code.   
    61 See Jerbil::TestNG::TestListener for an example. 
     81See Martin Fowler's article[http://www.martinfowler.com/articles/rake.html] for a detailed 
     82discussion on Rake vs. Ant. Besides the more compact build scripts you also get ability to 
     83implement arbitrary Java interfaces in Ruby (see Jerbil::TestNG::TestListener for an example). 
     84Another possibility is build script metaprogramming, i.e. creating your tasks programmatically: 
     85 
     86  MODULES = [ "common", "core", "server" ] 
     87  MODULES.each_with_index do |m,i| 
     88    Jerbil::JavacTask.new("compile_#{m}") do |jct| 
     89      jct.java_files = JavaFileList.new(File.join(m,SOURCE_DIR), JAVA_BUILD_DIR) 
     90      MODULES[0..i-1].each {|prev| jct.depends_on "compile_#{prev}" } if i>0 
     91    end 
     92  end 
     93 
     94This snippet creates several build targets (:compile_common, :compile_core, :compile_server)  
     95including correct dependencies. 
    6296 
    6397== Related projects 
    6498 
    65 * Raven[http://raven.rubyforge.org/]: similar to jerbil in scope, but different approach (invokes  
     99* Raven[http://raven.rubyforge.org/]: similar to Jerbil in scope, but different approach (invokes  
    66100  javac directly, no Java-Ruby integration). 
    67101  
    …… 
    72106== Contact 
    73107 
    74 Questions? Feedback? 
    75108mailto:jan@trampolinesystems.com 
    76109 

  • trunk/Rakefile

    r6056 r6104  
    6363  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README' 
    6464  rdoc.rdoc_files.include("README", "CHANGES", "TODO", "LICENSE", "lib/**/*.rb") 
     65        rdoc.rdoc_dir = 'rdoc' 
    6566end 
    6667   

  • trunk/lib/jerbil/java_helper.rb

    r6103 r6104  
    410410end 
    411411 
    412 # make some stuff available to the toplevel 
    413  
     412# make JavaFileList available to toplevel 
    414413JavaFileList = Jerbil::JavaFileList 
    415414 
     415# make load_jvm available to toplevel 
    416416def load_jvm(args, build_dir, options={}) 
    417417        Jerbil::JavaHelper.load_jvm(args, build_dir, options)                    

  • trunk/lib/jerbil/javac_task.rb

    r6060 r6104  
    2424    create_alias_for :g, :debug 
    2525     
    26     def initialize(name)    
     26    def initialize(name, files = nil)    
    2727      @name = name 
    2828      @verbose = false 
     29                        @java_files = files 
    2930     
    3031      yield self if block_given? 
     32                         
     33                        raise "need java_files" if java_files.nil? 
     34                         
    3135      depends_on java_files.dstdir 
     36                        #CLEAN.include(java_files.dstdir) if CLEAN 
     37                         
    3238      define      
    3339    end