You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildr.apache.org by as...@apache.org on 2009/07/16 02:36:40 UTC
svn commit: r794473 - in /buildr/trunk/doc: _layouts/default.html
download.textile index.textile installing.textile preface.textile
quick_start.textile setup_guide.textile
Author: assaf
Date: Thu Jul 16 00:36:39 2009
New Revision: 794473
URL: http://svn.apache.org/viewvc?rev=794473&view=rev
Log:
Setup guide becomes Installing & Running, since it deals with both.
Quick Start guide moved to the beginning (of the PDF) and top section (Web site).
Moved document conventions to Quick Start guide.
Fixed H2 links in Quick Start and renamed Compilation => Compiling (active verbs are better).
Added:
buildr/trunk/doc/installing.textile
- copied, changed from r794155, buildr/trunk/doc/setup_guide.textile
Removed:
buildr/trunk/doc/setup_guide.textile
Modified:
buildr/trunk/doc/_layouts/default.html
buildr/trunk/doc/download.textile
buildr/trunk/doc/index.textile
buildr/trunk/doc/preface.textile
buildr/trunk/doc/quick_start.textile
Modified: buildr/trunk/doc/_layouts/default.html
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/_layouts/default.html?rev=794473&r1=794472&r2=794473&view=diff
==============================================================================
--- buildr/trunk/doc/_layouts/default.html (original)
+++ buildr/trunk/doc/_layouts/default.html Thu Jul 16 00:36:39 2009
@@ -20,22 +20,17 @@
</div>
<div id='pages'>
<ol class='toc'>
- <li>Overview
+ <li>Start Here
<ol class="toc">
<li><a href='index.html'>Welcome</a></li>
- <li><a href='download.html'>Download</a></li>
- <li><a href='buildr.pdf'>User Guide (PDF)</a></li>
+ <li><a href='quick_start.html'>Quick Start</a></li>
+ <li><a href='installing.html'>Installing & Running</a></li>
<li><a href='http://cwiki.apache.org/confluence/display/BUILDR/Index'>Community Wiki</a></li>
</ol>
</li>
- <li>Start Here
- <ol class="toc">
- <li><a href='setup_guide.html'>Setup Guide</a></li>
- <li><a href='quickstart.html'>Quick Start</a></li>
- </ol>
- </li>
<li>Using Buildr
<ol class="toc">
+ <li><a href='buildr.pdf'>This Guide (PDF)</a></li>
<li><a href='projects.html'>Projects</a></li>
<li><a href='building.html'>Building</a></li>
<li><a href='artifacts.html'>Artifacts</a></li>
@@ -58,6 +53,7 @@
</li>
<li>Get Involved
<ol class="toc">
+ <li><a href='download.html'>Download</a></li>
<li><a href='mailing_lists.html'>Mailing Lists</a></li>
<li><a href='http://issues.apache.org/jira/browse/Buildr'>Issues/Bugs</a></li>
<li><a href='contributing.html'>Contributing</a></li>
Modified: buildr/trunk/doc/download.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/download.textile?rev=794473&r1=794472&r2=794473&view=diff
==============================================================================
--- buildr/trunk/doc/download.textile (original)
+++ buildr/trunk/doc/download.textile Thu Jul 16 00:36:39 2009
@@ -6,7 +6,7 @@
h2(#install). Installing Buildr
-*The easy way:* The "Getting Started guide":getting_started.html will show you how to install Buildr in a matter of minutes.
+*The easy way:* Follow the "quick installation instructions":installing.html to get Buildr up and running in a matter of minutes.
h2(#dists). Official & Unofficial Distributions
Modified: buildr/trunk/doc/index.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/index.textile?rev=794473&r1=794472&r2=794473&view=diff
==============================================================================
--- buildr/trunk/doc/index.textile (original)
+++ buildr/trunk/doc/index.textile Thu Jul 16 00:36:39 2009
@@ -38,7 +38,7 @@
* Simple way to upgrade to new versions.
* Did we mention fast?
-So let's get started. You can "read the documentation online":getting_started.html, or "download the PDF":buildr.pdf.
+So let's get started. You can "read the documentation online":quick_start.html, or "download the PDF":buildr.pdf.
h2(#news). What's New
Copied: buildr/trunk/doc/installing.textile (from r794155, buildr/trunk/doc/setup_guide.textile)
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/installing.textile?p2=buildr/trunk/doc/installing.textile&p1=buildr/trunk/doc/setup_guide.textile&r1=794155&r2=794473&rev=794473&view=diff
==============================================================================
--- buildr/trunk/doc/setup_guide.textile (original)
+++ buildr/trunk/doc/installing.textile Thu Jul 16 00:36:39 2009
@@ -1,6 +1,6 @@
---
layout: default
-title: Setup Guide
+title: Installing and Running
---
@@ -182,25 +182,6 @@
Run @buildr --version@ from the command line to find which version of Buildr you are using by default. If you see @(JRuby ...)@, Buildr is running on that version of JRuby.
-h2(#conventions). Document Conventions
-
-Lines that start with @$@ are command lines, for example:
-
-{% highlight sh %}
-$ # Run Buildr
-$ buildr
-{% endhighlight %}
-
-Lines that start with @=>@ show output from the console or the result of a method, for example:
-
-{% highlight sh %}
-puts 'Hello world'
-=> "Hello world"
-{% endhighlight %}
-
-And as you guessed, everything else is Buildfile Ruby or Java code. You can figure out which language is which.
-
-
h2(#running). Running Buildr
You need a *Buildfile*, a build script that tells Buildr all about the projects it's building, what they contain, what to produce, and so on. The Buildfile resides in the root directory of your project. We'll talk more about it in "the next chapter":projects.html. If you don't already have one, ask Buildr to create it by running @buildr@.
Modified: buildr/trunk/doc/preface.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/preface.textile?rev=794473&r1=794472&r2=794473&view=diff
==============================================================================
--- buildr/trunk/doc/preface.textile (original)
+++ buildr/trunk/doc/preface.textile Thu Jul 16 00:36:39 2009
@@ -5,7 +5,8 @@
p(title). !images/zbuildr.png!
<ol class='toc'>
- <li>"Getting Started":getting_started.html</li>
+ <li>"Quick Start":quick_start.html</li>
+ <li>"Installing and Running":installing.html</li>
<li>"Projects":projects.html</li>
<li>"Building":building.html</li>
<li>"Artifacts":artifacts.html</li>
Modified: buildr/trunk/doc/quick_start.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/quick_start.textile?rev=794473&r1=794472&r2=794473&view=diff
==============================================================================
--- buildr/trunk/doc/quick_start.textile (original)
+++ buildr/trunk/doc/quick_start.textile Thu Jul 16 00:36:39 2009
@@ -3,12 +3,31 @@
title: Quick Start
---
-This guide is meant to be a _very_ simple introduction to Buildr and its most basic concepts. However, despite its basic level, we will still manage to cover most of the concepts you will ever need to be productive with Buildr. We will leave out some important things (like "sub-projects":projects.html), and we will over-simplify some other concepts (such as "artifacts":artifacts.html). Nevertheless, most Buildr projects never need to go beyond the techniques contained within these pages.
+This quick start guide is meant to be a _very_ simple introduction to Buildr and its most basic concepts. However, despite its basic level, we will still manage to cover most of the concepts you will ever need to be productive with Buildr. We will leave out some important things (like "sub-projects":projects.html), and we will over-simplify some other concepts (such as "artifacts":artifacts.html). Nevertheless, most Buildr projects never need to go beyond the techniques contained within these pages.
-*No knowledge of Ruby is assumed.* Buildr is designed to be a very intuitive, very easy-to-use tool. You can create buildfiles which describe incredibly intricate projects, write custom tasks which do things far beyond Ant, and still never need to pick up more than a smattering of Ruby syntax. With that said, if you do know Ruby, Buildr's DSL will seem very natural and welcoming, but Ruby expertise is by no means a prerequisite. We do however assume that you have already "downloaded and installed":setup_guide.html Buildr and are ready to put the tool to good use.
+*No knowledge of Ruby is assumed.* Buildr is designed to be a very intuitive, very easy-to-use tool. You can create buildfiles which describe incredibly intricate projects, write custom tasks which do things far beyond Ant, and still never need to pick up more than a smattering of Ruby syntax. With that said, if you do know Ruby, Buildr's DSL will seem very natural and welcoming, but Ruby expertise is by no means a prerequisite. We do however assume that you have already "downloaded and installed":installing.html Buildr and are ready to put the tool to good use.
-(#first-project) h2. Your First Project
+h2(#conventions). Document Conventions
+
+Lines that start with @$@ are command lines, for example:
+
+{% highlight sh %}
+$ # Run Buildr
+$ buildr
+{% endhighlight %}
+
+Lines that start with @=>@ show output from the console or the result of a method, for example:
+
+{% highlight sh %}
+puts 'Hello world'
+=> "Hello world"
+{% endhighlight %}
+
+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
Much like Maven, Buildr is oriented around projects and tasks. You define your project in a concise, declarative fashion and most common tasks (such as compilation and testing) will be made available to you "at no extra charge". Most of the project definition is contained within the _buildfile_ -- or _Buildfile_, if you're really in love with the Make convention -- a single file sitting at the root of your project. A project definition does not need to be any more complicated than the following:
@@ -16,7 +35,7 @@
define 'killer-app'
{% endhighlight %}
-h3. Compilation
+h3. Compiling
Of course, this isn't really giving Buildr much information. What it can't learn from the buildfile, Buildr will learn by inspecting your directory structure. Java sources are expected to exist within the @src/main/java/@ directory. If Buildr finds these sources, it will automatically configure the compilation to source that directory, depositing the compilation results in the @target/classes/@ directory (all under the project root of course). We can run this compilation using the following command:
@@ -73,7 +92,7 @@
{% endhighlight %}
-(#dependencies) h2. Dependencies
+h2(#dependencies). Dependencies
So far, we have seen how Buildr can automatically infer what amounts to dozens of lines of @build.xml@ contents, all based on a buildfile and a directory structure. However, the best is yet to come. Buildr also provides Maven-style dependency management. In other words, you specify each dependent library using a string descriptor and Buildr figures out how to download and configure your classpath to use these libraries. For example, we can configure our project to reference the "Apache Commons CLI":http://commons.apache.org/cli/ library:
@@ -169,7 +188,7 @@
This is one area where Buildr's dependency management vastly excedes Maven's. With Maven, you would have to install the DBPool dependency manually. Buildr's auto-magical download and extraction keeps the dependency definitions centralized within the buildfile, available to your entire team and automatically resolved as needed by the compilation tasks.
-(#tasks) h2. Testing
+h2(#testing). Testing
Buildr supports auto-magical integration with a number of mainstream testing frameworks. For Java, this includes the ubiquitus JUnit4, as well as TestNG and a number of others. Scala supports Specs and ScalaTest, while Groovy supports EasyB. Configuration is as simple as placing our test sources in the appropriate directory. In the case of JUnit4, this would be @src/test/java/@. Once these tests are in place, we can run them using the @test@ task:
@@ -215,7 +234,7 @@
Other test frameworks are documented "here":testing.html and "here":languages.html.
-(#custom-tasks) h2. Custom Tasks
+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.
@@ -291,6 +310,6 @@
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!
-(#summary) h2. Summary
+h2(#summary). Summary
As long as this guide was, we have barely even scratched the surface of Buildr's true power. This was meant only to get you up and running as quickly as possible, exploiting some of Buildr's unique features to ease your build process. For more comprehensive documentation, start reading about "projects in Buildr":projects.html and work your way from there.