buildr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From as...@apache.org
Subject svn commit: r752671 [2/2] - in /buildr/trunk/doc: ./ _layouts/
Date Wed, 11 Mar 2009 22:43:23 GMT
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



Mime
View raw message