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 2009/03/11 23:43:23 UTC
svn commit: r752671 [2/2] - in /buildr/trunk/doc: ./ _layouts/
Modified: buildr/trunk/doc/settings_profiles.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/settings_profiles.textile?rev=752671&r1=752670&r2=752671&view=diff
==============================================================================
--- buildr/trunk/doc/settings_profiles.textile (original)
+++ buildr/trunk/doc/settings_profiles.textile Wed Mar 11 22:43:22 2009
@@ -10,24 +10,30 @@
For example:
+<notextile>
{% highlight sh %}
$ export HTTP_PROXY=http://myproxy:8080
{% endhighlight %}
+</notextile>
There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:
+<notextile>
{% highlight sh %}
$ buildr test=no
{% endhighlight %}
+</notextile>
For convenience, when you set environment variables on the command line, the variable name is case insensitive, you can use either @test=no@ or @TEST=no@. Any other way (@export@, @ENV@, etc) the variable names are case sensitive.
You can also set environment variables from within your Buildfile. For example, if you discover that building your project requires gobs of JVM heap space, and you want all other team members to run with the same settings:
+<notextile>
{% highlight ruby %}
# This project builds a lot of code.
ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
{% endhighlight %}
+</notextile>
Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even @require@).
@@ -39,23 +45,24 @@
| @BUILDR_ENV@ | Environment name (development, production, test, etc). Another way to set this is using the @-e@ command line option. |
| @DEBUG@ | Set to @no/off@ if you want Buildr to compile without debugging information (default when running the @release@ task, see "Compiling":building.html#compiling). |
| @HOME@ | Your home directory. |
-| @HTTP_PROXY@ | URL for HTTP proxy server (see "Specifying Repositories":artifacts.html#specifying_repositories). |
+| @HTTP_PROXY@ | URL for HTTP proxy server (see "Specifying Repositories":artifacts.html#repositories). |
| @JAVA_HOME@ | Points to your JDK, required when using Java and Ant. |
| @JAVA_OPTS@ | Command line options to pass to the JDK (e.g. @'-Xms1g'@). |
| @M2_REPO@ | Location of the Maven2 local repository. Defaults to the @.m2@ directory in your home directory (@ENV['HOME']@). |
-| @NO_PROXY@ | Comma separated list of hosts and domain that should not be proxied (see "Specifying Repositories":artifacts.html#specifying_repositories). |
-| @TEST@ | Set to @no/off@ to tell Buildr to skip tests, or @all@ to tell Buildr to run all tests and ignore failures (see "Running Tests":testing.html#running_tests). |
+| @NO_PROXY@ | Comma separated list of hosts and domain that should not be proxied (see "Specifying Repositories":artifacts.html#repositories). |
+| @TEST@ | Set to @no/off@ to tell Buildr to skip tests, or @all@ to tell Buildr to run all tests and ignore failures (see "Running Tests":testing.html#running). |
| @USER@ | Tasks that need your user name, for example to log to remote servers, will use this environment variable. |
p(note). Buildr does not check any of the arguments in @JAVA_OPTS@. A common mistake is to pass an option like @mx512mb@, where it should be @Xmx512mb@. Make sure to double check @JAVA_OPTS@.
Some extensions may use additional environment variables, and of course, you can always add your own. This example uses two environment variables for specifying the username and password:
+<notextile>
{% highlight ruby %}
repositories.upload_to[:username] = ENV['USERNAME']
repositories.upload_to[:password] = ENV['PASSWORD']
{% endhighlight %}
-<!-- -->
+</notextile>
h2(#personal). Personal Settings
@@ -68,6 +75,7 @@
Here's an example @settings.yaml@:
+<notextile>
{% highlight yaml %}
# The repositories hash is read automatically by buildr.
repositories:
@@ -92,9 +100,11 @@
usr: notifier@company-jabber.com
pwd: secret
{% endhighlight %}
+</notextile>
Later your buildfile or addons can reference user preferences using the hash returned by the @Buildr.settings.user@ accessor.
+<notextile>
{% highlight ruby %}
task 'relase-notification' do
usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
@@ -102,7 +112,7 @@
jabber.msg("We are pleased to announce the last stable version #{VERSION}")
end
{% endhighlight %}
-<!-- -->
+</notextile>
h2(#build). Build Settings
@@ -111,6 +121,7 @@
They help keep the buildfile and build.yaml file simple and readable, working to the advantages of each one. Example for build settings are gems, repositories and artifacts used by that build.
+<notextile>
{% highlight yaml %}
# This project requires the following ruby gems, buildr addons
gems:
@@ -139,20 +150,24 @@
jira:
uri: https://jira.corp.org
{% endhighlight %}
+</notextile>
When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.
Artifacts defined on @build.yaml@ can be referenced on your buildfile by supplying the ruby symbol to the @Buildr.artifact@ and @Buildr.artifacts@ methods. The @compile.with@, @test.with@ methods can also be given these names.
+<notextile>
{% highlight ruby %}
define 'my_project' do
compile.with artifacts(:log4j, :j2ee)
test.with :spring, :j2ee
end
{% endhighlight %}
+</notextile>
Build settings can be retreived using the @Buildr.settings.build@ accessor.
+<notextile>
{% highlight ruby %}
task 'create_patch' do
patch = Git.create_patch :interactive => true
@@ -162,7 +177,7 @@
end
end
{% endhighlight %}
-<!-- -->
+</notextile>
h2(#variable). Non constant settings
@@ -173,14 +188,15 @@
Here's an example @buildr.rb@:
+<notextile>
{% highlight ruby %}
# Only I should know that
repositories.upload_to[:username] = 'assaf'
repositories.upload_to[:password] = 'supersecret'
# Search here first, it's faster
repositories.remote << 'http://inside-the-firewall'
-{% endhighlight %}
-<!-- -->
+{% endhighlight %}
+</notextile>
h2(#environments). Environments
@@ -189,29 +205,35 @@
So let's start by talking about the build environment. Buildr has a global attributes that indicates which environment it's running in, accessible from the @environment@ method. You can set the current build environment in one of two ways. Using the @-e/--environment@ command line option:
+<notextile>
{% highlight sh %}
$ buildr -e test
(in /home/john/project, test)
{% endhighlight %}
+</notextile>
Or by setting the environment variable @BUILDR_ENV@:
+<notextile>
{% highlight text %}
$ export BUILDR_ENV=production
$ buildr
(in /home/john/project, production)
{% endhighlight %}
+</notextile>
Unless you tell it otherwise, Buildr assumes you're developing and sets the environment to @development@.
Here's a simple example for handling different environments within the Buildfile:
+<notextile>
{% highlight ruby %}
project 'db-module' do
db = (environment == 'production' ? 'oracle' : 'hsql')
resources.from(_("src/main/#{db}"))
end
{% endhighlight %}
+</notextile>
We recommend picking a convention for your different environments and following it across all your projects. For example:
@@ -229,6 +251,7 @@
For example, to support three different database configurations, we could write:
+<notextile>
{% highlight yaml %}
# HSQL, don't bother storing to disk.
development:
@@ -245,9 +268,11 @@
db: oracle
jdbc: oracle:thin:@bigstrong:1521:mighty
{% endhighlight %}
+</notextile>
Here's a simple example for a buildfile that uses the profile information:
+<notextile>
{% highlight ruby %}
project 'db-module' do
# Copy SQL files specific for the database we're using,
@@ -257,6 +282,7 @@
resources.filter.using :jdbc=>Buildr.settings.profile['jdbc']
end
{% endhighlight %}
+</notextile>
The @profile@ method returns the current profile, selected based on the current "environment":#environments. You can get a list of all profiles by calling @profiles@.
@@ -266,6 +292,7 @@
YAML allows you to use anchors (@&@), similar to ID attributes in XML, reference the anchored element (@*@) elsewhere, and merge one element into another (@<<@). For example:
+<notextile>
{% highlight yaml %}
# We'll reference this one as common.
development: &common
@@ -278,6 +305,7 @@
<<: *common
jdbc: hsqldb:file:testdb
{% endhighlight %}
+</notextile>
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: buildr/trunk/doc/testing.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/testing.textile?rev=752671&r1=752670&r2=752671&view=diff
==============================================================================
--- buildr/trunk/doc/testing.textile (original)
+++ buildr/trunk/doc/testing.textile Wed Mar 11 22:43:22 2009
@@ -26,77 +26,97 @@
If you have a lot of tests that are failing or just hanging there collecting dusts, you can tell Buildr to ignore them. You can either tell Buildr to only run specific tests, for example:
+<notextile>
{% highlight ruby %}
test.include 'com.acme.tests.passing.*'
{% endhighlight %}
+</notextile>
Or tell it to exclude specific tests, for example:
+<notextile>
{% highlight ruby %}
test.exclude '*FailingTest', '*FailingWorseTest'
{% endhighlight %}
+</notextile>
Note that we're always using the package qualified class name, and you can use star (@*@) to substitute for any set of characters.
When tests fail, Buildr fails the @test@ task. This is usually a good thing, but you can also tell Buildr to ignore failures by resetting the @:fail_on_failure@ option:
+<notextile>
{% highlight ruby %}
test.using :fail_on_failure=>false
{% endhighlight %}
+</notextile>
Besides giving you a free pass to ignore failures, you can use it for other causes, for example, to be somewhat forgiving:
+<notextile>
{% highlight ruby %}
test do
fail 'More than 3 tests failed!' if test.failed_tests.size > 3
end
{% endhighlight %}
+</notextile>
The @failed_tests@ collection holds the names of all classes with failed tests. And there's @classes@, which holds the names of all test classes. Ruby arithmetic allows you to get the name of all passed test classes with a simple @test.classes â test.failed_tests@. We'll let you imagine creative use for these two.
-h2. Running Tests
+h2(#running). Running Tests
It's a good idea to run tests every time you change the source code, so we wired the @build@ task to run the @test@ task at the end of the build. And conveniently enough, the @build@ task is the default task, so another way to build changes in your code and run your tests:
+<notextile>
{% highlight sh %}
$ buildr
{% endhighlight %}
+</notextile>
That only works with the local @build@ task and any local task that depends on it, like @package@, @install@ and @upload@. Each project also has its own @build@ task that does not invoke the @test@ task, so @buildr build@ will run the tests cases, but @buildr foo:build@ will not.
While it's a good idea to always run your tests, it's not always possible. There are two ways you can get @build@ to not run the @test@ task. You can set the environment variable @test@ to @no@ (but @skip@ and @off@ will also work). You can do that when running Buildr:
+<notextile>
{% highlight sh %}
$ buildr test=no
{% endhighlight %}
+</notextile>
Or set it once in your environment:
+<notextile>
{% highlight sh %}
$ export TEST=no
$ buildr
{% endhighlight %}
+</notextile>
If you're feeling really adventurous, you can also disable tests from your Buildfile or @buildr.rb@ file, by setting @options.test = false@. We didn't say it's a good idea, we're just giving you the option.
The @test@ task is just smart enough to run all the tests it finds, but will accept include/exclude patterns. Often enough you're only working on one broken test and you only want to run that one test. Better than changing your Buildfile, you can run the @test@ task with a pattern. For example:
+<notextile>
{% highlight sh %}
$ buildr test:KillerAppTest
{% endhighlight %}
+</notextile>
Buildr will then run only tests that match the pattern @KillerAppTest@. It uses pattern matching, so @test:Foo@ will run @com.acme.FooTest@ and @com.acme.FooBarTest@. With Java, you can use this to pick a class name, or a package name to run all tests in that package, or any such combination. In fact, you can specify several patterns separated with commas. For example:
+<notextile>
{% highlight sh %}
$ buildr test:FooTest,BarTest
{% endhighlight %}
+</notextile>
As you probably noticed, Buildr will stop your build at the first test that fails. We think it's a good idea, except when it's not. If you're using a continuous build system, you'll want a report of all the failed tests without stopping at the first failure. To make that happen, set the environment variable @test@ to "all", or the Buildr @options.test@ option to @:all@. For example:
+<notextile>
{% highlight sh %}
$ buildr package test=all
{% endhighlight %}
+</notextile>
We're using @package@ and not @build@ above. When using a continuous build system, you want to make sure that packages are created, contain the right files, and also run the integration tests.
@@ -109,23 +129,29 @@
You write integration tests much the same way as you write unit tests, using @test.compile@ and @test.resources@. However, you need to tell Buildr that your tests will execute during integration test. To do so, add the following line in your project definition:
+<notextile>
{% highlight ruby %}
test.using :integration
{% endhighlight %}
+</notextile>
Typically you'll use unit tests in projects that create internal modules, such as JARs, and integration tests in projects that create components, such as WARs and EARs. You only need to use the @:integration@ option with the later.
To run integration tests on the current project:
+<notextile>
{% highlight sh %}
$ buildr integration
{% endhighlight %}
+</notextile>
You can also run specific tests cases, for example:
+<notextile>
{% highlight sh %}
$ buildr integration:ClientTest
{% endhighlight %}
+</notextile>
If you run the @package@ task (or any task that depends on it, like @install@ and @upload@), Buildr will first run the @build@ task and all its unit tests, and then create the packages and run the integration tests. That gives you full coverage for your tests and ready to release packages. As with unit tests, you can set the environment variable @test@ to "no" to skip integration tests, or "all" to ignore failures.
@@ -136,10 +162,12 @@
Integration tests run a setup task before the tests, and a teardown task afterwards. You can use this task to setup a Web server for testing your Web components, or a database server for testing persistence. You can access either task by calling @integration.setup@ and @integration.teardown@. For example:
+<notextile>
{% highlight ruby %}
integration.setup { server.start ; server.deploy }
integration.teardown { server.stop }
{% endhighlight %}
+</notextile>
Depending on your build, you may want to enhance the setup/teardown tasks from within a project, for example, to populate the database with data used by that project's test, or from outside the project definition, for example, to start and stop the Web server.
@@ -154,6 +182,7 @@
You use the @check@ method to express and expectation. Buildr will then run all these expectations against your project, and fail at the first expectation that doesn't match. An expectation says three things. Let's look at a few examples:
+<notextile>
{% highlight ruby %}
check package(:war), 'should exist' do
it.should exist
@@ -177,16 +206,19 @@
it.should exist
end
{% endhighlight %}
+</notextile>
The first argument is the subject, or the project if you skip the first argument. The second argument is the description, optional, but we recommend using it. The method @it@ returns the subject.
You can also write the first expectation like this:
+<notextile>
{% highlight ruby %}
check do
package(:jar).should exist
end
{% endhighlight %}
+</notextile>
We recommend using the subject and description, they make your build easier to read and maintain, and produce better error messages.
Modified: buildr/trunk/doc/troubleshooting.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/troubleshooting.textile?rev=752671&r1=752670&r2=752671&view=diff
==============================================================================
--- buildr/trunk/doc/troubleshooting.textile (original)
+++ buildr/trunk/doc/troubleshooting.textile Wed Mar 11 22:43:22 2009
@@ -10,10 +10,12 @@
You can give the JVM more heap space by setting the @JAVA_OPTS@ environment variables. This environment variable provides arguments for staring the JVM. For example, to set the heap space to 1GB:
+<notextile>
{% highlight sh %}
$ export "JAVA_OPTS=-Xms1g -Xmx1g"
$ buildr compile
{% endhighlight %}
+</notextile>
If you're sharing the build with other developers, you'll want to specify these options in the Buildfile itself. You can set the environment variable within the Buildfile, but make sure to do so at the very top of the Buildfile.
@@ -61,10 +63,12 @@
Ruby statements don't need a delimiter and can span multiple lines, which can lead to bugs resulting from dangling commas and periods left at the end of the line. For example:
+<notextile>
{% highlight ruby %}
compile.with 'org.apache.axis2:axis2:jar:1.2',
test.with 'log4j:log4j:jar:1.1'
{% endhighlight %}
+</notextile>
This is actually a single method call with two arguments, separated by a comma. The second argument is the result of calling @test.with@, and makes the test task a pre-requisite of the compile task, leading to a circular dependency.
@@ -105,9 +109,11 @@
The culprit is having the Gem's binary directory show up in @RUBYLIB@. For example, Buildr's @bin/buildr@ includes this line:
+<notextile>
{% highlight sh %}
require 'buildr'
{% endhighlight %}
+</notextile>
Under normal circumstances, this tells RubyGems to load @buildr.rb@ from the Gem's library directory. When @RUBYLIB@ points to the Gem's @bin@ directory, it ends up loading itself repeatedly.
Modified: buildr/trunk/doc/whats_new.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/whats_new.textile?rev=752671&r1=752670&r2=752671&view=diff
==============================================================================
--- buildr/trunk/doc/whats_new.textile (original)
+++ buildr/trunk/doc/whats_new.textile Wed Mar 11 22:43:22 2009
@@ -11,7 +11,7 @@
* Starting with this release you can use the @build.yml@ file to control versions of various 3rd party libraries, e.g. Ant, JUnit, ScalaCheck.
* The _release_ task now supports alternative SVN repository layouts. Releases are tagged in SVN using the version number, but you can customize the tag name (see @Releases.tag_name@). The @NEXT_VERSION@ constant is no longer used during the release process.
* This release is tested against JRuby 1.1.3 and JRuby 1.1.4. There are also some improvements towards Ruby 1.9 support.
-* 27 other bug fixes and minor changes, see the "CHANGELOG":changelog.html for full details.
+* 27 other bug fixes and minor changes, see the "CHANGELOG":CHANGELOG for full details.
h2(#1.3.2). Buildr 1.3.2
@@ -87,7 +87,7 @@
Since this package is not an artifact and does not have a specification, it will not automatically install itself in the local repository or upload to a remote repository. For these, use the @package@ method as before.
-Read more about "the package method":packaging.html#specifying_and_referencing_packages.
+Read more about "the package method":packaging.html#referencing.
h3. Packaging EARs
@@ -113,15 +113,13 @@
* *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.
-"Read more ...":packaging.html#packaging_ears
+"Read more ...":packaging.html#ear
h3. JRuby Support
We now offer two versions of Buildr, one for Ruby and one for JRuby. They're exactly the same, except the Ruby version will also install RJB (Ruby Java Bridge), the JRuby version obviously can do well without it.
-"Read more ...":download.html#jruby
-
Buildr provides a "Nailgun":http://www.martiansoftware.com/nailgun/index.html server when running on JRuby. Using the integrated BuildrServer allows for faster task execution and avoid frequent JVM startup overhead.
"Read more ...":more_stuff.html#nailgun
@@ -197,7 +195,7 @@
pwd: secret
{% endhighlight %}
-"Read more ...":settings_profiles.html#personal_settings
+"Read more ...":settings_profiles.html#personal
Build settings are placed in the @build.yaml@ file located in the same directory that the @buildfile@. Normally this file would be managed by the project revision control system, so settings here are shared between developers.
@@ -224,7 +222,7 @@
uri: https://jira.corp.org
{% endhighlight %}
-"Read more ...":settings_profiles.html#build_settings
+"Read more ...":settings_profiles.html#build
h3. Using Gems for extensions and 3rd party libraries
@@ -233,7 +231,7 @@
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:
+Use the @build.yaml@ file to specify these dependencies (see "Build Settings":settings_profiles.html#build for more information), for example:
{% highlight yaml %}
# This project requires the following gems
@@ -245,7 +243,7 @@
- ci_reporter
{% endhighlight %}
-"Read more ...":more_stuff.html#using_gems
+"Read more ...":more_stuff.html#gems
h3. New API for accessing Java libraries
@@ -271,7 +269,7 @@
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.
-"Read more ...":more_stuff.html#using_java_libraries
+"Read more ...":more_stuff.html#java
h3. Creating Extensions
@@ -294,7 +292,7 @@
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.
-"Read more ...":extending.html#creating_extensions
+"Read more ...":extending.html#extensions
h3. Using Alternative Layouts
@@ -303,7 +301,7 @@
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.
-"Read more ...":extending.html#using_alternative_layouts
+"Read more ...":extending.html#layouts
h3. Other