more_stuff.textile in assaf-buildr-1.3.4

- old
+ new

@@ -80,41 +80,63 @@
 # Call @Java.load@ once before accessing any Java classes, allowing Buildr to set up the classpath.
 # Only call @Java.load@ when invoked, otherwise you may end up loading the JVM with a partial classpath, or before all remote repositories are listed.
 # Check on a clean build with empty local repository.
 
 
-h2. Nailgun
+h2. BuildrServer
 
-"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client, protocol, and server for running Java programs from the command line without  incurring the JVM startup overhead.  Nailgun integration is available only when running Buildr within JRuby.
+Buildr provides an addon that allows you start a "dRuby":http://www.ruby-doc.org/stdlib/libdoc/drb/rdoc/index.html server hosting a buildfile, so that you can later invoke tasks on it without having to load the complete buildr runtime again.
 
-Buildr provides a custom nailgun server, allowing you to start a single JVM and let buildr create a queue of runtimes. These JRuby runtimes can be cached (indexed by buildfile path) and are  automatically reloaded when the buildfile has been modified. Runtime caching allows you to execute tasks without spending time creating  the buildr environment. 
+Usage:
 
-Start the BuildrServer by executing
+{{{!sh
+buildr -r buildr/drb drb:start
+}}}
 
+To stop the BuildrServer simply use Ctrl+C or kill the process.
+
+Once the server has been started you can invoke tasks using a simple script:
+
 {{{!ruby
-$ jruby -S buildr -rbuildr/nailgun nailgun:start
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'buildr/drb'
+Buildr::DRbApplication.run
 }}}
 
-Server output will display a message when it becomes ready, you will also see messages when the JRuby runtimes are being created, or when a new buildr environment is being loaded on them. After the runtime queues have been populated, you can start calling buildr as you normally do, by invoking the $NAILGUN_HOME/ng binary:
+Save this script as @dbuildr@, make it executable and use it to invoke tasks.
+  
+{{{!sh
+$ dbuildr clean compile
+}}}
 
+@dbuildr@ will start the BuildrServer if there isn't one already running.
+Subsequent calls to dbuildr will act as the client and invoke the tasks you
+provide to the server.
+If the buildfile has been modified it will be reloaded on the BuildrServer.
+
+h3. Nailgun
+
+"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client, protocol, and server for running Java programs from the command line without incurring the JVM startup overhead.  Nailgun integration is available only when running Buildr within JRuby.
+
+JRuby users need not to create the @dbuildr@ script listed on the previous section, as they can benefit from
+using a nailgun client to invoke tasks without having to wait for JVM+JRuby to load.
+
+Start the BuildrServer by executing
+
 {{{!sh
-# on another terminal, change directory to a project.
-# if this project is the same nailgun:start was invoked on, it's 
-# runtime has been cached, so no loading is performed unless 
-# the buildfile has been modified. otherwise the buildfile 
-# will be loaded on a previously loaded fresh-buildr runtime
-# and it will be cached.
-cd /some/buildr/project
-ng nailgun:help                      # display nailgun help
-ng nailgun:tasks                     # display overview of ng tasks
-ng clean compile                # just invoke those two tasks
+$ jruby -S buildr -rbuildr/nailgun nailgun:start
 }}}
 
-Some nailgun tasks have been provided to manage the cached runtimes,  to get an overview of them execute the @nailgun:tasks@ task.
+To stop the BuildrServer simply use Ctrl+C or kill the process.
 
-Be sure to read the nailgun help by executing the @nailgun:help@ task.
+Once the server has been started you can invoke tasks using the nailgun client
+installed on @$JRUBY_HOME/tool/nailgun/ng@
 
+{{{!sh
+$ ng clean compile
+}}}
 
 h2. Growl, Qube
 
 For OS X users, Buildr supports "Growl":http://growl.info/ out of the box to send "completed and "failed" notifications to the user.
 
@@ -156,10 +178,16 @@
 
 The @eclipse@ task will generate a @.classpath@ and @.project@ file for each of projects (and sub-project) that compiles source code.  It will not generate files for other projects, for examples, projects you use strictly for packaging a distribution, or creating command line scripts, etc.
 
 If you add a new project, change the dependencies, or make any other change to your Buildfile, just run the @eclipse@ task again to re-generate the Eclipse project files.
 
+To have your libraries' source code available in Eclipse, run:
+ 
+{{{!sh
+$ buildr artifacts:sources
+}}}
+
 If you prefer IntelliJ IDEA, you can always:
 
 {{{!sh
 $ buildr idea
 }}}
@@ -211,21 +239,21 @@
 The other two tasks are @jdepend:text@ and @jdepend:xml@.
 
 We want Buildr to load fast, and not everyone cares for these tasks, so we don't include them by default.  If you want to use one of them, you need to require it explicitly.  The proper way to do it in Ruby:
 
 {{{!ruby
-require 'buildr/cobertura'
-require 'buildr/emma'
+require 'buildr/java/cobertura'
+require 'buildr/java/emma'
 require 'buildr/jdepend'
 }}}
 
 You may want to add those to the Buildfile.  Alternatively, you can use these tasks for all your projects without modifying the Buildfile.  One convenient method is to add these lines to the @buildr.rb@ file in your home directory.
 
 Another option is to require it from the command line (@--require@ or @-r@), for example:
 
 {{{!sh
 $ buildr --require buildr/jdepend jdepend:swing
-$ buildr -rbuildr/cobertura cobertura:html
+$ buildr -rbuildr/java/cobertura cobertura:html
 }}}
 
 
 h2. Anything Ruby Can Do
 