buildr 1.3.4 → 1.3.5

data/doc/contributing.textile

@@ -27,18 +27,16 @@ If it needs more attention, start a discussion over on the mailing list.  We wil
 
 When reporting a bug, please tell us which version of Ruby, Buildr and Java you are using, and also which operating system you are on:
 
-<notextile>
 {% highlight sh %}
 $ ruby --version
 $ buildr --version
 $ java --version
 {% endhighlight %}
-</notextile>
 
 
 h2(#wiki).  Community Wiki
 
-Our community Wiki is available at "http://cwiki.apache.org/confluence/display/BUILDR/Index":http://cwiki.apache.org/confluence/display/BUILDR/Index.
+"Our community Wiki":http://cwiki.apache.org/confluence/display/BUILDR/Index.
 
 
 h2(#code).  Contributing Code
@@ -81,19 +79,25 @@ You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/buil
 
 h3(#git).  Git
 
-Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from GitHub":http://github.com/buildr/buildr/tree/master:
+Not a fan of SVN?  We understand.  You can also use the "official Apache Git clone.":http://git.apache.org  This clone is maintained by the ASF and kept in sync with the SVN repository (though, in practice there may be some delay in cloning recent commits).  Apache's Git hosting supports both git:// and http:// protocols (you should use git:// if at all possible as it is faster than http://):
 
-<notextile>
 {% highlight sh %}
-$ git clone git://github.com/buildr/buildr.git
+$ git clone git://git.apache.org/buildr.git
+# or...
+$ git clone http://git.apache.org/buildr.git
 {% endhighlight %}
-</notextile>
 
 If you want to learn more about Git, you can start by watching Scott Chacon’s "Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816 (PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more, there's also the "Git Internals book":http://peepcode.com/products/git-internals-pdf.
 
 And keep this "Git cheat sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png close at hand. Very useful.
 
-*Note:* The GitHub repository is maintained by contributors to this project, but is *not* an official Apache repository.  To obtain Buildr from the official Apache repository, consider using @git-svn@ instead.
+h4. GitHub
+
+You are also welcome to fork or clone the "Buildr repository on GitHub":http://github.com/apache/buildr.  This repository is just an exact mirror of the official Apache Git clone referenced above (updated every 30 minutes).  Some of the core committers also maintain their own forks of Buildr on GitHub, often containing experimental and in-progress development slated for eventual inclusion into the SVN.  For reference, they are listed below:
+
+* "Assaf Arkin":http://github.com/assaf/buildr
+* "Victor Hugo Borja":http://github.com/vic/buildr
+* "Daniel Spiewak":http://github.com/djspiewak/buildr
 
 h3. Working with Source Code
 
@@ -130,12 +134,10 @@ Since Ruby Gems uses version numbers to detect new releases, if you installed Bu
 
 If you want to go back to using the RubyForge releases:
 
-<notextile>
 {% highlight sh %}
 gem source --remove http://people.apache.org/~assaf/buildr/snapshot/
 gem install buildr
 {% endhighlight %}
-</notextile>
 
 
 h2(#testing).  Tested and Documented
@@ -182,17 +184,45 @@ Yes, we do make typos, spelling errors and sometimes we write things that don't
 
 For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA.
 
-If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from SVN, edit, and @svn diff@ to create a patch.
+If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from Git/SVN, edit, and @svn diff@ to create a patch.
 
 We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML.  You can learn it all in a few minutes from the "Textile Reference Manual":http://redcloth.org/textile.  Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html.
 
-You can always check the documentation to see which conventions we use, and also a couple of extensions we have for styling source code (with syntax highlighting!) and handling footnotes.  The table of contents is auto-generated form H1/H2 headers.
+Syntax highlighting handled by "Pygments":http://pygments.org.  Use the special @highlight@ tag to separate code sample from the rest of the text and to tell Pygments which language to use.  For example:
+
+<notextile><pre>
+&#123;&#37; highlight ruby &#37;&#125;
+define 'project' do
+  # Just a sample
+end
+&#123;&#37; endhighlight &#37;&#125;
+</pre></notextile>
+
+Have a look at existing documentation to see writing conventions, specifically:
+
+* Separate paragraphs with two newlines.
+* Use one newline only if you need a &lt;br&gt; tag, otherwise, no newlines inside the paragraph.
+* When creating a new page, don't forget the YAML premable at the top (Jekyll needs the page title and layout).
+* The layout uses H1 to render the page title; only use H2 through H4 for the page content.
+* Use H2 headers for the major page sections.  Give each H2 header a unique ID so the table of contents can link to it.
+* Separating sentences with two spaces, just a convenience when editing in a text editor using monospaced fonts.
+* If in doubt, ask.
+
+To go from Textile to HTML we use "Jekyll":http://github.com/mojombo/jekyll.  You can use the @jekyll@ rake task to transform the files under @doc@ and create a copy of the Web site in the directory @_site@.  For example:
+
+{% highlight sh %}
+$ rake jekyll
+$ open _site/index.html
+{% endhighlight %}
 
-The tool we use for this is called Docter, which we developed specifically for Buildr, and use to create the Web site and printable PDF.  If you want to try it out you'll need to first @gem install docter@.  To generate a copy of the Web site, simple run @rake html@ .
+There is no live editing, but you can run @rake jekyll auto=true@, and when you update and save a Textile page it will regenerate the corresponding HTML page.
 
-If you're thinking of editing the docs, and using @rake html@ to see what the HTML looks like, you may want to try something simpler.  Start by running the Docter Web server with @rake docter@ and then point your browser at @http://localhost:3000@.  To see your edits, simply refresh the page.
+To go from HTML to PDF we use "PrinceXML":http://www.princexml.com/.  The target file @buildr.pdf@ is generated by first running Jekyll and then merging the generated HTML pages into a single PDF document.  For example:
 
-Generating the PDF is a bit more tricky, we use the HTML in combination with print media CSS stylesheets and run them through the wonderful "PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML first before you can @rake pdf@.
+{% highlight sh %}
+$ rake buildr.pdf
+$ open buildr.pdf
+{% endhighlight %}
 
 
 h2(#contributors).  Contributors
@@ -201,6 +231,8 @@ Here is the list of people who are actively working and committing on Buildr:
 
 *"Assaf Arkin":http://labnotes.org* (assaf at apache.org)
 
+Started working on Buildr because Maven was too much pain and Rake wasn't enough.  Assaf has been hanging around Apache since 1999, as founding contributor to XML Apache, Ode and Buildr.  Assaf is also co-author of "Ruby In Practice":http://manning.com/mcanally/.
+
 *Alex Boisvert*
 
 Came to Buildr as a refuge from the Maven Uncertainty Principle.  Alex has been working mostly on the Scala integration and believes Ruby scripting is a great complement to statically typed languages. 
@@ -214,3 +246,7 @@ Currently a Java Developer at "http://jwmsolutions.com":http://jwmsolutions.com,
 *Lacton* (lacton at apache.org)
 
 A test-infected developer since 2001, Lacton yearns for a development infrastructure that would shorten feedback loops so much that testing, building, refactoring and committing would feel as easy and natural as breathing air.
+
+*"Daniel Spiewak":http://www.codecommit.com/blog* (djspiewak at apache.org)
+
+Daniel originally came to Buildr in search of a Scala build tool which was better than Ant.  He got more than he bargained for.  Now, he works to advance Buildr as the absolute best tool for supporting Scala development.

data/doc/css/default.css

@@ -79,7 +79,7 @@ blockquote {
   padding-right: 2em;
   margin-left: 0.3em;
   margin-right: 0;
-  border-left: 1px solid #3c78b5;
+  font-style: italic;
 }
 
 ul { 
@@ -121,14 +121,16 @@ th, thead td {
 
 #header {
   margin: 0 0 3em 18em;
+  position: relative;
 }
 
 #header .tagline {
   float: right;
-  font-size: 1.5em;
+  font-size: 1.2em;
   font-weight: bold;
-  position: relative;
-  bottom: 4.5em;
+  position: absolute;
+  top: 0.6em;
+  right: 0;
 }
 
 
@@ -168,6 +170,11 @@ th, thead td {
   margin-top: 2em;
   padding: 0.3em 0 0.5em 0.5em;
 }
+#pages ol li p  {
+  font-weight: normal;
+  color: #000;
+  vertical-align: center;
+}
 
 
 #content { /* Parent Wrapper for inside boxes */

data/doc/css/print.css

@@ -15,34 +15,33 @@
  */
 
 
-@page { 
-  margin: 1in 0.75in 1in 0.75in;
-  @top-left, @top-right {
-    font-family: "Gill Sans";
-    font-weight: normal;
+@media print {
+  @page { size: letter; }
+  @page:first {
+    @top-left  { content: normal }
+    @top-right { content: normal }
+  }
+  @page:right {
+    margin: 1.25in 1in 1.5in 1.5in;
+    font: normal 10pt "Gill Sans" !important;
+    @top-left  { content: string(pagetitle); }
+    @top-right { content: counter(page); }
+  }
+  @page:left {
+    margin: 1.25in 1.5in 1.5in 1in;
+    font: normal 10pt "Gill Sans" !important;
+    @top-left  { content: counter(page); }
+    @top-right { content: string(pagetitle); }
   }
-}
-@page:left {
-  @top-left { content: counter(page); }
-  @top-right { content: string(pagetitle); }
-}
-@page:right {
-  @top-left { content: string(pagetitle); }
-  @top-right { content: counter(page); }
-}
-@page:first {
-  @top-left { content: normal }
-  @top-right { content: normal }
-}
 
-@media print {
   title { string-set: doctitle content(); }
 
   body {
-    font-family: "Helvetica Neue", "DejaVu Sans", "Verdana";
+    font-family: "Palatino";
     margin: 0;
     color: black;
     background: white;
+    font-size: 11pt;
   }
 
   h1 {
@@ -56,12 +55,16 @@
   pre, p, blockquote { page-break-inside: avoid; }
   pre, code {
     font-family: "Monaco", "DejaVu Sans Mono", "Courier New", "Courier";
-    font-size: 10pt;
+    font-size: 9pt;
+  }
+  pre br {
+    display: none;
   }
   a:link, a:visited {
     background: transparent;
     text-decoration: none;
   }
+  
 
   #header, #pages, #footer { display: none }
   #wrap, #content {
@@ -82,12 +85,17 @@
     border: none;
   }
   .title img {
-    width: 20em;
-    margin: 2em auto 2em auto;
+    display: block;
+    width: 80%;
+    margin: 2em auto 4em auto;
   }
   p.preface {
     page-break-before: always;
-    padding-top: 2.5in;
+    padding-top: 1.5in;
+  }
+  div.preface.quotes {
+    page-break-before: always;
+    padding-top: 1in;
   }
 
 }

data/doc/download.textile

@@ -6,7 +6,7 @@ title: Download
 
 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
@@ -23,6 +23,7 @@ h2(#dist).  Binaries and Source Code
 h3. buildr 1.3.4 (2009-04-21)
 
 |_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.4.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem | "34247286f910be1724f63b9e795e75ed":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.asc |
 | "buildr-1.3.4-java.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem | "44ed67bf835cf2abdc2b6723b5eceadb":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.asc |
 | "buildr-1.3.4.tgz":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz | "7d918b88a3bb8139f28f6ff0b39d003c":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.asc |
 | "buildr-1.3.4.zip":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip | "8f4cf84dc6e293aac5fba7e2a9cc0776":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.asc |

data/doc/extending.textile

@@ -11,7 +11,6 @@ For example, we use OpenJPA in several projects.  It's a very short task, but ea
 
 Compare this:
 
-<notextile>
 {% highlight ruby %}
 file('derby.sql') do
   REQUIRES = [
@@ -32,11 +31,9 @@ file('derby.sql') do
   end
 end
 {% endhighlight %}
-</notextile>
 
 To this:
 
-<notextile>
 {% highlight ruby %}
 file('derby.sql') do
   mapping_tool :action=>'build', :sql=>task.name,
@@ -44,16 +41,22 @@ file('derby.sql') do
     :classpath=>projects('store', 'utils')
 end
 {% endhighlight %}
-</notextile>
 
 I prefer the second.  It's easier to look at the Buildfile and understand what it does.  It's easier to maintain when you only have to look at the important information.
 
 But just using functions is not always enough.  You end up with a Buildfile containing a lot of code that clearly doesn't belong there.  For starters, I recommend putting it in the @tasks@ directory.  Write it into a file with a @.rake@ extension and place that in the @tasks@ directory next to the Buildfile.  Buildr will automatically pick it up and load it for you.
 
-If you want to share these pre-canned definitions between projects, you have a few more options.  You can share the @tasks@ directory using SVN externals. Another mechanism with better version control is to package all these tasks, functions and modules into a "Gem":http://rubygems.org/ and require it from your Buildfile.  You can run your own internal Gem server for that.
+If you want to share these pre-canned definitions between projects, you have a few more options.  You can share the @tasks@ directory using SVN externals, Git modules, or whichever cross-repository feature your source control system supports. Another mechanism with better version control is to package all these tasks, functions and modules into a "Gem":http://rubygems.org/ and require it from your Buildfile.  You can run your own internal Gem server for that.
 
-For individual task files, you can also use "Sake":http://errtheblog.com/post/6069 for system-wide Rake tasks deployment.
+To summarize, there are several common ways to distribute extensions: 
+* Put them in the same place (e.g. @~/.buildr@) and require them from your
+@buildfile@
+* Put them directly in the project, typically under the @tasks@ directory.
+* Put them in a shared code repository, and link to them from your project's @tasks@ directory
+* As Ruby gems and specify which gems are used in the settings file
 
+You can also get creative and devise your own way to distribute extensions.  
+"Sake":http://errtheblog.com/post/6069 is a good example of such initiative that lets you deploy Rake tasks on a system-wide basis.
 
 h2(#extensions).  Creating Extensions
 
@@ -61,23 +64,19 @@ The basic mechanism for extending projects in Buildr are Ruby modules.  In fact,
   
 A module defines instance methods that are then mixed into the project and become instance methods of the project.  There are two general ways for extending projects.  You can extend all projects by including the module in Project:
 
-<notextile>
 {% highlight ruby %}
 class Project
   include MyExtension
 end
 {% endhighlight %}
-</notextile>
 
 You can also extend a given project instance and only that instance by extending it with the module:
 
-<notextile>
 {% highlight ruby %}
 define 'foo' do
   extend MyExtension
 end
 {% endhighlight %}
-</notextile>
 
 Some extensions require tighter integration with the project, specifically for setting up tasks and properties, or for configuring tasks based on the project definition.  You can do that by adding callbacks to the process.
 
@@ -90,7 +89,6 @@ The easiest way to add callbacks is by incorporating the Extension module in you
 
 This example illustrates how to write a simple extension:
 
-<notextile>
 {% highlight ruby %}
 module LinesOfCode
   include Extension
@@ -127,8 +125,8 @@ class Buildr::Project
   include LinesOfCode
 end
 {% endhighlight %}
-</notextile>
 
+You may find interesting that this Extension API is used pervasively inside Buildr itself.  Many of the standard tasks such as @compile@, @test@, @package@  are extensions to a very small core.
 
 h2(#layouts).  Using Alternative Layouts
 
@@ -136,32 +134,26 @@ Buildr follows a common convention for project layouts: Java source files appear
 
 The default layout is available in @Layout.default@, and all projects inherit it.  You can set @Layout.default@ to your own layout, or define a project with a given layout (recommended) by setting the @:layout@ property.  Projects inherit the layout from their parent projects.  For example:
 
-<notextile>
 {% highlight ruby %}
 define 'foo', :layout=>my_layout do
   ...
 end
 {% endhighlight %}
-</notextile>
 
 A layout is an object that implements the @expand@ method.  The easiest way to define a custom layout is to create a new @Layout@ object and specify mapping between names used by Buildr and actual paths within the project.  For example:
 
-<notextile>
 {% highlight ruby %}
 my_layout = Layout.new
 my_layout[:source, :main, :java] = 'java'
 my_layout[:source, :main, :resources] = 'resources'
 {% endhighlight %}
-</notextile>
 
 Partial expansion also works, so you can specify the above layout using:
 
-<notextile>
 {% highlight ruby %}
 my_layout = Layout.new
 my_layout[:source, :main] = ''
 {% endhighlight %}
-</notextile>
 
 If you need anything more complex, you can always subclass @Layout@ and add special handling in the @expand@ method, you'll find one such example in the API documentation.
 
@@ -177,7 +169,6 @@ The built-in tasks expand lists of symbols into relative paths, using the follow
 
 All tasks are encouraged to use the same convention, and whenever possible, we recommend using the project's @path_to@ method to expand a list of symbols into a path, or use the appropriate path when available.  For example:
 
-<notextile>
 {% highlight ruby %}
 define 'bad' do
   # This may not be the real target.
@@ -193,4 +184,3 @@ define 'good' do
   package(:jar).include path_to(:source, :main, :etc, '*')
 end
 {% endhighlight %}
-</notextile>

data/doc/index.textile

@@ -1,13 +1,34 @@
 ---
 layout: default
-title: Welcome
+title: Apache Buildr
 ---
 
-h2(#what_is_apache_buildr).  What is Apache Buildr?
-
 Apache Buildr is a build system for Java-based applications, including support for Scala, Groovy and a growing number of JVM languages and tools.  We wanted something that's simple and intuitive to use, so we only need to tell it what to do, and it takes care of the rest.  But also something we can easily extend for those one-off tasks, with a language that's a joy to use.  And of course, we wanted it to be fast, reliable and have outstanding dependency management.
 
-Here's what we got:
+
+h2(#why).  Why Buildr Rocks
+
+"Daniel Spiewak":http://www.codecommit.com/blog:
+
+bq. If you think about it, the question isn’t “Why use Buildr?”, it’s really “Why use anything else?” The advantages afforded by Buildr are so substantial, I really can’t see myself going with any other tool, at least not when I have a choice.
+
+"Tristan Juricek":http://tristanhunt.com/:
+
+bq. That’s still the strongest sell: it builds everything I need, and as I’ve needed more, I just got things working without a lot of fuss.
+
+"Matthieu Riou":http://offthelip.org/:
+
+bq. We used to rely on Ant, with a fairly extensive set of scripts. It worked but was expensive to maintain. The biggest mistake afterward was to migrate to Maven2. I could write pages of rants explaining all the problems we ran into and we still ended up with thousands of lines of XML.
+
+"Martin Grotzke":http://www.javakaffee.de/blog/:
+
+bq. The positive side effect for me as a java user is that I learn a little ruby, and that’s easy but lots of fun… :-)
+
+"Ijonas Kisselbach":http://twitter.com/ijonas/statuses/4134103928:
+
+bq. I've cleaned up & migrated the Vamosa build process from 768 lines of Ant build.xml to 28 lines of Buildr.
+
+h2(#what).  What You Get
 
 * A simple way to specify projects, and build large projects out of smaller sub-projects.
 * Pre-canned tasks that require the least amount of configuration, keeping the build script DRY and simple.
@@ -20,28 +41,29 @@ Here's what we got:
 * 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).  Project News
+h2(#news).  What's New
 
-New in Buildr 1.3.4:
+New in Buildr 1.3.5:
 
-* We graduated from the Apache Incubator!  This is our first release as a top-level Apache project: http://buildr.apache.org.  New site, new mailing lists, SVN, Git, etc.
-* Support for Git version control system
-* Improved all-around Scala support, including joint Java-Scala compilation and upgraded to Scala 2.7.3 dependencies: ScalaSpecs 1.4.3, ScalaCheck 1.5 and ScalaTest 0.9.5
-* New 'artifacts:sources' task to download source code for artifact jars
-* Source code attachments for external dependencies in Eclipse and IDEA projects
-* Dependency upgrades such as Rake 0.8.4, Net-SSH 2.0.11, RSpec 1.2.2, JRuby 1.1.6.
-* Documentation now uses "Jekyll":http://github.com/mojombo/jekyll/ to generate web site and PDF document.  This replaces Docter so less code to
-maintain and the same Textile/Liquid mechanism as when using Github pages.
-* And 20 or so bug fixes.
+* Interactive shell (REPL) support, including BeanShell for Java projects
+* Scala libraries are automatically downloaded if not availabe locally
+* New 'cobertura:check' allows you to check for code coverage levels in your projects
+* Eclipse task is configurable to support various types of natures, builders, etc.
+* Dependency upgrades such as Net-SSH 2.0.15, JRuby 1.3.1, Rake 0.8.7, RSpec 1.2.8, easyb 0.9, TestNG 5.10
+* And 15+ bug fixes.
 
 See the "CHANGELOG":CHANGELOG for full details.
 
 
-h2(#legal).  Legal Notices
+h2(#notices).  Credits & Notices
+
+!http://www.apache.org/images/asf-logo.gif(A project of the Apache Software Foundation)!:http://www.apache.org
 
 The Apache Software Foundation is a non-profit organization, consider "sponsoring":http://www.apache.org/foundation/sponsorship.html and check the "thanks":http://www.apache.org/foundation/thanks.html page.
 
 "ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html, copyright of Ken Saunders.  "DejaVu fonts":http://dejavu.sourceforge.net, copyright of Bitstream, Inc.
+
+Community member quotes from a thread on "Stack Overflow":http://stackoverflow.com/questions/1015525/why-use-buildr-instead-of-ant-or-maven/1055864.