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/02/15 21:09:06 UTC
svn commit: r628155 - in /incubator/buildr/trunk/doc/pages:
artifacts.textile building.textile contributing.textile download.textile
getting_started.textile index.textile packaging.textile
settings_profiles.textile testing.textile
Author: assaf
Date: Fri Feb 15 12:09:05 2008
New Revision: 628155
URL: http://svn.apache.org/viewvc?rev=628155&view=rev
Log:
Now with tables and .tip/.note
Modified:
incubator/buildr/trunk/doc/pages/artifacts.textile
incubator/buildr/trunk/doc/pages/building.textile
incubator/buildr/trunk/doc/pages/contributing.textile
incubator/buildr/trunk/doc/pages/download.textile
incubator/buildr/trunk/doc/pages/getting_started.textile
incubator/buildr/trunk/doc/pages/index.textile
incubator/buildr/trunk/doc/pages/packaging.textile
incubator/buildr/trunk/doc/pages/settings_profiles.textile
incubator/buildr/trunk/doc/pages/testing.textile
Modified: incubator/buildr/trunk/doc/pages/artifacts.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/artifacts.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/artifacts.textile (original)
+++ incubator/buildr/trunk/doc/pages/artifacts.textile Fri Feb 15 12:09:05 2008
@@ -62,9 +62,9 @@
:under=>'org.apache.ws.commons.axiom', :version=>'1.2.4')
}}}
-*Note:* Buildr projects also define a @group@ attribute which can lead to some
-confusion. If you want to define an artifact group within a project definition,
-you should use the explicit qualifier @Buildr::group@.
+p(note). Buildr projects also define a @group@ attribute which can lead to
+some confusion. If you want to define an artifact group within a project
+definition, you should use the explicit qualifier @Buildr::group@.
If you have several artifacts you always use together, consider placing them in
an array. Methods that accept lists of artifacts also accept arrays. For
Modified: incubator/buildr/trunk/doc/pages/building.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/building.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/building.textile (original)
+++ incubator/buildr/trunk/doc/pages/building.textile Fri Feb 15 12:09:05 2008
@@ -208,17 +208,18 @@
The Java compiler supports the following options:
-* @:debug@ -- Generates bytecode with debugging information. You can also
-override this by setting the environment variable @debug@ to @off@.
-* @:deprecation@ -- If true, shows deprecation messages. False by default.
-* @:lint@ -- Defaults to false. Set this option to true to use all lint
-options, or specify a specific lint option (e.g. @:lint=>'cast'@).
-* @:other@ -- Array of options passed to the compiler (e.g.
-@:other=>'-implicit:none'@).
-* @:source@ -- Source code compatibility (e.g. '1.5').
-* @:target@ -- Bytecode compatibility (e.g. '1.4').
-* @:warnings@ -- Issue warnings when compiling. True when running in verbose
-mode.
+|_. Option |_. Usage |
+| @:debug@ | Generates bytecode with debugging information. You can
+also override this by setting the environment variable @debug@ to @off@. |
+| @:deprecation@ | If true, shows deprecation messages. False by default. |
+| @:lint@ | Defaults to false. Set this option to true to use all lint
+options, or specify a specific lint option (e.g. @:lint=>'cast'@). |
+| @:other@ | Array of options passed to the compiler (e.g.
+@:other=>'-implicit:none'@). |
+| @:source@ | Source code compatibility (e.g. '1.5'). |
+| @:target@ | Bytecode compatibility (e.g. '1.4'). |
+| @:warnings@ | Issue warnings when compiling. True when running in
+verbose mode. |
h3. Compiling Scala
@@ -240,16 +241,18 @@
The Scala compiler supports the following options:
-* @:debug@ -- Generates bytecode with debugging information. You can also
-override this by setting the environment variable @debug@ to @off@.
-* @:deprecation@ -- If true, shows deprecation messages. False by default.
-* @:optimise@ -- Generates faster bytecode by applying optimisations to the program.
-* @:other@ -- Array of options passed to the compiler (e.g.
-@:other=>'-Xprint-types'@).
-* @:source@ -- Source code compatibility (e.g. '1.5').
-* @:target@ -- Bytecode compatibility (e.g. '1.4').
-* @:warnings@ -- Issue warnings when compiling. True when running in verbose
-mode.
+|_. Option |_. Usage |
+| @:debug@ | Generates bytecode with debugging information. You can
+also override this by setting the environment variable @debug@ to @off@. |
+| @:deprecation@ | If true, shows deprecation messages. False by default. |
+| @:optimise@ | Generates faster bytecode by applying optimisations to the
+program. |
+| @:other@ | Array of options passed to the compiler (e.g.
+@:other=>'-Xprint-types'@). |
+| @:source@ | Source code compatibility (e.g. '1.5'). |
+| @:target@ | Bytecode compatibility (e.g. '1.4'). |
+| @:warnings@ | Issue warnings when compiling. True when running in verbose
+mode. |
You may use @fsc@, the Fast Scala Compiler, which submits compilation jobs to a
compilation daemon, by setting the environment variable @USE_FSC@ to @yes@. Note
@@ -265,9 +268,10 @@
}}}
Once loaded, the groovyc compiler will be automatically selected if any .groovy
-source files are found under @src/main/groovy@ directory, compiling them by
+source files are found under @src/main/groovy@ directory, compiling them by
default into the @target/classes@ directory.
-If the project has java sources in @src/main/java@ they will get compiled using
+
+If the project has java sources in @src/main/java@ they will get compiled using
the groovyc joint compiler.
Sources found in @src/test/groovy@ are compiled into the @target/test/classes@.
@@ -275,28 +279,34 @@
If you don't specify the packaging type, it defaults to JAR.
The Groovy compiler supports the following options:
- * @encoding@ -- Encoding of source files
- * @verbose@ -- Asks the compiler for verbose output, true when running in
- verbose mode.
- * @fork@ -- Whether to execute groovyc using a spawned instance of the JVM;
- defaults to no
- * @memoryInitialSize@ -- The initial size of the memory for the underlying VM,
- if using fork mode; ignored otherwise.
- Defaults to the standard VM memory setting. (Examples: 83886080, "81920k", or "80m")
- * @memoryMaximumSize@ -- The maximum size of the memory for the underlying VM,
- if using fork mode; ignored otherwise.
- Defaults to the standard VM memory setting. (Examples: 83886080, "81920k", or "80m")
- * @listfiles@ -- Indicates whether the source files to be compiled will be listed;
- defaults to no
- * @stacktrace@ -- If true each compile error message will contain a stacktrace
- * @warnings@ -- Issue warnings when compiling. True when running in verbose mode.
- * @debug@ -- Generates bytecode with debugging information. Set from the debug
- environment variable/global option.
- * @deprecation@ -- If true, shows deprecation messages. False by default.
- * @optimise@ -- Generates faster bytecode by applying optimisations to the program.
- * @source@ -- Source code compatibility.
- * @target@ -- Bytecode compatibility.
- * @javac@ -- Hash of options passed to the ant javac task
+
+|_. Option |_. Usage |
+| @encoding@ | Encoding of source files. |
+| @verbose@ | Asks the compiler for verbose output, true when running
+in verbose mode. |
+| @fork@ | Whether to execute groovyc using a spawned instance of
+the JVM. Defaults to no. |
+| @memoryInitialSize@ | The initial size of the memory for the underlying VM,
+if using fork mode, ignored otherwise. Defaults to the standard VM memory
+setting. (Examples: @83886080@, @81920k@, or @80m@) |
+| @memoryMaximumSize@ | The maximum size of the memory for the underlying VM,
+if using fork mode, ignored otherwise. Defaults to the standard VM memory
+setting. (Examples: @83886080@, @81920k@, or @80m@) |
+| @listfiles@ | Indicates whether the source files to be compiled will
+be listed. Defaults to no. |
+| @stacktrace@ | If true each compile error message will contain a
+stacktrace. |
+| @warnings@ | Issue warnings when compiling. True when running in
+verbose mode. |
+| @debug@ | Generates bytecode with debugging information. Set
+from the debug environment variable/global option. |
+| @deprecation@ | If true, shows deprecation messages. False by default.
+|
+| @optimise@ | Generates faster bytecode by applying optimisations to
+the program. |
+| @source@ | Source code compatibility. |
+| @target@ | Bytecode compatibility. |
+| @javac@ | Hash of options passed to the ant javac task. |
h2. Resources
@@ -319,11 +329,12 @@
You can specify a different format by passing it as the first argument.
Supported formats include:
-* @:ant@ -- Map from <code>@key@</code> to value.
-* @:maven@ -- Map from @${key}@ to value (default).
-* @:ruby@ -- Map from @#{key}@ to value.
-* @Regexp@ -- Map using the matched value of the regular expression (e.g.
-@/=(.*?)=/@).
+|_. Format |_. Usage |
+| @:ant@ | Map from <code>@key@</code> to value. |
+| @:maven@ | Map from @${key}@ to value (default). |
+| @:ruby@ | Map from @#{key}@ to value. |
+| @Regexp@ | Map using the matched value of the regular expression (e.g.
+@/=(.*?)=/@). |
For example, using the @:ruby@ format instead of the default @:maven@ format:
@@ -425,10 +436,11 @@
Much better. We're using the same task twice, but since we're using Rake here,
it will only execute once. In fact, it will only execute if we don't already
have a Derby database, or if it detects a change to the SQL file and needs to
-recreate the database. (Note: @Derby.create@ is not part of Buildr, you can
-get
+recreate the database.
+
+p(tip). @Derby.create@ is not part of Buildr, you can get
"derby.rake":http://svn.apache.org/repos/asf/incubator/ode/trunk/tasks/derby.rake
-here).
+here.
Here's another example. We want to copy some files over as part of the build,
and apply a filter to them. This time, we're going to extend the @build@ task:
Modified: incubator/buildr/trunk/doc/pages/contributing.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/contributing.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/contributing.textile (original)
+++ incubator/buildr/trunk/doc/pages/contributing.textile Fri Feb 15 12:09:05 2008
@@ -159,7 +159,8 @@
Here is the list of people who are actively working and committing on Buildr:
-|_.Name |_.ID |_.Organization |_. Role |
-| Assaf Arkin | assaf | "Intalio":http://intalio.com | Developer & PMC |
-| Alex Boisvert | boisvert | "Intalio":http://intalio.com | Developer & PMC |
-| Matthieu Riou | mriou | "Intalio":http://intalio.com | Developer & PMC Chair |
+|_.Name |_.ID |_.Organization |_. Role |
+| Assaf Arkin | assaf | "Intalio":http://intalio.com | Developer & PMC |
+| Alex Boisvert | boisvert | "Intalio":http://intalio.com | Developer & PMC |
+| Matthieu Riou | mriou | "Intalio":http://intalio.com | Developer & PMC Chair |
+| Victor Hugo Borja | vborja | | Developer |
Modified: incubator/buildr/trunk/doc/pages/download.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/download.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/download.textile (original)
+++ incubator/buildr/trunk/doc/pages/download.textile Fri Feb 15 12:09:05 2008
@@ -1,14 +1,15 @@
h1. Download and Installation
-The current release of Buildr works with Ruby 1.8 and JRuby 1.1RC1. We do not
-yet support Ruby 1.9 yet.
-
The installation instructions are slightly different for each operating system.
If you are using Ruby, pick the one that best matches your operating system.
If you are using JRuby, see the instructions for "JRuby":#jruby and also read
about using "JRuby and Ruby side by side":#using_jruby_and_ruby.
-
+
+p(note). The current release of Buildr works with Ruby 1.8 and JRuby 1.1RC1.
+We do not yet support Ruby 1.9 yet.
+
+
h2. Linux, BSD, Cygwin
To get started you will need a recent version of Ruby, Ruby Gems and build
Modified: incubator/buildr/trunk/doc/pages/getting_started.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/getting_started.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/getting_started.textile (original)
+++ incubator/buildr/trunk/doc/pages/getting_started.textile Fri Feb 15 12:09:05 2008
@@ -2,7 +2,7 @@
h2. Installing Buildr
-More information about "downloading and installing Buildr":downloading.html.
+More information about "downloading and installing Buildr":download.html.
h2. Conventions
@@ -33,12 +33,17 @@
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[1]:
+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.
+
You use Buildr by running the @buildr@ command:
{{{!sh
@@ -115,17 +120,21 @@
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. More Info
-
-*API* The "Buildr API":http://incubator.apache.org/buildr/rdoc/index.html 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.
+h2. More Info
+*API* The "Buildr API":http://incubator.apache.org/buildr/rdoc/index.html
+documentation.
-fn1. 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.
+*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=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/index.textile (original)
+++ incubator/buildr/trunk/doc/pages/index.textile Fri Feb 15 12:09:05 2008
@@ -40,9 +40,11 @@
Check out "what's new in Buildr 1.3":whats_new.html.
-h4. Disclaimer
+p(tip). 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
+p(note). 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
Modified: incubator/buildr/trunk/doc/pages/packaging.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/packaging.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/packaging.textile (original)
+++ incubator/buildr/trunk/doc/pages/packaging.textile Fri Feb 15 12:09:05 2008
@@ -26,8 +26,13 @@
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[1].
+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. Packaging JARs
@@ -172,7 +177,7 @@
}}}
If you need to use the @:path@ option repeatedly, consider using the @path@
-method instead. For example[2]:
+method instead. For example:
{{{!ruby
package(:zip).path("#{id}-#{version}").tap do |path|
@@ -181,7 +186,11 @@
end
}}}
-*Note:* To allow you to spread files across different paths, the
+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.
@@ -483,7 +492,7 @@
You can get all the packages created by a project and filter them yourself.
Let's illustrate that with an example that prints artifact specifications for
-all the packages we generate through our projects[3]:
+all the packages we generate through our projects:
{{{!ruby
puts projects.map(&:packages).flatten.map(&:to_spec).join(', ')
@@ -491,6 +500,11 @@
acme:killer-app-teh-impl:jar:1.0, acme:killer-app-la-web:war:1.0
}}}
+p(tip). The @map@ method takes an array, runs the block with each item, and
+returns a new array. The @&:@ shortcut is not a standard part of Ruby but a
+useful convenience that calls this method on each instance. So
+@map(&:packages)@ is just a shorter way of saying @map { |obj| obj.packages }@.
+
Now reduce it to only use the JAR packages:
{{{!ruby
@@ -561,19 +575,3 @@
We packaged the code, but will it actually work? Let's see "what the tests
say":testing.html.
-
-
-fn1. 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.
-
-fn2. 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.
-
-fn3. The @map@ method takes an array, runs the block with each item, and
-returns a new array. The @&:@ shortcut is not a standard part of Ruby but a
-useful convenience that calls this method on each instance. So
-@map(&:packages)@ is just a shorter way of saying @map { |obj| obj.packages }@.
Modified: incubator/buildr/trunk/doc/pages/settings_profiles.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/settings_profiles.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/settings_profiles.textile (original)
+++ incubator/buildr/trunk/doc/pages/settings_profiles.textile Fri Feb 15 12:09:05 2008
@@ -34,9 +34,13 @@
ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
}}}
-Make sure to set any environment variables at the very top of the Buildfile[1],
+Make sure to set any environment variables at the very top of the Buildfile,
above any Ruby statement (even @require@).
+p(tip). Using @||=@ sets the environment variable, if not already set, so
+it's still possible for other developers to override this environment variable
+without modifying the Buildfile.
+
Buildr supports the following environment variables:
|_. Variable |_. Description |
@@ -49,8 +53,7 @@
| @HTTP_PROXY@ | URL for HTTP proxy server (see "Specifying
Repositories":artifacts.html#specifying_repositories). |
| @JAVA_HOME@ | Points to your JDK, required when using Java and Ant. |
-| @JAVA_OPTS@ | Command line options to pass to the JDK[2] (e.g.
-@'-Xms1g'@). |
+| @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
@@ -61,6 +64,10 @@
| @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:
@@ -219,12 +226,3 @@
You can "learn more about YAML here":http://www.yaml.org, and use this
handy "YAML quick reference":http://www.yaml.org/refcard.html.
-
-
-fn1. Using @||=@ sets the environment variable, if not already set, so it's
-still possible for other developers to override this environment variable
-without modifying the Buildfile.
-
-fn2. 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@.
Modified: incubator/buildr/trunk/doc/pages/testing.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/testing.textile?rev=628155&r1=628154&r2=628155&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/testing.textile (original)
+++ incubator/buildr/trunk/doc/pages/testing.textile Fri Feb 15 12:09:05 2008
@@ -358,7 +358,7 @@
a path in a ZIP file, checking its contents as if it was a directory, or
against an entry in a ZIP file, checking the content of that file.
-*Note:* The @package@ method returns a package task based on packaging type,
+p(note). The @package@ method returns a package task based on packaging type,
identifier, group, version and classifier. The last four are inferred, but if
you create a package with different specifications (for example, you specify a
classifier) your checks must call @package@ with the same qualifying arguments