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 2008/08/06 02:23:42 UTC
svn commit: r683061 [2/4] - /incubator/buildr/trunk/doc/pages/
Modified: incubator/buildr/trunk/doc/pages/getting_started.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/getting_started.textile?rev=683061&r1=683060&r2=683061&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/getting_started.textile (original)
+++ incubator/buildr/trunk/doc/pages/getting_started.textile Tue Aug 5 17:23:42 2008
@@ -2,26 +2,18 @@
h2. Installing Buildr
-The installation instructions are slightly different for each operating system.
-Pick the one that best matches your operating system and target platform.
+The installation instructions are slightly different for each operating system. Pick the one that best matches your operating system and target platform.
-The @gem install@ and @gem update@ commands install Buildr from a binary
-distribution provided through "RubyForge":http://rubyforge.org/projects/buildr.
-This distribution is maintained by contributors to this project, but is *not*
-an official Apache distribution. You can obtain the official Apache
-distribution files from the "download page":download.html.
+The @gem install@ and @gem update@ commands install Buildr from a binary distribution provided through "RubyForge":http://rubyforge.org/projects/buildr. This distribution is maintained by contributors to this project, but is *not* an official Apache distribution. You can obtain the official Apache distribution files from the "download page":download.html.
-The current release of Buildr for Ruby may not work well with Java 6, only
-Java 1.5 or earlier. If you need to use Java 6, consider "Buildr for JRuby":#jruby.
+The current release of Buildr for Ruby may not work well with Java 6, only Java 1.5 or earlier. If you need to use Java 6, consider "Buildr for JRuby":#jruby.
h3. Linux
-To get started you will need a recent version of Ruby, Ruby Gems and build
-tools for compiling native libraries (@make@, @gcc@ and standard headers).
+To get started you will need a recent version of Ruby, Ruby Gems and build tools for compiling native libraries (@make@, @gcc@ and standard headers).
-On *RedHat/Fedora* you can use yum to install Ruby and RubyGems, and then
-upgrade to the most recent version of RubyGems:
+On *RedHat/Fedora* you can use yum to install Ruby and RubyGems, and then upgrade to the most recent version of RubyGems:
{{{!sh
$ sudo yum install ruby rubygems ruby-devel gcc
@@ -34,8 +26,7 @@
$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential
}}}
-The Debian package for @rubygems@ will not allow you to install Buildr, so you
-need to install RubyGems from source:
+The Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
{{{!sh
$ wget http://rubyforge.org/frs/download.php/38646/rubygems-1.2.0.tgz
@@ -45,8 +36,7 @@
$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
}}}
-Before installing Buildr, please set the @JAVA_HOME@ environment variable to
-point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution. Next, use Ruby Gem to install Buildr:
{{{!sh
$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
@@ -59,19 +49,12 @@
$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.0
}}}
-You can also use this script "to install Buildr on
-Linux":scripts/install-linux.sh. This script will install Buildr or if already
-installed, upgrade to a more recent version. It will also install Ruby 1.8.6
-if not already installed (using @yum@ or @apt-get@) and upgrage RubyGems to
-1.0.1.
+You can also use this script "to install Buildr on Linux":scripts/install-linux.sh. This script will install Buildr or if already installed, upgrade to a more recent version. It will also install Ruby 1.8.6 if not already installed (using @yum@ or @apt-get@) and upgrage RubyGems to 1.0.1.
h3. OS/X
-OS/X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6. OS/X 10.4
-(Tiger) includes an older version of Ruby, we recommend you first install Ruby
-1.8.6 using MacPorts (@sudo port install ruby rb-rubygems@), Fink or the
-"Ruby One-Click Installer for OS/X":http://rubyosx.rubyforge.org/.
+OS/X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6. OS/X 10.4 (Tiger) includes an older version of Ruby, we recommend you first install Ruby 1.8.6 using MacPorts (@sudo port install ruby rb-rubygems@), Fink or the "Ruby One-Click Installer for OS/X":http://rubyosx.rubyforge.org/.
We recommend you first upgrade to the latest version of Ruby gems:
@@ -79,8 +62,7 @@
$ sudo gem update --system
}}}
-Before installing Buildr, please set the @JAVA_HOME@ environment variable to
-point to your JDK distribution:
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution:
{{{!sh
$ export JAVA_HOME=/Library/Java/Home
@@ -99,17 +81,12 @@
$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.0
}}}
-You can also use this script "to install Buildr on
-OS/X":scripts/install-osx.sh. This script will install Buildr or if already
-installed, upgrade to a more recent version. It will also install Ruby 1.8.6
-if not already installed (using MacPorts) and upgrage RubyGems to 1.0.1.
+You can also use this script "to install Buildr on OS/X":scripts/install-osx.sh. This script will install Buildr or if already installed, upgrade to a more recent version. It will also install Ruby 1.8.6 if not already installed (using MacPorts) and upgrage RubyGems to 1.0.1.
h3. Windows
-If you don't already have Ruby installed, now is the time to do it. The
-easiest way to install Ruby is using the "one-click
-installer":http://rubyinstaller.rubyforge.org/.
+If you don't already have Ruby installed, now is the time to do it. The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.
We recommend you first upgrade to the latest version of Ruby gems:
@@ -117,17 +94,13 @@
> gem update --system
}}}
-Before installing Buildr, please set the @JAVA_HOME@ environment variable to
-point to your JDK distribution. Next, use Ruby Gem to install Buildr:
+Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution. Next, use Ruby Gem to install Buildr:
{{{!sh
> gem install buildr
}}}
-Buildr uses several libraries that include native extensions. During
-installation it will ask you to pick a platform for these libraries. By
-selecting @mswin32@ it will download and install pre-compiled DLLs for these
-extensions.
+Buildr uses several libraries that include native extensions. During installation it will ask you to pick a platform for these libraries. By selecting @mswin32@ it will download and install pre-compiled DLLs for these extensions.
To upgrade to a new version or install a specific version:
@@ -139,11 +112,9 @@
h3. JRuby
-If you don't already have JRuby 1.1 or later installed, you can download it
-from the "JRuby site":http://dist.codehaus.org/jruby/.
+If you don't already have JRuby 1.1 or later installed, you can download it from the "JRuby site":http://dist.codehaus.org/jruby/.
-After uncompressing JRuby, update your @PATH@ to include both @java@ and @jruby@
-executables.
+After uncompressing JRuby, update your @PATH@ to include both @java@ and @jruby@ executables.
For Linux and OS/X:
@@ -166,29 +137,17 @@
$ jruby -S gem install buildr -v 1.3.0
}}}
-You can also use this script "to install Buildr on
-JRuby":scripts/install-jruby.sh. This script will install Buildr or if already
-installed, upgrade to a more recent version. If necessary, it will also
-install JRuby 1.1 in @/opt/jruby@ and update the @PATH@ variable in
-@~/.bash_profile@ or @~/.profile@.
+You can also use this script "to install Buildr on JRuby":scripts/install-jruby.sh. This script will install Buildr or if already installed, upgrade to a more recent version. If necessary, it will also install JRuby 1.1 in @/opt/jruby@ and update the @PATH@ variable in @~/.bash_profile@ or @~/.profile@.
*Important: Running JRuby and Ruby side by side*
-Ruby and JRuby maintain separate Gem repositories, and in fact install
-slightly different versions of the Buildr Gem (same functionality, different
-dependencies). Installing Buildr for Ruby does not install it for JRuby and
-vice versa.
-
-If you have JRuby installed but not Ruby, the @gem@ and @buildr@ commands will
-use JRuby. If you have both JRuby and Ruby installed, follow the instructions
-below. To find out if you have Ruby installed (some operating systems include
-it by default), run @ruby --version@ from the command line.
+Ruby and JRuby maintain separate Gem repositories, and in fact install slightly different versions of the Buildr Gem (same functionality, different dependencies). Installing Buildr for Ruby does not install it for JRuby and vice versa.
-To work exclusively with JRuby, make sure it shows first on the path, for example,
-by setting @PATH=/opt/jruby/bin:$PATH@.
+If you have JRuby installed but not Ruby, the @gem@ and @buildr@ commands will use JRuby. If you have both JRuby and Ruby installed, follow the instructions below. To find out if you have Ruby installed (some operating systems include it by default), run @ruby --version@ from the command line.
-You can use JRuby and Ruby side by side, by running scripts with the @-S@
-command line argument. For example:
+To work exclusively with JRuby, make sure it shows first on the path, for example, by setting @PATH=/opt/jruby/bin:$PATH@.
+
+You can use JRuby and Ruby side by side, by running scripts with the @-S@ command line argument. For example:
{{{!
$ # with Ruby
@@ -199,9 +158,7 @@
$ jruby -S buildr
}}}
-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.
+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. Document Conventions
@@ -213,35 +170,26 @@
$ buildr
}}}
-Lines that start with @=>@ show output from the console or the result of a
-method, for example:
+Lines that start with @=>@ show output from the console or the result of a method, for example:
{{{!sh
puts 'Hello world'
=> "Hello world"
}}}
-And as you guessed, everything else is Buildfile Ruby or Java code. You can
-figure out which language is which.
+And as you guessed, everything else is Buildfile Ruby or Java code. You can figure out which language is which.
h2. 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:
+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:
{{{!sh
$ buildr
}}}
-p(tip). You'll notice that Buildr creates a file called @buildfile@. It's
-case sensitive, but Buildr will look for either @buildfile@ or @Buildfile@.
-You can also use @Rakefile@ or @rakefile@ for compatibility with previous
-versions of Buildr.
+p(tip). You'll notice that Buildr creates a file called @buildfile@. It's case sensitive, but Buildr will look for either @buildfile@ or @Buildfile@.
You use Buildr by running the @buildr@ command:
@@ -266,8 +214,7 @@
| @-v/--version@ | Display the program version. |
| @-P/--prereqs@ | Display tasks and dependencies, then exit. |
-You can tell Buildr to run specific tasks and the order to run them. For
-example:
+You can tell Buildr to run specific tasks and the order to run them. For example:
{{{!sh
# Clean and rebuild
@@ -276,15 +223,9 @@
buildr install
}}}
-If you don't specify a task, Buildr will run the "@build@ task":building.html,
-compiling source code and running test cases. Running a task may run other
-tasks as well, for example, running the @install@ task will also run @package@.
-
-There are several "environment
-variables":settings_profiles.html#environment_variables that let you control
-how Buildr works, for example, to skip test cases during a build, or specify
-options for the JVM. Depending on the variable, you may want to set it once in
-your environment, or set a different value each time you run Buildr.
+If you don't specify a task, Buildr will run the "@build@ task":building.html, compiling source code and running test cases. Running a task may run other tasks as well, for example, running the @install@ task will also run @package@.
+
+There are several "environment variables":settings_profiles.html#environment_variables that let you control how Buildr works, for example, to skip test cases during a build, or specify options for the JVM. Depending on the variable, you may want to set it once in your environment, or set a different value each time you run Buildr.
For example:
@@ -296,10 +237,7 @@
h2. Help Tasks
-Buildr includes a number of informative tasks. Currently that number stands at
-two, but we'll be adding more tasks in future releases. These tasks report
-information from the Buildfile, so you need one to run them. For more general
-help (version number, command line arguments, etc) use @buildr --help@.
+Buildr includes a number of informative tasks. Currently that number stands at two, but we'll be adding more tasks in future releases. These tasks report information from the Buildfile, so you need one to run them. For more general help (version number, command line arguments, etc) use @buildr --help@.
To start with, type:
@@ -307,8 +245,7 @@
$ buildr help
}}}
-You can list the name and description of all your projects using the
-@help:projects@ task. For example:
+You can list the name and description of all your projects using the @help:projects@ task. For example:
{{{!sh
$ buildr help:projects
@@ -318,32 +255,19 @@
killer-app:la-web # What our users see
}}}
-You are, of course, describing your projects for the sake of those who will
-maintain your code, right? To describe a project, or a task, call the @desc@
-method before the project or task definition.
+You are, of course, describing your projects for the sake of those who will maintain your code, right? To describe a project, or a task, call the @desc@ method before the project or task definition.
So next let's talk about "projects":projects.html.
h2. Learning More
-*Ruby* It pays to pick up Ruby as a second (or first) programming language.
-It's fun, powerful and slightly addictive. If you're interested in learning
-Ruby the language, a good place to start is "Programming Ruby: The Pragmatic
-Programmer's Guide":http://www.pragprog.com/titles/ruby/programming-ruby,
-fondly known as the _Pickaxe book_.
-
-For a quicker read (and much more humor), "Whyâs (Poignant) Guide to
-Ruby":http://poignantguide.net/ruby/ is available online. More resources are
-listed on the "ruby-lang web site":http://www.ruby-lang.org/en/documentation/.
-
-*Rake* Buildr is based on Rake, a Ruby build system that handles tasks and
-dependencies. Check out the "Rake documentation":http://docs.rubyrake.org/ for
-more information.
-
-*AntWrap* Buildr uses AntWrap, for configuring and running Ant tasks. You can
-learn more from the "Antwrap documentation":http://antwrap.rubyforge.org/.
-
-*YAML* Buildr uses YAML for its profiles. You can "learn more about YAML
-here":http://www.yaml.org, and use this handy "YAML quick
-reference":http://www.yaml.org/refcard.html.
+*Ruby* It pays to pick up Ruby as a second (or first) programming language. It's fun, powerful and slightly addictive. If you're interested in learning Ruby the language, a good place to start is "Programming Ruby: The Pragmatic Programmer's Guide":http://www.pragprog.com/titles/ruby/programming-ruby, fondly known as the _Pickaxe book_.
+
+For a quicker read (and much more humor), "Whyâs (Poignant) Guide to Ruby":http://poignantguide.net/ruby/ is available online. More resources are listed on the "ruby-lang web site":http://www.ruby-lang.org/en/documentation/.
+
+*Rake* Buildr is based on Rake, a Ruby build system that handles tasks and dependencies. Check out the "Rake documentation":http://docs.rubyrake.org/ for more information.
+
+*AntWrap* Buildr uses AntWrap, for configuring and running Ant tasks. You can learn more from the "Antwrap documentation":http://antwrap.rubyforge.org/.
+
+*YAML* Buildr uses YAML for its profiles. You can "learn more about YAML here":http://www.yaml.org, and use this handy "YAML quick reference":http://www.yaml.org/refcard.html.
Modified: incubator/buildr/trunk/doc/pages/index.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/index.textile?rev=683061&r1=683060&r2=683061&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/index.textile (original)
+++ incubator/buildr/trunk/doc/pages/index.textile Tue Aug 5 17:23:42 2008
@@ -2,35 +2,22 @@
h2. What is Buildr?
-Buildr is a build system for Java applications. 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.
+Buildr is a build system for Java applications. 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:
-* 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.
-* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT
-source code generation, Javadoc and more.
-* A dependency mechanism that only builds what has changed since the last
-release.
-* A drop-in replacement for Maven 2.0, Buildr uses the same file layout,
-artifact specifications, local and remote repositories.
-* All your Ant tasks belong to us! Anything you can do with Ant, you can do
-with Buildr.
-* No overhead for building "plugins" or configuration. Just write new tasks or
-functions.
-* Buildr is Ruby all the way down. No one-off task is too demanding when you
-write code using variables, functions and objects.
+* 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.
+* Compiling, copying and filtering resources, JUnit/TestNG test cases, APT source code generation, Javadoc and more.
+* A dependency mechanism that only builds what has changed since the last release.
+* A drop-in replacement for Maven 2.0, Buildr uses the same file layout, artifact specifications, local and remote repositories.
+* All your Ant tasks belong to us! Anything you can do with Ant, you can do with Buildr.
+* No overhead for building "plugins" or configuration. Just write new tasks or functions.
+* Buildr is Ruby all the way down. No one-off task is too demanding when you write code using variables, functions and objects.
* 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":getting_started.html, or "download the PDF":buildr.pdf.
h2. News
@@ -51,18 +38,8 @@
h2. Notices
-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.
-
-Apache Buildr is an effort undergoing incubation at The Apache Software
-Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of
-all newly accepted projects until a further review indicates that the
-infrastructure, communications, and decision making process have stabilized in
-a manner consistent with other successful ASF projects. While incubation status
-is not necessarily a reflection of the completeness or stability of the code,
-it does indicate that the project has yet to be fully endorsed by the ASF.
-
-"ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html,
-copyright of Ken Saunders. "DejaVu fonts":http://dejavu.sourceforge.net,
-copyright of Bitstream, Inc.
+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.
+
+Apache Buildr is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
+
+"ColorCons":http://www.mouserunner.com/Spheres_ColoCons1_Free_Icons.html, copyright of Ken Saunders. "DejaVu fonts":http://dejavu.sourceforge.net, copyright of Bitstream, Inc.
Modified: incubator/buildr/trunk/doc/pages/more_stuff.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/more_stuff.textile?rev=683061&r1=683060&r2=683061&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/more_stuff.textile (original)
+++ incubator/buildr/trunk/doc/pages/more_stuff.textile Tue Aug 5 17:23:42 2008
@@ -3,44 +3,19 @@
h2. Using Gems
-The purpose of the buildfile is to define your projects, and the various tasks
-and functions used for building them. Some of these are specific to your
-projects, others are more general in nature, and you may want to share them
-across projects.
-
-There are several mechanisms for developing extensions and build features
-across projects which we cover in more details in the section "Extending
-Buildr":extending.html. Here we will talk about using extensions that are
-distributed in the form of RubyGems.
-
-"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool
-that you can use to search, install, upgrade, package and distribute gems. It
-installs all gems into a local repository that is shared across your builds and
-all other Ruby applications you may have running. You can install a gem from a
-local file, or download and install it from any number of remote repositories.
-
-RubyGems is preconfigured to use the "RubyForge":http://rubyforge.org
-repository. You'll find a large number of open source Ruby libraries there,
-including Buildr itself and all its dependencies. RubyForge provides a free
-account that you can use to host your projects and distribute your gems (you
-can use RubyForge strictly for distribution, as we do with Buildr).
-
-You can also set up your own private repository and use it instead or in
-addition to RubyForge. Use the @gem sources@ command to add repositories, and
-the @gem server@ command to run a remote repository. You can see all available
-options by running @gem help@.
-
-If your build depends on other gems, you will want to specify these
-dependencies as part of your build and check that configuration into source
-control. That way you can have a specific environment that will guarantee
-repeatable builds, whether you're building a particular version, moving between
-branches, or joining an existing project. Buildr will take care of installing
-all the necessary dependencies, which you can then manage with the @gem@
-command.
-
-Use the @build.yaml@ file to specify these dependencies (see "Build
-Settings":settings_profiles.html#build_settings for more information), for
-example:
+The purpose of the buildfile is to define your projects, and the various tasks and functions used for building them. Some of these are specific to your projects, others are more general in nature, and you may want to share them across projects.
+
+There are several mechanisms for developing extensions and build features across projects which we cover in more details in the section "Extending Buildr":extending.html. Here we will talk about using extensions that are distributed in the form of RubyGems.
+
+"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool that you can use to search, install, upgrade, package and distribute gems. It installs all gems into a local repository that is shared across your builds and all other Ruby applications you may have running. You can install a gem from a local file, or download and install it from any number of remote repositories.
+
+RubyGems is preconfigured to use the "RubyForge":http://rubyforge.org repository. You'll find a large number of open source Ruby libraries there, including Buildr itself and all its dependencies. RubyForge provides a free account that you can use to host your projects and distribute your gems (you can use RubyForge strictly for distribution, as we do with Buildr).
+
+You can also set up your own private repository and use it instead or in addition to RubyForge. Use the @gem sources@ command to add repositories, and the @gem server@ command to run a remote repository. You can see all available options by running @gem help@.
+
+If your build depends on other gems, you will want to specify these dependencies as part of your build and check that configuration into source control. That way you can have a specific environment that will guarantee repeatable builds, whether you're building a particular version, moving between branches, or joining an existing project. Buildr will take care of installing all the necessary dependencies, which you can then manage with the @gem@ command.
+
+Use the @build.yaml@ file to specify these dependencies (see "Build Settings":settings_profiles.html#build_settings for more information), for example:
{{{!yaml
# This project requires the following gems
@@ -52,52 +27,29 @@
- ci_reporter
}}}
-Gems contain executable code, and for that reason Buildr will not install gems
-without your permission. When you run a build that includes any dependencies
-that are not already installed on your machine, Buildr will ask for permission
-before installing them. On Unix-based operating systems, you will also need
-sudo privileges and will be asked for your password before proceeding.
-
-Since this step requires your input, it will only happen when running Buildr
-interactively from the command line. In all other cases, Buildr will fail and
-report the missing dependencies. If you have an automated build environment,
-make sure to run the build once manually to install all the necessary
-dependencies.
-
-When installing a gem for the first time, Buildr will automatically look for
-the latest available version. You can specify a particular version number, or
-a set of version numbers known to work with that build. You can use equality
-operations to specify a range of versions, for example, @1.2.3@ to install only
-version 1.2.3, and @=> 1.2.3@ to install version 1.2.3 or later.
-
-You can also specify a range up to one version bump, for example, @~> 1.2.3@ is
-the same as @>= 1.2.3 < 1.3.0@, and @~> 1.2@ is the same as @>= 1.2.0 < 2.0.0@.
-If necessary, you can exclude a particular version number, for example, @~>
-1.2.3 != 1.2.7@.
-
-Buildr will install the latest version that matches the version requirement.
-To keep up with newer versions, execute the @gem update@ command periodically.
-You can also use @gem outdated@ to determine which new versions are available.
-
-Most gems include documentation that you can access in several forms. You can
-use the @ri@ command line tool to find out more about a class, module or
-specific method. For example:
+Gems contain executable code, and for that reason Buildr will not install gems without your permission. When you run a build that includes any dependencies that are not already installed on your machine, Buildr will ask for permission before installing them. On Unix-based operating systems, you will also need sudo privileges and will be asked for your password before proceeding.
+
+Since this step requires your input, it will only happen when running Buildr interactively from the command line. In all other cases, Buildr will fail and report the missing dependencies. If you have an automated build environment, make sure to run the build once manually to install all the necessary dependencies.
+
+When installing a gem for the first time, Buildr will automatically look for the latest available version. You can specify a particular version number, or a set of version numbers known to work with that build. You can use equality operations to specify a range of versions, for example, @1.2.3@ to install only version 1.2.3, and @=> 1.2.3@ to install version 1.2.3 or later.
+
+You can also specify a range up to one version bump, for example, @~> 1.2.3@ is the same as @>= 1.2.3 < 1.3.0@, and @~> 1.2@ is the same as @>= 1.2.0 < 2.0.0@. If necessary, you can exclude a particular version number, for example, @~> 1.2.3 != 1.2.7@.
+
+Buildr will install the latest version that matches the version requirement. To keep up with newer versions, execute the @gem update@ command periodically. You can also use @gem outdated@ to determine which new versions are available.
+
+Most gems include documentation that you can access in several forms. You can use the @ri@ command line tool to find out more about a class, module or specific method. For example:
{{{!sh
$ ri Buildr::Jetty
$ ri Buildr::Jetty.start
}}}
-You can also access documentation from a Web browser by running @gem server@
-and pointing your browser to "http://localhost:8808":http://localhost:8808.
-Note that after installing a new gem, you will need to restart the gem server
-to see its documentation.
+You can also access documentation from a Web browser by running @gem server@ and pointing your browser to "http://localhost:8808":http://localhost:8808. Note that after installing a new gem, you will need to restart the gem server to see its documentation.
h2. Using Java Libraries
-Buildr runs along side a JVM, using either RJB or JRuby. The Java module
-allows you to access Java classes and create Java objects.
+Buildr runs along side a JVM, using either RJB or JRuby. The Java module allows you to access Java classes and create Java objects.
Java classes are accessed as static methods on the @Java@ module, for example:
@@ -110,12 +62,9 @@
Java.com.sun.tools.javac.Main.compile(args)
}}}
-The @classpath@ attribute allows Buildr to add JARs and directories to the
-classpath, for example, we use it to load Ant and various Ant tasks, code
-generators, test frameworks, and so forth.
+The @classpath@ attribute allows Buildr to add JARs and directories to the classpath, for example, we use it to load Ant and various Ant tasks, code generators, test frameworks, and so forth.
-When using an artifact specification, Buildr will automatically download and
-install the artifact before adding it to the classpath.
+When using an artifact specification, Buildr will automatically download and install the artifact before adding it to the classpath.
For example, Ant is loaded as follows:
@@ -123,37 +72,21 @@
Java.classpath << 'org.apache.ant:ant:jar:1.7.0'
}}}
-Artifacts can only be downloaded after the Buildfile has loaded, giving it a
-chance to specify which remote repositories to use, so adding to classpath does
-not by itself load any libraries. You must call @Java.load@ before accessing any
-Java classes to give Buildr a chance to load the libraries specified in the
-classpath.
+Artifacts can only be downloaded after the Buildfile has loaded, giving it a chance to specify which remote repositories to use, so adding to classpath does not by itself load any libraries. You must call @Java.load@ before accessing any Java classes to give Buildr a chance to load the libraries specified in the classpath.
When building an extension, make sure to follow these rules:
-# Add to the @classpath@ when the extension is loaded (i.e. in module or class
-definition), so the first call to @Java.load@ anywhere in the code will include
-the libraries you specify.
-# Call @Java.load@ once before accessing any Java classes, allowing Buildr to
-set up the classpath.
-# Only call @Java.load@ when invoked, otherwise you may end up loading the JVM
-with a partial classpath, or before all remote repositories are listed.
+# Add to the @classpath@ when the extension is loaded (i.e. in module or class definition), so the first call to @Java.load@ anywhere in the code will include the libraries you specify.
+# Call @Java.load@ once before accessing any Java classes, allowing Buildr to set up the classpath.
+# Only call @Java.load@ when invoked, otherwise you may end up loading the JVM with a partial classpath, or before all remote repositories are listed.
# Check on a clean build with empty local repository.
h2. Nailgun
-"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client,
-protocol, and server for running Java programs from the command line without
-incurring the JVM startup overhead.
-Nailgun integration is available only when running Buildr within JRuby.
-
-Buildr provides a custom nailgun server, allowing you to start a single JVM
-and let buildr create a queue of runtimes.
-These JRuby runtimes can be cached (indexed by buildfile path) and are
-automatically reloaded when the buildfile has been modified.
-Runtime caching allows you to execute tasks without spending time creating
-the buildr environment.
+"Nailgun":http://www.martiansoftware.com/nailgun/index.html is a client, protocol, and server for running Java programs from the command line without incurring the JVM startup overhead. Nailgun integration is available only when running Buildr within JRuby.
+
+Buildr provides a custom nailgun server, allowing you to start a single JVM and let buildr create a queue of runtimes. These JRuby runtimes can be cached (indexed by buildfile path) and are automatically reloaded when the buildfile has been modified. Runtime caching allows you to execute tasks without spending time creating the buildr environment.
Start the BuildrServer by executing
@@ -161,11 +94,7 @@
$ jruby -S buildr -rbuildr/nailgun nailgun:start
}}}
-Server output will display a message when it becomes ready, you
-will also see messages when the JRuby runtimes are being created,
-or when a new buildr environment is being loaded on them.
-After the runtime queues have been populated, you can start calling
-buildr as you normally do, by invoking the $NAILGUN_HOME/ng binary:
+Server output will display a message when it becomes ready, you will also see messages when the JRuby runtimes are being created, or when a new buildr environment is being loaded on them. After the runtime queues have been populated, you can start calling buildr as you normally do, by invoking the $NAILGUN_HOME/ng binary:
{{{!sh
# on another terminal, change directory to a project.
@@ -180,29 +109,22 @@
ng clean compile # just invoke those two tasks
}}}
-Some nailgun tasks have been provided to manage the cached runtimes,
-to get an overview of them execute the @nailgun:tasks@ task.
+Some nailgun tasks have been provided to manage the cached runtimes, to get an overview of them execute the @nailgun:tasks@ task.
Be sure to read the nailgun help by executing the @nailgun:help@ task.
h2. Eclipse, IDEA
-If you're using Eclipse, you can generate @.classpath@ and @.project@ from
-your Buildfile and use them to create a project in your workspace:
+If you're using Eclipse, you can generate @.classpath@ and @.project@ from your Buildfile and use them to create a project in your workspace:
{{{!sh
$ buildr eclipse
}}}
-The @eclipse@ task will generate a @.classpath@ and @.project@ file for each
-of projects (and sub-project) that compiles source code. It will not generate
-files for other projects, for examples, projects you use strictly for
-packaging a distribution, or creating command line scripts, etc.
-
-If you add a new project, change the dependencies, or make any other change to
-your Buildfile, just run the @eclipse@ task again to re-generate the Eclipse
-project files.
+The @eclipse@ task will generate a @.classpath@ and @.project@ file for each of projects (and sub-project) that compiles source code. It will not generate files for other projects, for examples, projects you use strictly for packaging a distribution, or creating command line scripts, etc.
+
+If you add a new project, change the dependencies, or make any other change to your Buildfile, just run the @eclipse@ task again to re-generate the Eclipse project files.
If you prefer IntelliJ IDEA, you can always:
@@ -210,33 +132,18 @@
$ buildr idea
}}}
-It will generate a @.iml@ file for every project (or subproject) and a @.ipr@
-that you can directly open for the root project. To allow IntelliJ Idea to
-resolve external dependencies properly, you will need to add a @M2_REPO@
-variable pointing to your Maven2 repository directory (@Settings / Path
-Variables@).
-
-If you're using IDEA 7 or later, use the @buildr idea7x@ task instead. This
-task creates the proper @.ipr@ and @.iml@ files for IDEA version 7. It
-includes the @-7x@ suffix in the generated files, so you can use the @idea@ and
-@idea7x@ tasks side by side on the same project.
-
-Also, check out the "Buildr plugin for
-IDEA":http://www.digitalsanctum.com/buildr-plug-in/ (IDEA 7 and later). Once
-installed, open your project with IDEA. If IDEA finds that you have Buildr
-installed and finds a buildfile in the project's directory, it will show all
-the tasks available for that project. To run a task, double-click it. When
-the task completes, IDEA will show the results in the Buildr Output window.
+It will generate a @.iml@ file for every project (or subproject) and a @.ipr@ that you can directly open for the root project. To allow IntelliJ Idea to resolve external dependencies properly, you will need to add a @M2_REPO@ variable pointing to your Maven2 repository directory (@Settings / Path Variables@).
+
+If you're using IDEA 7 or later, use the @buildr idea7x@ task instead. This task creates the proper @.ipr@ and @.iml@ files for IDEA version 7. It includes the @-7x@ suffix in the generated files, so you can use the @idea@ and @idea7x@ tasks side by side on the same project.
+
+Also, check out the "Buildr plugin for IDEA":http://www.digitalsanctum.com/buildr-plug-in/ (IDEA 7 and later). Once installed, open your project with IDEA. If IDEA finds that you have Buildr installed and finds a buildfile in the project's directory, it will show all the tasks available for that project. To run a task, double-click it. When the task completes, IDEA will show the results in the Buildr Output window.
h2. Cobertura, JDepend
-You can use "Cobertura":http://cobertura.sourceforge.net/ to instrument your
-code, run the tests and create a test coverage report in either HTML or XML
-format.
+You can use "Cobertura":http://cobertura.sourceforge.net/ to instrument your code, run the tests and create a test coverage report in either HTML or XML format.
-There are two tasks, both of which generate a test coverage report in the
-@reports/cobertura@ directory. For example:
+There are two tasks, both of which generate a test coverage report in the @reports/cobertura@ directory. For example:
{{{!sh
$ buildr test cobertura:html
@@ -244,16 +151,13 @@
As you can guess, the other task is @cobertura:xml@.
-If you want to generate cobertura reports only for a specific project, you
-can do so by using the project name as prefix to cobertura tasks.
+If you want to generate cobertura reports only for a specific project, you can do so by using the project name as prefix to cobertura tasks.
{{{!sh
$ buildr subModule:cobertura:html
}}}
-Each project can specify which classes to include or exclude from cobertura
-instrumentation by giving a class-name regexp to the @cobertura.include@ or
-@cobertura.exclude@ methods:
+Each project can specify which classes to include or exclude from cobertura instrumentation by giving a class-name regexp to the @cobertura.include@ or @cobertura.exclude@ methods:
{{{!ruby
define 'someModule' do
@@ -264,9 +168,7 @@
end
}}}
-You can use "JDepend":http://clarkware.com/software/JDepend.html on to
-generate design quality metrics. There are three tasks this time, the eye
-candy one:
+You can use "JDepend":http://clarkware.com/software/JDepend.html on to generate design quality metrics. There are three tasks this time, the eye candy one:
{{{!sh
$ buildr jdepend:swing
@@ -274,22 +176,16 @@
The other two tasks are @jdepend:text@ and @jdepend:xml@.
-We want Buildr to load fast, and not everyone cares for these tasks, so we
-don't include them by default. If you want to use either one, you need to
-require it explicitly. The proper way to do it in Ruby:
+We want Buildr to load fast, and not everyone cares for these tasks, so we don't include them by default. If you want to use either one, you need to require it explicitly. The proper way to do it in Ruby:
{{{!ruby
require 'buildr/cobertura'
require 'buildr/jdepend'
}}}
-You may want to add those to the Buildfile. Alternatively, you can use these
-tasks for all your projects without modifying the Buildfile. One convenient
-method is to add these two likes to the @buildr.rb@ file in your home
-directory.
+You may want to add those to the Buildfile. Alternatively, you can use these tasks for all your projects without modifying the Buildfile. One convenient method is to add these two likes to the @buildr.rb@ file in your home directory.
-Another option is to require it from the command line (@--require@ or @-r@),
-for example:
+Another option is to require it from the command line (@--require@ or @-r@), for example:
{{{!sh
$ buildr --require buildr/jdepend jdepend:swing
@@ -299,18 +195,11 @@
h2. Anything Ruby Can Do
-Buildr is Ruby code. That's an implementation detail for some, but a useful
-features for others. You can use Ruby to keep your build scripts simple and
-DRY, tackle ad hoc tasks and write reusable features without the complexity of
-"plugins".
-
-We already showed you one example where Ruby could help. You can use Ruby to
-manage dependency by setting constants and reusing them, grouping related
-dependencies into arrays and structures.
-
-You can use Ruby to perform ad hoc tasks. For example, Buildr doesn't have
-any pre-canned task for setting file permissions. But Ruby has a method for
-that, so it's just a matter of writing a task:
+Buildr is Ruby code. That's an implementation detail for some, but a useful features for others. You can use Ruby to keep your build scripts simple and DRY, tackle ad hoc tasks and write reusable features without the complexity of "plugins".
+
+We already showed you one example where Ruby could help. You can use Ruby to manage dependency by setting constants and reusing them, grouping related dependencies into arrays and structures.
+
+You can use Ruby to perform ad hoc tasks. For example, Buildr doesn't have any pre-canned task for setting file permissions. But Ruby has a method for that, so it's just a matter of writing a task:
{{{!ruby
bins = file('target/bin'=>FileList[_('src/main/dist/bin/*')]) do |task|
@@ -320,10 +209,7 @@
end
}}}
-You can use functions to keep your code simple. For example, in the ODE
-project we create two binary distributions, both of which contain a common set
-of files, and one additional file unique to each distribution. We use a
-method to define the common distribution:
+You can use functions to keep your code simple. For example, in the ODE project we create two binary distributions, both of which contain a common set of files, and one additional file unique to each distribution. We use a method to define the common distribution:
{{{!ruby
def distro(project, id)
@@ -352,9 +238,7 @@
end
}}}
-Ruby's functional style and blocks make some task extremely easy. For
-example, let's say we wanted to count how many source files we have, and total
-number of lines:
+Ruby's functional style and blocks make some task extremely easy. For example, let's say we wanted to count how many source files we have, and total number of lines:
{{{!ruby
sources = projects.map { |prj| prj.compile.sources.
Modified: incubator/buildr/trunk/doc/pages/packaging.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/packaging.textile?rev=683061&r1=683060&r2=683061&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/packaging.textile (original)
+++ incubator/buildr/trunk/doc/pages/packaging.textile Tue Aug 5 17:23:42 2008
@@ -1,22 +1,18 @@
h1. Packaging
-For our next trick, we're going to try and create an artifact ourselves. We're
-going to start with:
+For our next trick, we're going to try and create an artifact ourselves. We're going to start with:
{{{!ruby
package :jar
}}}
-We just told the project to create a JAR file in the @target@ directory,
-including all the classes (and resources) that we previously compiled into
-@target/classes@. Or we can create a WAR file:
+We just told the project to create a JAR file in the @target@ directory, including all the classes (and resources) that we previously compiled into @target/classes@. Or we can create a WAR file:
{{{!ruby
package :war
}}}
-The easy case is always easy, but sometimes we have more complicated use cases
-which we'll address through the rest of this section.
+The easy case is always easy, but sometimes we have more complicated use cases which we'll address through the rest of this section.
Now let's run the build, test cases and create these packages:
@@ -24,23 +20,14 @@
$ buildr package
}}}
-The @package@ task runs the @build@ task (remember: @compile@ and @test@) and
-then runs each of the packaging tasks, creating packages in the projects'
-target directories.
-
-p(tip). The @package@ task and @package@ methods are related, but that relation is
-different from other task/method pairs. The @package@ method creates a file
-task that points to the package in the @target@ directory and knows how to
-create it. It then adds itself as a prerequisite to the @package@ task.
-Translation: you can create multiple packages from the same project.
+The @package@ task runs the @build@ task (remember: @compile@ and @test@) and then runs each of the packaging tasks, creating packages in the projects' target directories.
+
+p(tip). The @package@ task and @package@ methods are related, but that relation is different from other task/method pairs. The @package@ method creates a file task that points to the package in the @target@ directory and knows how to create it. It then adds itself as a prerequisite to the @package@ task. Translation: you can create multiple packages from the same project.
h2. Specifying And Referencing Packages
-Buildr supports several packaging types, and so when dealing with packages, you
-have to indicate the desired package type. The packaging type can be the first
-argument, or the value of the @:type@ argument. The following two are
-equivalent:
+Buildr supports several packaging types, and so when dealing with packages, you have to indicate the desired package type. The packaging type can be the first argument, or the value of the @:type@ argument. The following two are equivalent:
{{{!ruby
package :jar
@@ -49,10 +36,7 @@
If you do not specify a package type, Buildr will attempt to infer one.
-In the documentation you will find a number of tasks dealing with specific
-packaging types (@ZipTask@, @JarTask@, etc). The @package@ method is a
-convenience mechanism that sets up the package for you associates it with
-various project life cycle tasks.
+In the documentation you will find a number of tasks dealing with specific packaging types (@ZipTask@, @JarTask@, etc). The @package@ method is a convenience mechanism that sets up the package for you associates it with various project life cycle tasks.
To package a particular file, use the @:file@ argument, for example:
@@ -60,25 +44,13 @@
package :zip, :file=>_('target/interesting.zip')
}}}
-This returns a file task that will run as part of the project's @package@ task
-(generating all packages). It will invoke the @build@ task to generate any
-necessary prerequisites, before creating the specified file.
-
-The package type does not have to be the same as the file name extension, but
-if you don't specify the package type, it will be inferred from the extension.
-
-Most often you will want to use the second form to generate packages that are
-also artifacts. These packages have an artifact specification, which you can
-use to reference them from other projects (and buildfiles). They are also
-easier to share across projects: artifacts install themselves in the local
-repository when running the @install@ task, and upload to the remote repository
-when running the @upload@ task (see "Installing and
-Uploading":#installing_and_uploading).
-
-The artifact specification is based on the project name (using dashes instead
-of colons), group identifier and version number, all three obtained from the
-project definition. You can specify different values using the @:id@,
-@:group@, @:version@ and @:classifier@ arguments. For example:
+This returns a file task that will run as part of the project's @package@ task (generating all packages). It will invoke the @build@ task to generate any necessary prerequisites, before creating the specified file.
+
+The package type does not have to be the same as the file name extension, but if you don't specify the package type, it will be inferred from the extension.
+
+Most often you will want to use the second form to generate packages that are also artifacts. These packages have an artifact specification, which you can use to reference them from other projects (and buildfiles). They are also easier to share across projects: artifacts install themselves in the local repository when running the @install@ task, and upload to the remote repository when running the @upload@ task (see "Installing and Uploading":#installing_and_uploading).
+
+The artifact specification is based on the project name (using dashes instead of colons), group identifier and version number, all three obtained from the project definition. You can specify different values using the @:id@, @:group@, @:version@ and @:classifier@ arguments. For example:
{{{!ruby
define 'killer-app', :version=>'1.0' do
@@ -97,24 +69,13 @@
end
}}}
-The file name is determined from the identifier, version number, classifier and
-extension associated with that packaging type.
+The file name is determined from the identifier, version number, classifier and extension associated with that packaging type.
+
+If you do not specify the packaging type, Buildr attempt to infer it from the project definition. In the general case it will use the default packaging type, ZIP. A project that compiles Java classes will default to JAR packaging; for other languages, consult the specific documentation.
-If you do not specify the packaging type, Buildr attempt to infer it from the
-project definition. In the general case it will use the default packaging
-type, ZIP. A project that compiles Java classes will default to JAR packaging;
-for other languages, consult the specific documentation.
-
-A single project can create multiple packages. For example, a Java project may
-generate a JAR package for the runtime library and another JAR containing just
-the API; a ZIP file for the source code and another ZIP for the documentation.
-Make sure to always call @package@ with enough information to identify the
-specific package you are referencing. Even if the project only defines a
-single package, calling the @package@ method with no arguments does not
-necessarily refer to that one.
+A single project can create multiple packages. For example, a Java project may generate a JAR package for the runtime library and another JAR containing just the API; a ZIP file for the source code and another ZIP for the documentation. Make sure to always call @package@ with enough information to identify the specific package you are referencing. Even if the project only defines a single package, calling the @package@ method with no arguments does not necessarily refer to that one.
-You can use the @packages@ method to obtain a list of all packages defined in
-the project, for example:
+You can use the @packages@ method to obtain a list of all packages defined in the project, for example:
{{{!ruby
project('killer-app:teh-impl').packages.first
@@ -124,42 +85,30 @@
h2. Packaging ZIPs
-ZIP is the most common form of packaging, used by default when no other
-packaging type applies. It also forms the basis for many other packaging types
-(e.g. JAR and WAR). Most of what you'll find here applies to other packaging
-types.
+ZIP is the most common form of packaging, used by default when no other packaging type applies. It also forms the basis for many other packaging types (e.g. JAR and WAR). Most of what you'll find here applies to other packaging types.
-Let's start by including additional files in the ZIP package. We're going to
-include the @target/docs@ directory and @README@ file:
+Let's start by including additional files in the ZIP package. We're going to include the @target/docs@ directory and @README@ file:
{{{!ruby
package(:zip).include _('target/docs'), 'README'
}}}
-The @include@ method accepts files, directories and file tasks. You can also
-use file pattern to match multiple files and directories. File patterns
-include asterisk (@*@) to match any file name or part of a file name, double
-asterisk (@**@) to match directories recursively, question mark (@?@) to match
-any character, square braces (@[]@) to match a set of characters, and curly
-braces (@{}@) to match one of several names.
+The @include@ method accepts files, directories and file tasks. You can also use file pattern to match multiple files and directories. File patterns include asterisk (@*@) to match any file name or part of a file name, double asterisk (@**@) to match directories recursively, question mark (@?@) to match any character, square braces (@[]@) to match a set of characters, and curly braces (@{}@) to match one of several names.
-And the same way you @include@, you can also @exclude@ specific files you don't
-want showing up in the ZIP. For example, to exclude @.draft@ and @.raw@ files:
+And the same way you @include@, you can also @exclude@ specific files you don't want showing up in the ZIP. For example, to exclude @.draft@ and @.raw@ files:
{{{!ruby
package(:zip).include('target/docs').
exclude('target/docs/**/*.{draft,raw}')
}}}
-So far we've included files under the root of the ZIP. Let's include some
-files under a given path using the @:path@ option:
+So far we've included files under the root of the ZIP. Let's include some files under a given path using the @:path@ option:
{{{!ruby
package(:zip).include 'target/docs', :path=>"#{id}-#{version}"
}}}
-If you need to use the @:path@ option repeatedly, consider using the @tap@
-method instead. For example:
+If you need to use the @:path@ option repeatedly, consider using the @tap@ method instead. For example:
{{{!ruby
package(:zip).path("#{id}-#{version}").tap do |path|
@@ -168,56 +117,36 @@
end
}}}
-p(tip). The @tap@ method is not part of the core library, but a very useful
-extension. It takes an object, yields to the block with that object, and then
-returns that object.
-
-p(note). To allow you to spread files across different paths, the
-include/exclude patterns are specific to a path. So in the above example, if
-you want to exclude some files from the "target/docs" directory, make sure to
-call @exclude@ on the path, not on the ZIP task itself.
+p(tip). The @tap@ method is not part of the core library, but a very useful extension. It takes an object, yields to the block with that object, and then returns that object.
+
+p(note). To allow you to spread files across different paths, the include/exclude patterns are specific to a path. So in the above example, if you want to exclude some files from the "target/docs" directory, make sure to call @exclude@ on the path, not on the ZIP task itself.
-If you need to include a file or directory under a different name, use the
-@:as@ option. For example:
+If you need to include a file or directory under a different name, use the @:as@ option. For example:
{{{!ruby
package(:zip).include('corporate-logo-350x240.png', :as=>'logo.png')
}}}
-You can also use @:as=>'.'@ to include all files from the given directory. For
-example:
+You can also use @:as=>'.'@ to include all files from the given directory. For example:
{{{!ruby
package(:zip).include 'target/docs/*'
package(:zip).include 'target/docs', :as=>'.'
}}}
-These two are almost identical. They both include all the files from the
-@target/docs@ directory, but not the directory itself. But they operate
-differently. The first line expands to include all the files in @target/docs@.
-If you don't already have files in @target/docs@, well, then it won't do
-anything interesting. Your ZIP will come up empty. The second file includes
-the directory itself, but strips the path during inclusion. You can define it
-now, create these files later, and then ZIP them all up.
-
-For example, when @package :jar@ decides to include all the files from
-@target/classes@, it's still working on the project definition, and has yet to
-compile anything. Since @target/classes@ may be empty, may not even exist, it
-uses @:as=>'.'@.
-
-If you need to get rid of all the included files, call the @clean@ method.
-Some packaging types default to adding various files and directories, for
-example, JAR packaging will include all the compiled classes and resources.
+These two are almost identical. They both include all the files from the @target/docs@ directory, but not the directory itself. But they operate differently. The first line expands to include all the files in @target/docs@. If you don't already have files in @target/docs@, well, then it won't do anything interesting. Your ZIP will come up empty. The second file includes the directory itself, but strips the path during inclusion. You can define it now, create these files later, and then ZIP them all up.
-You can also merge two ZIP files together, expanding the content of one ZIP
-into the other. For example:
+For example, when @package :jar@ decides to include all the files from @target/classes@, it's still working on the project definition, and has yet to compile anything. Since @target/classes@ may be empty, may not even exist, it uses @:as=>'.'@.
+
+If you need to get rid of all the included files, call the @clean@ method. Some packaging types default to adding various files and directories, for example, JAR packaging will include all the compiled classes and resources.
+
+You can also merge two ZIP files together, expanding the content of one ZIP into the other. For example:
{{{!ruby
package(:zip).merge 'part1.zip', 'part2.zip'
}}}
-If you need to be more selective, you can apply the include/exclude pattern to
-the expanded ZIP. For example:
+If you need to be more selective, you can apply the include/exclude pattern to the expanded ZIP. For example:
{{{!ruby
# Everything but the libs
@@ -227,9 +156,7 @@
h2. Packaging JARs
-JAR packages extend ZIP packages with support for Manifest files and the
-META-INF directory. They also default to include the class files found in the
-@target/classes@ directory.
+JAR packages extend ZIP packages with support for Manifest files and the META-INF directory. They also default to include the class files found in the @target/classes@ directory.
You can tell the JAR package to include a particular Manifest file:
@@ -243,14 +170,9 @@
package(:jar).with :manifest=>{ 'Copyright'=>'Acme Inc (C) 2007' }
}}}
-You can also generate a JAR with no manifest with the value @false@, create a
-manifest with several sections using an array of hashes, or create it from a
-proc.
-
-In large projects, where all the packages use the same manifest, it's easier to
-set it once on the top project using the @manifest@ project property.
-Sub-projects inherit the property from their parents, and the @package@ method
-uses that property if you don't override it, as we do above.
+You can also generate a JAR with no manifest with the value @false@, create a manifest with several sections using an array of hashes, or create it from a proc.
+
+In large projects, where all the packages use the same manifest, it's easier to set it once on the top project using the @manifest@ project property. Sub-projects inherit the property from their parents, and the @package@ method uses that property if you don't override it, as we do above.
For example, we can get the same result by specifying this at the top project:
@@ -258,30 +180,21 @@
manifest['Copyright'] = 'Acme Inc (C) 2007'
}}}
-If you need to mix-in the project's manifest with values that only one package
-uses, you can do so easily:
+If you need to mix-in the project's manifest with values that only one package uses, you can do so easily:
{{{!ruby
package(:jar).with :manifest=>manifest.merge('Main-Class'=>'com.acme.Main')
}}}
-If you need to include more files in the @META-INF@ directory, you can use the
-@:meta_inf@ option. You can give it a file, or array of files. And yes, there
-is a @meta_inf@ project property you can set once to include the same set of
-file in all the JARs. It works like this:
+If you need to include more files in the @META-INF@ directory, you can use the @:meta_inf@ option. You can give it a file, or array of files. And yes, there is a @meta_inf@ project property you can set once to include the same set of file in all the JARs. It works like this:
{{{!ruby
meta_inf << file('DISCLAIMER') << file('NOTICE')
}}}
-If you have a @LICENSE@ file, it's already included in the @meta_inf@ list of
-files.
+If you have a @LICENSE@ file, it's already included in the @meta_inf@ list of files.
-Other than that, @package :jar@ includes the contents of the compiler's target
-directory and resources, which most often is exactly what you intend it to do.
-If you want to include other files in the JAR, instead or in addition, you can
-do so using the @include@ and @exclude@ methods. If you do not want the target
-directory included in your JAR, simply call the @clean@ method on it:
+Other than that, @package :jar@ includes the contents of the compiler's target directory and resources, which most often is exactly what you intend it to do. If you want to include other files in the JAR, instead or in addition, you can do so using the @include@ and @exclude@ methods. If you do not want the target directory included in your JAR, simply call the @clean@ method on it:
{{{!ruby
package(:jar).clean.include( only_these_files )
@@ -290,18 +203,11 @@
h2. Packaging WARs
-Pretty much everything you know about JARs works the same way for WARs, so
-let's just look at the differences.
+Pretty much everything you know about JARs works the same way for WARs, so let's just look at the differences.
-Without much prompting, @package :war@ picks the contents of the
-@src/main/webapp@ directory and places it at the root of the WAR, copies the
-compiler target directory into the @WEB-INF/classes@ path, and copies any
-compiled dependencies into the @WEB-INF/libs@ paths.
-
-Again, you can use the @include@ and @exclude@ methods to change the contents
-of the WAR. There are two convenience options you can use to make the more
-common changes. If you need to include a classes directory other than the
-default:
+Without much prompting, @package :war@ picks the contents of the @src/main/webapp@ directory and places it at the root of the WAR, copies the compiler target directory into the @WEB-INF/classes@ path, and copies any compiled dependencies into the @WEB-INF/libs@ paths.
+
+Again, you can use the @include@ and @exclude@ methods to change the contents of the WAR. There are two convenience options you can use to make the more common changes. If you need to include a classes directory other than the default:
{{{!ruby
package(:war).with :classes=>_('target/additional')
@@ -313,15 +219,9 @@
package(:war).with :libs=>MYSQL_JDBC
}}}
-Both options accept a single value or an array. The @:classes@ option accepts
-the name of a directory containing class files, initially set to
-@compile.target@ and @resources.target@. The @:libs@ option accepts artifact
-specifications, file names and tasks, initially set to include everything in
-@compile.dependencies@.
-
-As you can guess, the package task has two attributes called @classes@ and
-@libs@; the @with@ method merely sets their value. If you need more precise
-control over these arrays, you can always work with them directly, for example:
+Both options accept a single value or an array. The @:classes@ option accepts the name of a directory containing class files, initially set to @compile.target@ and @resources.target@. The @:libs@ option accepts artifact specifications, file names and tasks, initially set to include everything in @compile.dependencies@.
+
+As you can guess, the package task has two attributes called @classes@ and @libs@; the @with@ method merely sets their value. If you need more precise control over these arrays, you can always work with them directly, for example:
{{{!ruby
# Add an artifact to the existing set:
@@ -336,34 +236,20 @@
h2. Packaging AARs
-Axis2 service archives are similar to JAR's (compiled classes go into the root
-of the archive) but they can embed additional libraries under /lib and include
-@services.xml@ and WSDL files.
+Axis2 service archives are similar to JAR's (compiled classes go into the root of the archive) but they can embed additional libraries under /lib and include @services.xml@ and WSDL files.
{{{!ruby
package(:aar).with(:libs=>'log4j:log4j:jar:1.1')
package(:aar).with(:services_xml=>_('target/services.xml'), :wsdls=>_('target/*.wsdl'))
}}}
-The @libs@ attribute is a list of .jar artifacts to be included in the archive
-under /lib. The default is no artifacts; compile dependencies are not included
-by default.
-
-The @services_xml@ attribute points to an Axis2 services configuration file
-called @services.xml@ that will be placed in the @META-INF@ directory inside
-the archive. The default behavior is to point to the @services.xml@ file in
-the project's @src/main/axis2@ directory. In the second example above we set
-it explicitly.
-
-The @wsdls@ attribute is a collection of file names or glob patterns for WSDL
-files that get included in the @META-INF@ directory. In the second example we
-include WSDL files from the @target@ directory, presumably created by an
-earlier build task. In addition, AAR packaging will include all files ending
-with @.wsdl@ from the @src/main/axis2@ directory.
-
-If you already have WSDL files in the @src/main/axis2@ directory but would like
-to perform some filtering, for example, to set the HTTP port number, consider
-ignoring the originals and including only the filtered files, for example:
+The @libs@ attribute is a list of .jar artifacts to be included in the archive under /lib. The default is no artifacts; compile dependencies are not included by default.
+
+The @services_xml@ attribute points to an Axis2 services configuration file called @services.xml@ that will be placed in the @META-INF@ directory inside the archive. The default behavior is to point to the @services.xml@ file in the project's @src/main/axis2@ directory. In the second example above we set it explicitly.
+
+The @wsdls@ attribute is a collection of file names or glob patterns for WSDL files that get included in the @META-INF@ directory. In the second example we include WSDL files from the @target@ directory, presumably created by an earlier build task. In addition, AAR packaging will include all files ending with @.wsdl@ from the @src/main/axis2@ directory.
+
+If you already have WSDL files in the @src/main/axis2@ directory but would like to perform some filtering, for example, to set the HTTP port number, consider ignoring the originals and including only the filtered files, for example:
{{{!ruby
# Host name depends on environment.
@@ -377,10 +263,7 @@
h2. Packaging EARs
-EAR packaging is slightly different from JAR/WAR packaging. It's main purpose
-is to package components together, and so it includes special methods for
-handling component inclusion that take care to update application.xml and the
-component's classpath.
+EAR packaging is slightly different from JAR/WAR packaging. It's main purpose is to package components together, and so it includes special methods for handling component inclusion that take care to update application.xml and the component's classpath.
EAR packages support four component types:
@@ -397,11 +280,7 @@
package(:ear).add project('commonLib') # By default, the JAR package
}}}
-Adding a WAR package assumes it's a WAR component and treats it as such, but
-JAR packages can be any of three component types, so by default they are all
-treated as shared libraries. If you want to add an EJB or Application Client
-component, you need to say so explicitly, either passing @:type=>package@, or by
-passing the component type in the @:type@ option.
+Adding a WAR package assumes it's a WAR component and treats it as such, but JAR packages can be any of three component types, so by default they are all treated as shared libraries. If you want to add an EJB or Application Client component, you need to say so explicitly, either passing @:type=>package@, or by passing the component type in the @:type@ option.
Here are three examples:
@@ -414,13 +293,9 @@
package(:ear).add project('client'), :type=>:jar
}}}
-By default, WAR components are all added under the @/war@ path, and likewise,
-EJB components are added under the @/ejb@ path, shared libraries under @/lib@
-and Application Client components under @/jar@.
-
-If you want to place components in different locations you can do so using the
-@:path@ option, or by specifying a different mapping between component types
-and their destination directory. The following two examples are equivalent:
+By default, WAR components are all added under the @/war@ path, and likewise, EJB components are added under the @/ejb@ path, shared libraries under @/lib@ and Application Client components under @/jar@.
+
+If you want to place components in different locations you can do so using the @:path@ option, or by specifying a different mapping between component types and their destination directory. The following two examples are equivalent:
{{{!ruby
# Specify once per component.
@@ -430,18 +305,11 @@
package(:ear) << project('coolWebService').package(:war)
}}}
-EAR packages include an @application.xml@ file in the @META-INF@ directory that
-describes the application and its components. This file is created for you
-during packaging, by referencing all the components added to the EAR. There
-are a couple of things you will typically want to change.
-
-* *display-name* -- The application's display name defaults to the project's
-identifier. You can change that by setting the @display_name@ attribute.
-
-* *context-root* -- WAR components specify a context root, based on the package
-identifier, for example, "cool-web-1.0.war" will have the context root
-"cool-web". To specify a different context root, add the WAR package with the
-@context_root@ option.
+EAR packages include an @application.xml@ file in the @META-INF@ directory that describes the application and its components. This file is created for you during packaging, by referencing all the components added to the EAR. There are a couple of things you will typically want to change.
+
+* *display-name* -- The application's display name defaults to the project's identifier. You can change that by setting the @display_name@ attribute.
+
+* *context-root* -- WAR components specify a context root, based on the package identifier, for example, "cool-web-1.0.war" will have the context root "cool-web". To specify a different context root, add the WAR package with the @context_root@ option.
Again, by example:
@@ -450,40 +318,28 @@
package(:ear).add project('coolWebService').package(:war), :context-root=>'coolness'
}}}
-If you need to disable the context root (e.g. for Portlets), set @context_root@
-to @false@.
+If you need to disable the context root (e.g. for Portlets), set @context_root@ to @false@.
h2. Packaging Tars and GZipped Tars
-Everything you know about working with ZIP files translates to Tar files, the
-two tasks are identical in more respect, so here we'll just go over the
-differences.
+Everything you know about working with ZIP files translates to Tar files, the two tasks are identical in more respect, so here we'll just go over the differences.
{{{!ruby
package(:tar).include _('target/docs'), 'README'
package(:tgz).include _('target/docs'), 'README'
}}}
-The first line creates a Tar archive with the extension @.tar@, the second
-creates a GZipped Tar archive with the extension @.tgz@.
+The first line creates a Tar archive with the extension @.tar@, the second creates a GZipped Tar archive with the extension @.tgz@.
-In addition to packaging that includes the archive in the list of
-installed/released files, you can use the method @tar@ to create a @TarTask@.
-This task is similar to @ZipTask@, and introduces the @gzip@ attribute, which
-you can use to tell it whether to create a regular file, or GZip it. By
-default the attribute it set to true (GZip) if the file name ends with either
-@.gz@ or @.tgz@.
+In addition to packaging that includes the archive in the list of installed/released files, you can use the method @tar@ to create a @TarTask@. This task is similar to @ZipTask@, and introduces the @gzip@ attribute, which you can use to tell it whether to create a regular file, or GZip it. By default the attribute it set to true (GZip) if the file name ends with either @.gz@ or @.tgz@.
h2. Installing and Uploading
-You can bring in the artifacts you need from remote repositories and install
-them in the local repositories. Other projects have the same expectation, that
-your packages be their artifacts.
+You can bring in the artifacts you need from remote repositories and install them in the local repositories. Other projects have the same expectation, that your packages be their artifacts.
-So let's create these packages and install them in the local repository where
-other projects can access them:
+So let's create these packages and install them in the local repository where other projects can access them:
{{{!sh
$ buildr install
@@ -495,8 +351,7 @@
$ buildr uninstall
}}}
-That works between projects you build on the same machine. Now let's share
-these artifacts with other developers through a remote repository:
+That works between projects you build on the same machine. Now let's share these artifacts with other developers through a remote repository:
{{{!sh
$ buildr upload
@@ -508,20 +363,11 @@
repositories.release_to = 'sftp://john:secret@release/usr/share/repo'
}}}
-This example uses the SFTP protocol. In addition, you can use the HTTP
-protocol -- Buildr supports HTTP and HTTPS, Basic Authentication and uploads
-using PUT -- or point to a directory on your file system.
-
-The URL in this example contains the release server ("release"), path to
-repository ("user/share/repo") and username/password for access. The way SFTP
-works, you specify the path on the release server, and give the user
-permissions to create directories and files inside the repository. The file
-system path is different from the path you use to download these artifacts
-through an HTTP server, and starts at the root, not the user's home directory.
-
-Of course, you'll want to specify the release server URL in the Buildfile, but
-leave the username/password settings private in your local @buildr.rb@ file.
-Let's break up the release server settings:
+This example uses the SFTP protocol. In addition, you can use the HTTP protocol -- Buildr supports HTTP and HTTPS, Basic Authentication and uploads using PUT -- or point to a directory on your file system.
+
+The URL in this example contains the release server ("release"), path to repository ("user/share/repo") and username/password for access. The way SFTP works, you specify the path on the release server, and give the user permissions to create directories and files inside the repository. The file system path is different from the path you use to download these artifacts through an HTTP server, and starts at the root, not the user's home directory.
+
+Of course, you'll want to specify the release server URL in the Buildfile, but leave the username/password settings private in your local @buildr.rb@ file. Let's break up the release server settings:
{{{!ruby
# build.rb, loaded first
@@ -532,14 +378,9 @@
repositories.release_to[:url] = 'sftp://release/usr/share/repo'
}}}
-The @upload@ task takes care of uploading all the packages created by your
-project, along with their associated POM files and MD5/SHA1 signatures (Buildr
-creates these for you).
-
-If you need to upload other files, you can always extend the @upload@ task and
-use @repositories.release_to@ in combination with @URI.upload@. You can also
-extend it to upload to different servers, for example, to publish the
-documentation and test coverage reports to your site:
+The @upload@ task takes care of uploading all the packages created by your project, along with their associated POM files and MD5/SHA1 signatures (Buildr creates these for you).
+
+If you need to upload other files, you can always extend the @upload@ task and use @repositories.release_to@ in combination with @URI.upload@. You can also extend it to upload to different servers, for example, to publish the documentation and test coverage reports to your site:
{{{!ruby
# We'll let some other task decide how to create 'docs'
@@ -552,21 +393,15 @@
h2. Packaging Sources and JavaDocs
-IDEs can take advantage of source packages to help you debug and trace through
-compiled code. We'll start with a simple example:
+IDEs can take advantage of source packages to help you debug and trace through compiled code. We'll start with a simple example:
{{{!ruby
package :sources
}}}
-This one creates a ZIP package with the classifier "sources" that will contain
-all the source directories in that project, typically @src/main/java@, but also
-other sources generated from Apt, JavaCC, XMLBeans and friends.
-
-You can also generate a ZIP package with the classifier "javadoc" that contains
-the JavaDoc documentation for the project. It uses the same set of
-documentation files generated by the project's @javadoc@ task, so you can use
-it in combination with the @javadoc@ method. For example:
+This one creates a ZIP package with the classifier "sources" that will contain all the source directories in that project, typically @src/main/java@, but also other sources generated from Apt, JavaCC, XMLBeans and friends.
+
+You can also generate a ZIP package with the classifier "javadoc" that contains the JavaDoc documentation for the project. It uses the same set of documentation files generated by the project's @javadoc@ task, so you can use it in combination with the @javadoc@ method. For example:
{{{!ruby
package :javadoc
@@ -575,9 +410,7 @@
By default Buildr picks the project's description for the window title.
-You can also tell Buildr to automatically create sources and JavaDoc packages
-in all the sub-projects that have any source files to package or document.
-Just add either or both of these methods in the top-level project:
+You can also tell Buildr to automatically create sources and JavaDoc packages in all the sub-projects that have any source files to package or document. Just add either or both of these methods in the top-level project:
{{{!ruby
package_with_sources
@@ -591,5 +424,4 @@
package_with_javadoc :except=>'la-web'
}}}
-We packaged the code, but will it actually work? Let's see "what the tests
-say":testing.html.
+We packaged the code, but will it actually work? Let's see "what the tests say":testing.html.