buildr 1.3.5-x86-mswin32

data/doc/css/default.css

@@ -0,0 +1,236 @@
+/* Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with this
+ * work for additional information regarding copyright ownership.  The ASF
+ * licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+
+body {
+  background-color: #fff;
+  color: #000;
+  font-family: "Helvetica Neue", "DejaVu Sans", "Verdana";
+  text-align: center;
+  line-height: 150%;
+}
+
+a:link, a:visited{
+  color: #0044b3;
+  text-decoration: none;
+}
+
+a:hover{
+  text-decoration: underline;
+}
+
+img {
+  border: none;
+}
+
+pre, code {
+  font-family: "Monaco", "DejaVu Sans Mono", "Courier New", "Courier";
+  font-size: 11pt;
+}
+pre {
+  margin: 0.3em 0 0.3em 0.9em;
+  padding: 0;
+  line-height: 1.8em;
+  white-space: pre-wrap;       /* css-3 */
+  white-space: -moz-pre-wrap !important;  /* Mozilla, since 1999 */
+}
+pre br { display: none; }
+
+h1, h2, h3 {
+  font-family: "Gill Sans";
+  padding: 0;
+  margin: 1.6em 0 0.6em -0.9em;
+  line-height: 1.25em;
+  letter-spacing: 0.03em;
+}
+
+h1 {
+  font-size: 2em;
+  margin-top: 0;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid #808080;
+}
+
+h2 {
+  font-size: 1.3em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid #a0a0a0;
+}
+
+h3 {
+  font-size: 1.1em;
+}
+
+blockquote {
+  padding-left: 2em;
+  padding-right: 2em;
+  margin-left: 0.3em;
+  margin-right: 0;
+  font-style: italic;
+}
+
+ul { 
+  list-style-type: disc;
+}
+
+ul ul {
+  list-style-type: disc;
+  padding-left: 1em;
+}
+
+table {
+  border-spacing: 0;
+  width: 100%;
+  margin: 0.3em 0 0.3em 0;
+}
+
+th, td {
+  padding: 0.3em 0.5em 0.3em 0.5em;
+  border-bottom: 1px solid #D8D8D8;
+  vertical-align: top;
+  background-color: #FFFFFF;
+}
+
+th, thead td {
+  border-bottom: none;
+  background-color: #669966;
+  color: #ffffff;
+  text-align: left;
+}
+
+
+#wrap{
+  margin: 1em auto 2em auto;
+  text-align: left;
+  width: 65em;
+}
+
+
+#header {
+  margin: 0 0 3em 18em;
+  position: relative;
+}
+
+#header .tagline {
+  float: right;
+  font-size: 1.2em;
+  font-weight: bold;
+  position: absolute;
+  top: 0.6em;
+  right: 0;
+}
+
+
+#pages { /* Parent Wrapper for inside boxes */
+/*  display: inline; */ /* IE Hack */
+  width: 12em;
+  float: left;
+  text-align: left;
+  margin-right: 2em;
+  font-family: "Gill Sans";
+  font-size: 11pt;
+  text-align: right;
+  border-right: 1px solid #ccc;
+  padding-right: 2em;
+}
+#pages ol {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+#pages ol li {
+  padding: 0.3em 0 0.6em 0em;
+  color: #669966;
+  font-weight: bold; 
+}
+#pages ol li ol {
+  margin-top: 0.3em;
+  padding: 0.3em 0 0.9em 0.9em;
+}
+#pages ol li ol li {
+  padding: 0.3em 0 0.3em 0em;
+}
+#pages ol li a  {
+  font-weight: normal;
+}
+#pages form {
+  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 */
+/*  display: inline; *//* IE Hack */
+  float: right;
+  width: 44em;
+  margin-left: 0.3em;
+  margin-bottom: 5em;
+}
+
+ol.toc {
+  list-style: none;
+  padding: 0;
+  margin: 0 0 2em 0;
+}
+ol.toc li {
+  padding: 0.3em 0 0.3em 0;
+  margin: 0;
+}
+ol.toc li ol.toc {
+  margin: 0;
+  padding-left: 0.9em;
+}
+
+
+#content p.tip, #content p.note {
+  margin: 0.9em 0 0 0;
+  padding: 0 0 2em 4em;
+}
+#content p.tip { background: url("../images/tip.png") 0 0 no-repeat; }
+#content p.note { background: url("../images/note.png") 0 0 no-repeat; }
+ 
+#content .footnote {
+  margin-top: 2.5em;
+}
+#content .footnote {
+  padding-top: 1.5em;
+  border-top: 1px solid #ccc;
+}
+#content .footnote + .footnote {
+  margin-top: 0.5em;
+  padding-top: 0;
+  border: none;
+}
+#content .footnote sup { font-weight: bold; }
+
+#content .footnote-links dt { font-weight: bold; }
+#content .footnote-links dt:after { content: ": " }
+#content .footnote-links dd { }
+
+
+#footer {
+  color: #888;
+  border-top: 1px solid #ccc;
+  font-size: 0.9em;
+  padding: 0.3em;
+  margin: 2em 0 3em 0em;
+  clear: both;
+}

data/doc/css/print.css

@@ -0,0 +1,101 @@
+/* Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with this
+ * work for additional information regarding copyright ownership.  The ASF
+ * licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+
+@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); }
+  }
+
+  title { string-set: doctitle content(); }
+
+  body {
+    font-family: "Palatino";
+    margin: 0;
+    color: black;
+    background: white;
+    font-size: 11pt;
+  }
+
+  h1 {
+    string-set: pagetitle content();
+    page-break-before: always;
+  }
+  h1:first-child { page-break-before: avoid; }
+  h1, h2, h3 {
+    font-family: "Gill Sans";
+  }
+  pre, p, blockquote { page-break-inside: avoid; }
+  pre, code {
+    font-family: "Monaco", "DejaVu Sans Mono", "Courier New", "Courier";
+    font-size: 9pt;
+  }
+  pre br {
+    display: none;
+  }
+  a:link, a:visited {
+    background: transparent;
+    text-decoration: none;
+  }
+  
+
+  #header, #pages, #footer { display: none }
+  #wrap, #content {
+    float: none !important;
+    color: black;
+    background: transparent;
+    width: auto !important;
+    margin: 0;
+    padding: 0;
+    border: 0;
+  }
+
+  ol.toc a:link, ol.toc a:visited { text-decoration: none; }
+  ol.toc a:after { content: leader('.') target-counter(attr(href), page); }
+
+  .title {
+    page-break-before: always;
+    border: none;
+  }
+  .title img {
+    display: block;
+    width: 80%;
+    margin: 2em auto 4em auto;
+  }
+  p.preface {
+    page-break-before: always;
+    padding-top: 1.5in;
+  }
+  div.preface.quotes {
+    page-break-before: always;
+    padding-top: 1in;
+  }
+
+}

data/doc/css/syntax.css

@@ -0,0 +1,23 @@
+/* Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with this
+ * work for additional information regarding copyright ownership.  The ASF
+ * licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+.highlight .k, .highlight .kp { color: blue } /* keyword */
+.highlight .no { color: darkblue } /* constant */
+.highlight .s1 { color: green } /* string */
+.highlight .n { color: black } /* identifier */
+.highlight .o, .highlight .p { color: darkblue } /* = + */
+.highlight .ss { color: darkblue } /* symbol */
+.highlight .c1 { color: gray } /* comment */

data/doc/download.textile

@@ -0,0 +1,79 @@
+---
+layout: default
+title: Download
+---
+
+
+h2(#install).  Installing Buildr
+
+*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
+
+The official Apache distribution consists of the digitally signed binaries (gems) and source packages "available below":#dist.  To install these binaries, you must first download them to disk and then install them using the @gem install@ command (or @rake install@ for a source distribution).
+
+In addition, contributors to this project maintain a separate distribution over on "RubyForge":http://rubyforge.org/projects/buildr.  Using this distribution, you're able to install Buildr directly from the remote gem repository and to automatically upgrade when a new release comes out.  The RubyForge distribution is *not* an official Apache distribution.
+
+The source code is included in both source and binary distribution, the Gem distribution expands the source code into your local Gem repository. That's in addition to getting the source code directly from "SVN":http://svn.apache.org/repos/asf/buildr or "GitHub":http://github.com/buildr/buildr/tree/master. Learn more about working with source code and "living on the edge":contributing.html#edge.
+
+
+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 |
+
+p>. ("Release signing keys":http://www.apache.org/dist/buildr/1.3.4/KEYS)
+
+
+h3. buildr 1.3.3-incubating (2008-10-08)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.3-incubating.gem":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.gem | "7192dad45441630cbf07b85af5f9069a":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.gem.asc |
+| "buildr-1.3.3-java-incubating.gem":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-java-incubating.gem | "71ad4f0f8bfa951fa129db67a06b608a":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-java-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-java-incubating.gem.asc |
+| "buildr-1.3.3-incubating.tgz":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.tgz | "e5ee6fe5b86386520c91a9633d02814b":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.tgz.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.tgz.asc |
+| "buildr-1.3.3-incubating.zip":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.zip | "baab601fd46a877ee8e408891d68c842":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.zip.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.3-incubating/buildr-1.3.3-incubating.zip.asc |
+
+p>. ("Release signing keys":http://archive.apache.org/dist/buildr/1.3.3-incubating/KEYS)
+
+
+h3. buildr 1.3.2-incubating (2008-07-18)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.2-incubating.gem":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem | "225504bc195334c4eb9d6dec814d9db1":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem.asc |
+| "buildr-1.3.2-java-incubating.gem":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem | "d7d8394c7aed887987be0e813e1e4cee":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem.asc |
+| "buildr-1.3.2-incubating.tgz":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz | "611e97df1bc76382ecbe6b60e9340f2b":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz.asc |
+| "buildr-1.3.2-incubating.zip":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip | "d65d20005f603338c0aedd4f17d0bc90":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip.asc |
+
+p>. ("Release signing keys":http://archive.apache.org/dist/buildr/1.3.2-incubating/KEYS)
+
+
+
+h3. buildr 1.3.1-incubating (2008-05-19)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.1-incubating.gem":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.gem | "476436429b9a6c4ed178009ba17dd724":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.gem.asc |
+| "buildr-1.3.1-java-incubating.gem":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-java-incubating.gem | "7af37acc10621b18d4b870119c36d998":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-java-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-java-incubating.gem.asc |
+| "buildr-1.3.1-incubating.tgz":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.tgz | "ad6694416fc2e6eb22ab1042dcc41411":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.tgz.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.tgz.asc |
+| "buildr-1.3.1-incubating.zip":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.zip | "0470349978b93e645ca2e9607e304ed1":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.zip.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.1-incubating/buildr-1.3.1-incubating.zip.asc |
+
+p>. ("Release signing keys":http://archive.apache.org/dist/buildr/1.3.1-incubating/KEYS)
+
+
+h3. buildr 1.3.0-incubating (2008-05-01)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.0-incubating.gem":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.gem | "37758d0a8dabc570799b0a58d23d19f0":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.gem.asc |
+| "buildr-1.3.0-java-incubating.gem":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-java-incubating.gem | "6a3a86740077f739c111514e0e2b9e06":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-java-incubating.gem.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-java-incubating.gem.asc |
+| "buildr-1.3.0-incubating.tgz":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.tgz | "acd84ad8c5031962e65b0036f3bc2e76":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.tgz.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.tgz.asc |
+| "buildr-1.3.0-incubating.zip":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.zip | "d85945f05efd0e512e6d769e3dd1cc98":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.zip.md5 | "Sig":http://archive.apache.org/dist/buildr/1.3.0-incubating/buildr-1.3.0-incubating.zip.asc |
+
+p>. ("Release signing keys":http://archive.apache.org/dist/buildr/1.3.0-incubating/KEYS)
+
+
+p(note). When downloading from files please check the "md5sum":http://www.apache.org/dev/release-signing#md5 and verify the "OpenPGP":http://www.apache.org/dev/release-signing#openpgp compatible signature from the main Apache site. This "KEYS":http://archive.apache.org/dist/buildr/KEYS file contains the public keys used for signing releases. It is recommended that (when possible) a web of trust is used to confirm the identity of these keys. For more information, please see the "Apache Release FAQ":http://www.apache.org/dev/release.html.

data/doc/extending.textile

@@ -0,0 +1,186 @@
+---
+layout: default
+title: Extending Buildr
+---
+
+h2(#tasks). Organizing Tasks
+
+A couple of things we learned while working on Buildr.  Being able to write your own Rake tasks is a very powerful feature.  But if you find yourself doing the same thing over and over, you might also want to consider functions. They give you a lot more power and easy abstractions.
+
+For example, we use OpenJPA in several projects.  It's a very short task, but each time I have to go back to the OpenJPA documentation to figure out how to set the Ant MappingTool task, tell Ant how to define it.  After the second time, you're recognizing a pattern and it's just easier to write a function that does all that for you.
+
+Compare this:
+
+{% highlight ruby %}
+file('derby.sql') do
+  REQUIRES = [
+    'org.apache.openjpa:openjpa-all:jar:0.9.7-incubating',
+    'commons-collections:commons-collections:jar:3.1',
+    . . . 
+    'net.sourceforge.serp:serp:jar:1.11.0' ]
+  ant('openjpa') do |ant|
+    ant.taskdef :name=>'mapping',
+      :classname=>'org.apache.openjpa.jdbc.ant.MappingToolTask',
+      :classpath=>REQUIRES.join(File::PATH_SEPARATOR)
+    ant.mapping :schemaAction=>'build', :sqlFile=>task.name,
+      :ignoreErrors=>true do
+        ant.config :propertiesFile=>_('src/main/sql/derby.xml')
+        ant.classpath :path=>projects('store', 'utils' ).
+          flatten.map(&:to_s).join(File::PATH_SEPARATOR)
+    end
+  end
+end
+{% endhighlight %}
+
+To this:
+
+{% highlight ruby %}
+file('derby.sql') do
+  mapping_tool :action=>'build', :sql=>task.name,
+    :properties=>_('src/main/sql/derby.xml'),
+    :classpath=>projects('store', 'utils')
+end
+{% endhighlight %}
+
+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, 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.
+
+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
+
+The basic mechanism for extending projects in Buildr are Ruby modules.  In fact, base features like compiling and testing are all developed in the form of modules, and then added to the core Project class.
+  
+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:
+
+{% highlight ruby %}
+class Project
+  include MyExtension
+end
+{% endhighlight %}
+
+You can also extend a given project instance and only that instance by extending it with the module:
+
+{% highlight ruby %}
+define 'foo' do
+  extend MyExtension
+end
+{% endhighlight %}
+
+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.
+
+The easiest way to add callbacks is by incorporating the Extension module in your own extension, and using the various class methods to define callback behavior.
+
+|_. Method        |_. Usage |
+| @first_time@    | This block will be called once for any particular extension.  You can use this to setup top-level and local tasks. |
+| @before_define@ | This block is called once for the project with the project instance, right before running the project definition.  You can use this to add tasks and set properties that will be used in the project definition. |
+| @after_define@  | This block is called once for the project with the project instance, right after running the project definition.  You can use this to do any post-processing that depends on the project definition. |
+
+This example illustrates how to write a simple extension:
+
+{% highlight ruby %}
+module LinesOfCode
+  include Extension
+
+  first_time do
+    # Define task not specific to any projet.
+    desc 'Count lines of code in current project'
+    Project.local_task('loc')
+  end
+
+  before_define do |project|
+    # Define the loc task for this particular project.
+    define_task 'loc' do |task|
+      lines = task.prerequisites.map { |path| Dir["#{path}/**/*"] }.flatten.uniq.
+        inject(0) { |total, file| total + File.readlines(file).count }
+      puts "Project #{project.name} has #{lines} lines of code"
+    end
+  end
+
+  after_define do |project|
+    # Now that we know all the source directories, add them.
+    task('loc'=>compile.sources + compile.test.sources)
+  end
+
+  # To use this method in your project:
+  #   loc path_1, path_2
+  def loc(*paths)
+    task('loc'=>paths)
+  end
+
+end
+
+class Buildr::Project
+  include LinesOfCode
+end
+{% endhighlight %}
+
+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
+
+Buildr follows a common convention for project layouts: Java source files appear in @src/main/java@ and compile to @target/classes@, resources are copied over from @src/main/resources@ and so forth.  Not all projects follow this convention, so it's now possible to specify an alternative project layout.
+
+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:
+
+{% highlight ruby %}
+define 'foo', :layout=>my_layout do
+  ...
+end
+{% endhighlight %}
+
+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:
+
+{% highlight ruby %}
+my_layout = Layout.new
+my_layout[:source, :main, :java] = 'java'
+my_layout[:source, :main, :resources] = 'resources'
+{% endhighlight %}
+
+Partial expansion also works, so you can specify the above layout using:
+
+{% highlight ruby %}
+my_layout = Layout.new
+my_layout[:source, :main] = ''
+{% endhighlight %}
+
+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.
+
+The built-in tasks expand lists of symbols into relative paths, using the following convention:
+
+|_. Path                          |_. Expands to |
+| @:source, :main, <lang/usage>@  |  Directory containing source files for a given language or usage, for example, @:java@, @:resources@, @:webapp@. |
+| @:source, :test, <lang/usage>@  | Directory containing test files for a given language or usage, for example, @:java@, @:resources@. |
+| @:target, :generated@           | Target directory for generated code (typically source code). |
+| @:target, :main, <lang/usage>@  | Target directory for compiled code, for example, @:classes@, @:resources@. |
+| @:target, :test, <lang/usage>@  | Target directory for compile test cases, for example, @:classes@, @:resources@. |
+| @:reports, <framework/usage>@   | Target directory for generated reports, for example, @:junit@, @:coverage@. |
+
+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:
+
+{% highlight ruby %}
+define 'bad' do
+  # This may not be the real target.
+  puts 'Compiling to ' + path_to('target/classes')
+  # This will break with different layouts.
+  package(:jar).include 'src/main/etc/*'
+end
+
+define 'good' do
+  # This is always the compiler's target.
+  puts 'Compiling to ' + compile.target.to_s
+  # This will work with different layouts.
+  package(:jar).include path_to(:source, :main, :etc, '*')
+end
+{% endhighlight %}