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 @bui...@.
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.
