buildr 1.3.3-java → 1.3.4-java

data/doc/{pages/building.textile → building.textile}

@@ -1,4 +1,8 @@
-h1. Building
+---
+layout: default
+title: Building
+---
+
 
 To remove any confusion, Buildr's build task is actually called @build@.  It's also the default task that executes when you run @buildr@ without any task name.
 
@@ -7,7 +11,7 @@ The @build@ task runs two other tasks: @compile@ and its associated tasks (that
 Why @build@ and not @compile@?  Some projects do more than just compiling. Other projects don't compile at all, but perform other build tasks, for example, creating a database schema or command line scripts.  So we want you to get in the practice of running the @build@ task, and help you by making it the default task.
 
 
-h2. Compiling
+h2(#compiling). Compiling
 
 Each project has its own @compile@ task you can invoke directly, by running @buildr compile@ or as part of another build task.  (Yes, that @build@).
 
@@ -21,35 +25,41 @@ Buildr uses file tasks to handle dependencies, but here we're talking about the
 
 An easier way to specify dependencies is by calling the @compile.with@ method. It takes a list of arguments and adds them to the dependency list.  The @compile.with@ method is easier to use, it accepts several type of dependencies.  You can use file names, file tasks, projects, artifacts specifications and even pass arrays of dependencies.
 
-Most dependencies fall into the last three categories.  When you pass a project to @compile.with@, it picks up all the packages created by that project.  In doing so, it establishes an order of dependency between the two projects (see "Defining the Project":projects.html#defining_the_project).  For example, if you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect that change, recompile and package _teh-api_ before compiling _teh-impl_.  You can also select a specific package using the @package@ or @packages@ methods (see "Packaging":packaging.html).
+Most dependencies fall into the last three categories.  When you pass a project to @compile.with@, it picks up all the packages created by that project.  In doing so, it establishes an order of dependency between the two projects (see "Defining the Project":projects.html#defining).  For example, if you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect that change, recompile and package _teh-api_ before compiling _teh-impl_.  You can also select a specific package using the @package@ or @packages@ methods (see "Packaging":packaging.html).
 
 When you pass an artifact specification to @compile.with@, it creates an @Artifact@ task that will download that artifact from one of the remote repositories, install it in the local repository, and use it in your project. Rake's dependency mechanism is used here to make sure the artifact is downloaded once, when needed.  Check the "Artifacts":artifacts.html section for more information about artifact specification and repositories.
 
 For now let's just show a simple example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile.with 'org.apache.axis2:axis2:jar:1.2',
   'org.apache.derby:derby:jar:10.1.2.1', projects('teh-api', 'teh-impl')
-}}}
+{% endhighlight %}
+</notextile>
 
-Passing arrays to @compile.with@ is just a convenient for handling multiple dependencies, we'll show more examples of that when we talk about "Artifacts":#artifacts.
+Passing arrays to @compile.with@ is just a convenient for handling multiple dependencies, we'll show more examples of that when we talk about "Artifacts":artifacts.html.
 
 Likewise, the @compile@ task has an array of file tasks that point at the source directories you want to compile from.  You can access that array by calling @compile.sources@.  You can use @compile.from@ to add new source directories by passing a file name or a file task.
 
 For example, let's run the APT tool on our annotated source code before compiling it:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile.from apt
-}}}
+{% endhighlight %}
+</notextile>
 
 When you call @apt@ on a project, it returns a file task that points to the @target/generated/apt@ directory.  This file task executes by running APT, using the same list of source directories, dependencies and compiler options. It then generates new source files in the target directory.  Calling @compile.from@ with that file task includes those additional source files in the list of compiled sources.
 
 Here's another example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 jjtree = jjtree(_('src/main/jjtree'), :in_package=>'com.acme')
 compile.from javacc(jjtree, :in_package=>'com.acme'), jjtree
-}}}
+{% endhighlight %}
+</notextile>
 
 This time, the variable @jjtree@ is a file task that reads a JJTree source file from the @src/main/jjtree@ directory, and generates additional source files in the @target/generated/jjtree@ directory.  The second line creates another file task that takes those source files, runs JavaCC on them, and generates yet more source files in @target/generated/javacc@.  Finally, we include both sets of source files in addition to those already in @src/main/java@, and compile the lot.
 
@@ -61,10 +71,12 @@ We use method pairs to give you finer control over the compiler, but also a way
 
 For example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile.from('srcs').with('org.apache.axis2:axis2:jar:1.2').
   into('classes').using(:target=>'1.4')
-}}}
+{% endhighlight %}
+</notextile>
 
 Buildr uses the method pair and method chaining idiom in many places to make your life easier without sacrificing flexibility.
 
@@ -72,22 +84,28 @@ Occasionally, you'll need to post-process the generated bytecode.  Since you onl
 
 For example, to run the OpenJPA bytecode enhancer after compiling the source files:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile { open_jpa_enhance }
-}}}
+{% endhighlight %}
+</notextile>
 
 You can change various compile options by calling, you guessed, @compile.options@.  For example, to set the compiler to VM compatibility with Java 1.5 and turn on all Lint messages:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile.options.target = '1.5'
 compile.options.lint = 'all'
-}}}
+{% endhighlight %}
+</notextile>
 
 Or, if you want to chain methods together:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 compile.using :target=>'1.5', :lint=>'all'
-}}}
+{% endhighlight %}
+</notextile>
 
 
 Sub-projects inherit compile options from their parent project, so you only need to change these settings once in the top project.  You can do so, even if the top project itself doesn't compile anything.
@@ -96,33 +114,38 @@ The options available to you depend on which compiler you are using for this par
 
 Buildr turns the @warning@ option on by default, but turns it off when you run @buildr --silent@.  It also sets the @debug@ option on, but turns it off when making a release.  You can also control the @debug@ option from the command line, for example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 # When calling buildr
 $ buildr compile debug=off
 
 # Once until we change the variable
 $ export DEBUG=off
 $ buildr compile
-}}}
+{% endhighlight %}
+</notextile>
 
 The default source and target directories, compiler settings and other options you can use depend on the specific language.  You can find more information in the "Languages":languages.html section.
 
 
-h2. Resources
+h2(#resources). Resources
 
 
 The @compile@ task comes bundled with a @resources@ task.  It copies files from the @src/main/resources@ directory into @target/resources@.  Best used for copying files that you want to included in the generated code, like configuration files, i18n messages, images, etc.
 
 The @resources@ task uses a filter that can change files as it copies them from source to destination.  The most common use is by mapping values using a hash. For example, to substitute "${version}" for the project's version number and "${copyright}" for "Acme Inc (C) 2007" :
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 resources.filter.using 'version'=>version,
   'copyright'=>'Acme Inc (C) 2007'
-}}}
+{% endhighlight %}
+</notextile>
 
 You can also use "profiles":settings_profiles.html#profiles to supply a name/value map that all @resources@ task should default to, by adding a @filter@ element to each of the profiles.  The following examples shows a @profiles.yaml@ file that applies the same filter in development and test environments:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 filter: &alpha1
   version: experimental
   copyright: Acme Inc (C) 2007
@@ -131,42 +154,51 @@ development:
   filter: *alpha1
 test:
   filter: *alpha1
-}}}
+{% endhighlight %}
+</notextile>
 
 You can specify a different format by passing it as the first argument. Supported formats include:
 
 |_. Format  |_. Usage |
-| @:ant@    | Map from <code>@key@</code> to value. |
+| @:ant@    | Map from @key@ to value. |
 | @:maven@  | Map from @${key}@ to value (default). |
 | @:ruby@   | Map from @#{key}@ to value. |
 | @Regexp@  | Map using the matched value of the regular expression (e.g. @/=(.*?)=/@). |
 
 For example, using the @:ruby@ format instead of the default @:maven@ format:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 resources.filter.using :ruby, 'version'=>version,
   'copyright'=>'Acme Inc (C) 2007'
-}}}
+{% endhighlight %}
+</notextile>
 
 For more complicated mapping you can also pass a method or a proc.  The filter will call it once for each file with the file name and content.
 
 If you need to copy resource files from other directories, add these source directories by calling the @from@ method, for example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 resources.from _('src/etc')
-}}}
+{% endhighlight %}
+</notextile>
 
 You can select to copy only specific files using common file matching patterns. For example, to include only HTML files:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 resources.include '*.html'
-}}}
+{% endhighlight %}
+</notextile>
 
 To include all files, except for files in the @scratch@ directory:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 resources.exclude 'scratch/*'
-}}}
+{% endhighlight %}
+</notextile>
 
 The filter always excludes the @CVS@ and @.svn@ directories, and all files ending with @.bak@ or @~@, so no need to worry about these.
 
@@ -176,15 +208,17 @@ You can use filters elsewhere.  The @filter@ method creates a filter, the @into@
 
 For example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 filter('src/specs').into('target/specs').
   using('version'=>version, 'created'=>Time.now).run
-}}}
+{% endhighlight %}
+</notextile>
 
 The @resources@ task is, in fact, just a wrapper around such a filter that automatically adds the @src/main/resources@ directory as one of the source directories.
 
 
-h2. More On Building
+h2(#more). More On Building
 
 The @build@ task runs the @compile@ (and @resources@) tasks as prerequisites, followed by any actions you add to it, and completes by running the @test@ task.  The @build@ task itself is a prerequisite to other tasks, for example, @package@ and @upload@.
 
@@ -192,38 +226,44 @@ You can extend the @build@ task in two ways.  You can add more prerequisites tha
 
 Let's look at a simple example.  Say we want to generate a Derby database from an SQL file and include it in the ZIP package:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
 package(:zip).include db
-}}}
+{% endhighlight %}
+</notextile>
 
 There's nothing fundamentally wrong with this code, if that's what you intend to do.  But in practice, you don't always run the @package@ task during development, so you won't notice if something is wrong with this task when you build.  For example, if it fails to generate the SQL file.  In addition, the @package@ task runs after @build@, so you can't use the database in your test cases.
 
 So let's refactor it.  We're going to use the variable @db@ to reference the file task that creates the database, and make it a prerequisite of the @build@ task.  And use that same variable again to include the database in the ZIP package:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
 build db
 package(:zip).include db
-}}}
+{% endhighlight %}
+</notextile>
 
 Much better.  We're using the same task twice, but since we're using Rake here, it will only execute once.  In fact, it will only execute if we don't already have a Derby database, or if it detects a change to the SQL file and needs to recreate the database.
 
-p(tip). @Derby.create@ is not part of Buildr, you can get "derby.rake":http://svn.apache.org/repos/asf/incubator/ode/trunk/tasks/derby.rake here.
+p(tip). @Derby.create@ is not part of Buildr, you can get "derby.rake":http://svn.apache.org/repos/asf/ode/trunk/tasks/derby.rake here.
 
 Here's another example.  We want to copy some files over as part of the build, and apply a filter to them.  This time, we're going to extend the @build@ task:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 build do
   filter('src/specs').into('target/specs').
     using('version'=>version, 'created'=>Time.now).run
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 The @build@ task is recursive, so running @buildr build@ picks the current project and runs its @build@ task, which in turn runs the @build@ task on each of its sub-projects.  One @build@ task to rule them all.
 
 
-h2. Cleaning
+h2(#cleaning). Cleaning
 
 The @build@ task has an evil twin, the @clean@ task.  It's the task you use to remove all the files created during the build, especially when you mess things up and want to start all over.
 
@@ -231,9 +271,11 @@ It basically erases the target directories, the one called @target@, and if you
 
 For example: 
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 clean { rm_rf _('staged') }
-}}}
+{% endhighlight %}
+</notextile>
 
 The @rm_rf@ method deletes the directory and all files in it.  It's named after UNIX's infamous @rm -rf@.  Use it wisely.  This is also a good time to introduce you to @FileUtils@, a standard Ruby library that contains convenient methods for creating and deleting directories, copying and moving files, even comparing two files.  They're all free of charge when you use Buildr.
 

data/doc/{pages/contributing.textile → contributing.textile}

@@ -1,20 +1,23 @@
-h1. Contributing
+---
+layout: default
+title: Contributing
+---
 
 Buildr is a community effort, and we welcome all contributors.  Here's your chance to get involved and help your fellow developers.
 
-h2.  Getting involved
+h2(#involved).  Getting involved
 
-All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs_aka_issues.
+All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs.
 
 
-h3.  Mailing Lists
+h2(#mailing_lists).  Mailing Lists
 
-We run two mailing lists, the "buildr-user":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/ mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the  "buildr-dev":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/ mailing list for talking about development of Buildr itself, and  "commits":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/ mailing list for following SVN commits and JIRA issues.
+We run two mailing lists, the "users":http://buildr.markmail.org/search/list:users mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the "dev":http://buildr.markmail.org/search/list:dev mailing list for talking about development of Buildr itself. There's also "commits":http://buildr.markmail.org/search/list:commits mailing list for following SVN commits and JIRA issues.
 
 Check the "mailing lists":mailing_lists.html page for more information on subscribing, searching and posting to the mailing list.
 
 
-h3.  Bugs (aka Issues)
+h2(#bugs).  Bugs (aka Issues)
 
 We really do try to keep bugs to a minimum, and anticipate everything you'll ever want to do with Buildr.  We're also, not perfect.  So you may have found a bug, or have an enhancement in mind, or better yet, a patch to contribute. Here's what you can do.
 
@@ -24,25 +27,27 @@ 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:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ ruby --version
 $ buildr --version
 $ java --version
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h3.  Community Wiki
+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.
 
 
-h3.  Contributing Code
+h2(#code).  Contributing Code
 
 Yes, please.
 
 If you have a patch to submit, do it through "JIRA":http://issues.apache.org/jira/browse/Buildr.  We want to make sure Apache gets the right to use your contribution, and the JIRA upload form includes a simple contribution agreement.  Lawyer not included.
 
-h4.  The Perfect Patch
+h3.  The Perfect Patch
 
 If you want to get your patch accepted quickly:
 
@@ -53,34 +58,36 @@ If you want to get your patch accepted quickly:
 
 If you don't know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that.  A spec is preferred to a fix.
 
-h4.  Working on a new feature?
+h3.  Working on a new feature?
 
 If you want to work on a cool new feature, but not quite ready to submit a patch, there's still a way you can get the Buildr community involved.  We're experimenting with using Git for that.  You can use Git to maintain a fork of Buildr that can keep up with changes in the main branch (tip: use @git rebase@), while developing your own changes/features on it.
 
-That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#Git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.
+That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.
 
 
-h2.  Living on the edge
+h2(#edge).  Living on the edge
 
 Did we mention Buildr is an open source project?  In fact, when you install Buildr you get all the source code, documentation, test case and everything you need to use it, extend it and patch it.  Have a look in your Gem directory.
 
-h3.  SVN
+h3(#svn).  SVN
 
-But if you want to work with the latest and greatest, you'll want to check out "Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr:
+But if you want to work with the latest and greatest, you'll want to check out "Buildr from SVN":http://svn.apache.org/repos/asf/buildr:
 
-{{{!sh
-$ svn co http://svn.apache.org/repos/asf/incubator/buildr/trunk buildr
-}}}
+{% highlight sh %}
+$ svn co http://svn.apache.org/repos/asf/buildr/trunk buildr
+{% endhighlight %}
 
-You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/incubator/buildr.
+You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/buildr.
 
-h3.  Git
+h3(#git).  Git
 
-Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from GitHub":http://github.com/vic/buildr/tree/master:
+Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from GitHub":http://github.com/buildr/buildr/tree/master:
 
-{{{!sh
-$ git clone git://github.com/vic/buildr.git
-}}}
+<notextile>
+{% highlight sh %}
+$ git clone git://github.com/buildr/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.
 
@@ -92,17 +99,17 @@ h3. Working with Source Code
 
 To install Buildr from the source directory:
 
-{{{!sh
+{% highlight sh %}
 $ cd buildr
 $ rake setup install
-}}}
+{% endhighlight %}
 
 When using Buildr for JRuby:
 
-{{{!sh
+{% highlight sh %}
 $ cd buildr
 $ jruby -S rake setup install
-}}}
+{% endhighlight %}
 
 The _setup_ task takes care of installing all the necessary dependencies used for building, testing and running Buildr. Once in a while we upgrade or add new dependencies, if you're experiencing a missing dependency, simply run @rake setup@ again.
 
@@ -115,21 +122,23 @@ h3. Using development build
 
 Occasionally we'll make development builds from the current code in trunk/head. We appreciate if you can take the time to test those out and report any bugs. To install development builds, use the Gem repository at @people.apache.org/~assaf/buildr/snapshot@:
 
-{{{!sh
+{% highlight sh %}
 gem source --add http://people.apache.org/~assaf/buildr/snapshot/
-}}}
+{% endhighlight %}
 
 Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr from a snapshot and want to upgrade to a newer snapshot or the latest official release, you need to use @gem install buildr@ rather than @gem upgrade@.
 
 If you want to go back to using the RubyForge releases:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 gem source --remove http://people.apache.org/~assaf/buildr/snapshot/
 gem install buildr
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2.  Tested and Documented
+h2(#testing).  Tested and Documented
 
 Two things we definitely encourage!
 
@@ -141,18 +150,18 @@ We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test fra
 
 You can run an individual specifications using the @spec@ command, for example:
 
-{{{!sh
+{% highlight sh %}
 $ spec spec/compiler_spec.rb
 $ spec spec/compiler_spec.rb -l 409
-}}}
+{% endhighlight %}
 
 The first command will run all the specifications in @compiler_spec@, the second command will run only the specification identified by line 409 of that file. You can use line numbers to point at a particular specification (lines starting with @it@), or set of specifications (lines starting with @describe@). You can also use the @-e@ command line option to name a particular specification.
 
 To make sure your change did not break anything else, you can run all the specifications (be patient, we have a lot of these):
 
-{{{!sh
+{% highlight sh %}
 $ rake spec
-}}}
+{% endhighlight %}
 
 If you get any failures, you can use @rake failed@ to run only the failed specs, and repeat until there are no more failed specs to run. The list of failed specs is stored in the file _failed_.
 
@@ -160,14 +169,14 @@ We always @rake spec@ before making a release.
 
 For full test coverage:
 
-{{{!sh
+{% highlight sh %}
 $ rake coverage
-}}}
+{% endhighlight %}
 
 Specification and coverage reports are HTML files you can view with a Web browser, look for them in the _reports_ directory. You can also check out the "RSpec report":specs.html and "test coverage":coverage/index.html we publish with each release.
 
 
-h3.  Documentation
+h2(#docs).  Documentation
 
 Yes, we do make typos, spelling errors and sometimes we write things that don't make sense, so if you find a documentation bug, or want to help make the documentation even better, here's the way to do it.
 
@@ -183,11 +192,10 @@ The tool we use for this is called Docter, which we developed specifically for B
 
 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.
 
-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@.
+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@.
 
 
-h2.  Contributors
+h2(#contributors).  Contributors
 
 Here is the list of people who are actively working and committing on Buildr:
 
@@ -205,4 +213,4 @@ 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.
+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.