svn commit: r794731 - /buildr/trunk/doc/quick_start.textile

[dj...@apache.org]

Author: djspiewak
Date: Thu Jul 16 16:09:56 2009
New Revision: 794731

URL: http://svn.apache.org/viewvc?rev=794731&view=rev
Log:
Revised Quick Start:

 - Removed classpath section from custom tasks
 - Removed crazy talk about artifacts task
 - Changed capitalization to be more consistent (at least within the QS)

Modified:
    buildr/trunk/doc/quick_start.textile

Modified: buildr/trunk/doc/quick_start.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/quick_start.textile?rev=794731&r1=794730&r2=794731&view=diff
==============================================================================
--- buildr/trunk/doc/quick_start.textile (original)
+++ buildr/trunk/doc/quick_start.textile Thu Jul 16 16:09:56 2009
@@ -24,7 +24,7 @@
 => "Hello world"
 {% endhighlight %}
 
-And as you guessed, everything else is Buildfile, Ruby or Java code.  You can figure out which language is which.
+And as you guessed, everything else is buildfile, Ruby or Java code.  You can figure out which language is which.
 
 
 h2(#first-project). Your First Project
@@ -111,13 +111,7 @@
 
 p(tip). You can search the global repository of artifacts at sites like "MvnRepository":http://mvnrepository.com  Simply enter the name of the library you are looking for, and the search should pull up the groupId, artifactId and a list of available versions.
 
-Buildr uses the artifact descriptor and its "list of remote repositories":artifacts.html#repositories to download the relevant JAR file(s) and cache them locally.  Specifically, every downloaded artifact is installed in your local repository, by default located in the @~/.m2/repository/@ directory (yes, even on Windows).  You can explicitly force Buildr to check to make sure that all of its artifacts are current by running the @artifacts@ task:
-
-{% highlight sh %}
-$ buildr artifacts
-{% endhighlight %}
-
-Alternatively, you can simply wait until the next time you run the @compile@ task, at which point Buildr will automatically check to make sure that all of its artifacts are current.  It will also place the relevant JAR files on the classpath of the @javac@ compiler, allowing you to use the libraries in your project.  In one line Ruby, Buildr handles everything that Ivy can do in twenty lines of XML.
+Buildr uses the artifact descriptor and its "list of remote repositories":artifacts.html#repositories to download the relevant JAR file(s) and cache them locally.  Specifically, every downloaded artifact is installed in your local repository, by default located in the @~/.m2/repository/@ directory (yes, even on Windows).  Every time you run the @compile@ task, Buildr will check to make sure you have the correct version of every artifact mentioned in your buildfile.  It will then place the relevant JAR files on the classpath for the @javac@ compiler, allowing you to use the libraries in your project.  In one line of Ruby, Buildr handles everything that Ivy can do in twenty lines of XML.
 
 Unfortunately, not all libraries are quite as simple as Commons CLI.  In particular, many libraries, such as Apache Wicket, have dependencies of their own.  While we may be able to _compile_ against Apache Wicket without these extra libraries on our classpath, we cannot actually _run_ our application without its transitive dependencies.
 
@@ -236,8 +230,6 @@
 
 h2(#custom-tasks). Custom Tasks
 
-p(note). Ok, I lied: this section assumes a _little_ Ruby knowledge.  However, it's nothing that you couldn't pick up after spending 15 minutes with the core library documentation.
-
 If there is one area in which Buildr excels, it is defining custom tasks.  This is something which is notoriously difficult in both Ant and Maven, often requiring separate Java plugins and mountains of code simply to perform basic tasks.  For example, let's imagine that we wanted to define a @run@ task which would compile and run our "killer-app" project.  This is a simple matter of invoking the @java@ command against our main class:
 
 {% highlight ruby %}
@@ -280,35 +272,6 @@
 $ buildr run
 {% endhighlight %}
 
-Let's make things just a little bit harder.  Suppose that our project has some dependencies.  Now, these dependencies have to be included on the classpath.  On top of that, you may have noticed that the command we are passing to @system@ includes a path (@target/classes@) which is relative to the current working directory.  Buildr doesn't introspect our strings, looking for paths, so we have accidentally created a @run@ task which _only_ works when our current working directory is equivalent to the project root.
-
-In order to get around these dillemas, we need to use some of Buildr's API to construct an array of paths which must be added to the Java classpath.  We will then join each of these array elements together using the system-specific path separator ('@:@' on Mac and Unix, '@;@' on Windows) and then use this string as the value of the @-cp@ switch on the @java@ command.  This sounds very intimidating, but it's actually not all that complicated.  If you're familiar with Ruby and its collection APIs, then this should be second nature for you.  If you're not familiar with Ruby, then just treat this as magic pixie dust and trust that it works:
-
-{% highlight ruby %}
-WICKET = transitive('org.apache.wicket:wicket:jar:1.4-rc6')
-SLF4J = 'org.slf4j:slf4j-jdk14:jar:1.5.8'
-
-local_task :run
-
-define 'killer-app' do
-  project.version '0.1.0'
-  compile.with WICKET, SLF4J
-  
-  package :jar
-  
-  task :run => :compile do
-    cp = [compile.target] + compile.dependencies
-    cp_str = cp.map(&:to_s).join File::PATH_SEPARATOR
-    
-    system "java -cp '#{cp_str}' org.apache.killer.Main"
-  end
-end
-{% endhighlight %}
-
-There are two bits of non-standard Ruby within this task: @compile.target@ and @compile.dependencies@.  These are methods which are part of the Buildr API.  The former (@compile.target@) returns a string representing the canonical path to your project's @target/classes/@ directory.  This method works regardless of what the current working directory is, and regardless of what @:layout@ the project may be using.  The latter method returns a Ruby array representing all of the dependencies associated with the @compile@ task.  Technically, this array actually contains instances of class @ArtifactTask@, which is why we must map over this array, invoking the @to_s@ method on each element.  This invocation transforms the artifacts into canonical paths, each pointing to a different JAR file.  The @join@ method takes that array and combines all of the elements into a single string, using @File::PATH_SEPARATOR@ to separate the elements.
-
-The result is stored in @cp_str@, which we include into our @system@ command by using Ruby's @#{...}@ string syntax.  This string represents the _complete_ @compile@ classpath for our project, including all transitive and immediate dependencies, as well as the compile output directory.  In short, this is exactly what we need to pass to the @java@ command in order to ensure that our application runs correctly.  Imagine doing that with Maven!
-
 
 h2(#summary). Summary