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/02 05:57:29 UTC
svn commit: r617749 - in /incubator/buildr/trunk/doc: ./ pages/
Author: assaf
Date: Fri Feb 1 20:57:25 2008
New Revision: 617749
URL: http://svn.apache.org/viewvc?rev=617749&view=rev
Log:
Documentation for settings and profiles
Modified:
incubator/buildr/trunk/doc/pages/download.textile
incubator/buildr/trunk/doc/pages/extending.textile
incubator/buildr/trunk/doc/pages/getting_started.textile
incubator/buildr/trunk/doc/pages/more_stuff.textile
incubator/buildr/trunk/doc/pages/recipes.textile
incubator/buildr/trunk/doc/pages/testing.textile
incubator/buildr/trunk/doc/pages/troubleshooting.textile
incubator/buildr/trunk/doc/pages/whats_new.textile
incubator/buildr/trunk/doc/print.toc.yaml
incubator/buildr/trunk/doc/web.toc.yaml
Modified: incubator/buildr/trunk/doc/pages/download.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/download.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/download.textile (original)
+++ incubator/buildr/trunk/doc/pages/download.textile Fri Feb 1 20:57:25 2008
@@ -179,6 +179,14 @@
$ sudo gem install buildr -v 1.3.0
}}}
+When using JRuby you will notice that Buildr takes a few seconds to start up.
+To speed it up, we recommend switching to Java 1.6 and running the JVM in
+client mode:
+
+{{{!
+$ export JAVA_OPTS=-client
+}}}
+
h2. Using JRuby and Ruby
Modified: incubator/buildr/trunk/doc/pages/extending.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/extending.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/extending.textile (original)
+++ incubator/buildr/trunk/doc/pages/extending.textile Fri Feb 1 20:57:25 2008
@@ -151,53 +151,6 @@
}}}
-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.
-
-Java classes are accessed as static methods on the @Java@ module, for example:
-
-{{{!ruby
-str = Java.java.lang.String.new('hai!')
-str.toUpperCase
-=> 'HAI!'
-Java.java.lang.String.isInstance(str)
-=> true
-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.
-
-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:
-
-{{{!ruby
-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.
-
-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.
-# Check on a clean build with empty local repository.
-
-
h2. Using Alternative Layouts
Buildr follows a common convention for project layouts: Java source files
Modified: incubator/buildr/trunk/doc/pages/getting_started.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/getting_started.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/getting_started.textile (original)
+++ incubator/buildr/trunk/doc/pages/getting_started.textile Fri Feb 1 20:57:25 2008
@@ -42,21 +42,78 @@
You use Buildr by running the @buildr@ command:
{{{!sh
-buildr [-f buildfile] {options} targets...
+$ buildr [options] [tasks] [name=value]
}}}
There are several options you can use, for a full list of options type:
{{{!sh
-buildr --help
+$ buildr --help
}}}
-Once you have a Buildfile ready, you can find out even more information by
-running the _help_ task:
+|_. Option |_. Description |
+| @-f/--buildfile [file]@ | Specify the buildfile. |
+| @-e/--environment [name]@ | Environment name (e.g. development, test, production). |
+| @-h/--help@ | Display this help message. |
+| @-n/--nosearch@ | Do not search parent directories for the buildfile. |
+| @-q/--quiet@ | Do not log messages to standard output. |
+| @-r/--require [file]@ | Require MODULE before executing buildfile. |
+| @-t/--trace@ | Turn on invoke/execute tracing, enable full backtrace. |
+| @-v/--version@ | Display the program version. |
+
+You can tell Buildr to run specific tasks and the order to run them. For
+example:
+
+{{{!sh
+# Clean and rebuild
+buildr clean build
+# Package and install
+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.
+
+For example:
{{{!sh
-buildr help
+$ export JAVA_OPTS='-Xms1g -Xmx1g'
+$ buildr TEST=no
}}}
+
+
+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.
+
+To start with, type:
+
+{{{!sh
+$ buildr help
+}}}
+
+You can list the name and description of all your projects using the
+@help:projects@ task. For example:
+
+{{{!sh
+$ buildr help:projects
+killer-app # Code. Build. ??? Profit!
+killer-app:teh-api # Abstract classes and interfaces
+killer-app:teh-impl # All those implementation details
+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.
h2. More Info
Modified: incubator/buildr/trunk/doc/pages/more_stuff.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/more_stuff.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/more_stuff.textile (original)
+++ incubator/buildr/trunk/doc/pages/more_stuff.textile Fri Feb 1 20:57:25 2008
@@ -1,215 +1,51 @@
h1. More Stuff
-h2. Help Tasks
+h2. Using Java Libraries
-Buildr includes a number of informative tasks. Currently that number stands
-at two, but we'll be adding more tasks in future releases.
+Buildr runs along side a JVM, using either RJB or JRuby. The Java module
+allows you to access Java classes and create Java objects.
-To start with, type:
-
-{{{!sh
-$ buildr help
-}}}
-
-You can list the name and description of all your projects using the
-@help:projects@ task. For example:
-
-{{{!sh
-$ buildr help:projects
-killer-app # Code. Build. ??? Profit!
-killer-app:teh-api # Abstract classes and interfaces
-killer-app:teh-impl # All those implementation details
-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.
-
-
-h2. Environment and Personal Settings
-
-In many cases you will want to customize your build to deal with different
-environments and configurations, customize how it runs on your machine, and
-even control the build each time you run the @buildr@ command. The following
-sections will show you how to do that.
-
-
-h4. Environments
-
-One common use case is adapting the build to different environments. For
-example, to compile code with debugging information during development and
-testing, but strip it for production. Another example is using different
-databases for development, testing and production, or using services at
-different URLs.
-
-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@ command line option:
-
-{{{!sh
-$ buildr -e test
-(in /home/john/project, test)
-}}}
-
-Or by setting the environment variable @BUILDR_ENV@:
-
-{{{!
-$ export BUILDR_ENV=production
-$ buildr
-(in /home/john/project, production)
-}}}
-
-The default environment is "development".
-
-Here's a simple example for handling different environments within the
-Buildfile:
-
-{{{!ruby
-project 'db-module' do
- db = (environment == 'production' ? 'oracle' : 'hsql')
- resources.from(_(:source, :main, db))
-end
-}}}
-
-
-h4. Profiles
-
-Different environments may require different configurations, and you can handle
-a lot of that by using the profile file. The profile file is a YAML file
-called @profile.yaml@ that you place in the same directory as the Buildfile.
-We selected YAML because it's easier to read and edit than XML.
-
-For example, to support three different database configurations, we could write:
-
-{{{!yaml
-development:
- db: hsql
-test:
- db: oracle
-production:
- db: oracle
-}}}
-
-And change the Buildfile to use the profile:
+Java classes are accessed as static methods on the @Java@ module, for example:
{{{!ruby
-project 'db-module' do
- db = profile['db']
- resources.from(_(:source, :main, db))
-end
+str = Java.java.lang.String.new('hai!')
+str.toUpperCase
+=> 'HAI!'
+Java.java.lang.String.isInstance(str)
+=> true
+Java.com.sun.tools.javac.Main.compile(args)
}}}
-The @profile@ method returns a profile that matches the current environment.
-For the development environment, it returns a hash with the name/value pair
-@'db'=>'hsql'@.
-
-You can "learn more about YAML here":http://www.yaml.org, and use this handy
-"YAML quick reference":http://www.yaml.org/refcard.html.
-
-
-h4. Personal Settings
-
-Some things clearly do not belong in the Buildfile. For example, the
-username/password you use to upload releases. If you're working in a team or
-on an open source project, you'd want to keep these in a separate place.
-
-You may want to use personal settings for picking up a different location for
-the local repository, or use a different set of preferred remote repositories,
-and so forth.
-
-Before loading the Buildfile, Buildr will attempt to load two @buildr.rb@
-files. First, the @buildr.rb@ file it finds in your home directory, and then
-the @buildr.rb@ file it finds in the build directory. That order is important,
-it allows you to place global settings that affect all your builds in your home
-directory's @buildr.rb@, but also over-ride those with settings for a given
-project.
-
-Here's an example @buildr.rb@:
-
-{{{!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'
-}}}
-
-
-h4. Environment Variables
-
-Buildr uses several environment variables that help you control how it works.
-Environment variables are used in addition to profiles and personal settings in
-two cases:
-
-* When you need to control the build from the command line, for example,
-specifying the build environment using @BUILDR_ENV@, or skipping tests using
-@test=no@.
+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.
-* For commonly used environment variables, such as @JAVA_HOME@, @JAVA_OPTS@ and
-@HTTP_PROXY@.
+When using an artifact specification, Buildr will automatically download and
+install the artifact before adding it to the classpath.
-Some environment variables you will only set once or change infrequently.
-Other environment variables may change more often, for example, running a build
-with different versions of the JDK, or disabling tests. You can change these
-variables when running Buildr by adding @name=value@ as a command line argument.
-
-For example:
-
-{{{!sh
-$ buildr test=no
-}}}
-
-You can also change environment variables from within the Buildfile. For
-example, if your build needs more JVM heap space than the default, you can add
-a line like this to your Buildfile:
+For example, Ant is loaded as follows:
{{{!ruby
-# This project builds a lot of code.
-ENV['JAVA_OPTS'] = '-Xms1g -Xmx1g'
+Java.classpath << 'org.apache.ant:ant:jar:1.7.0'
}}}
-Make sure to set environment variables at the very top of the Buildfile, above
-any @requires@ or other Ruby statements.
-
-Buildr uses the following environment variables.
-
-*BUILDR_ENV* -- Environment name that you can also set using the @-e@ command
-line option.
-
-*DEBUG* -- Set to @off@ if you want Buildr to compile without debugging
-information (default when running @release@, see
-"Compiling":building.html#compiling).
+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.
-*HTTP_PROXY* -- URL for HTTP proxy server (see "Specifying
-Repositories":artifacts.html#specifying_repositories).
+When building an extension, make sure to follow these rules:
-*JAVA_HOME* -- Points to your JDK, required for running Buildr.
-
-*JAVA_OPTS/JAVA_OPTIONS* -- Command line options to pass to the JDK (e.g.
-@'-Xms1g'@)[1].
-
-*NO_PROXY* -- Comma separated list of hosts and domain that should not be
-proxied (see "Specifying
-Repositories":artifacts.html#specifying_repositories).
-
-*TEST* -- Set to @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).
-
-*USER* -- Tasks that need your user name, for example to log to remote serers,
-will use this environment variable.
-
-If you need to, you can always use more environment variables. This example
-uses two environment variables for specifying the username and password for
-uploading artifacts:
-
-{{{!ruby
-repositories.upload_to[:username] = ENV['USERNAME']
-repositories.upload_to[:password] = ENV['PASSWORD']
-}}}
+# 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. Eclipse, IDEA
@@ -359,4 +195,3 @@
}}}
-fn1. 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/recipes.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/recipes.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/recipes.textile (original)
+++ incubator/buildr/trunk/doc/pages/recipes.textile Fri Feb 1 20:57:25 2008
@@ -3,7 +3,7 @@
Commond recipes for Buildr, collected from the mailing list.
-h4. Creating a classpath
+h2. Creating a classpath
For Java, the classpath argument is simply a list of paths joined with an
OS-specific path separator:
@@ -43,11 +43,11 @@
}}}
-h4. Keeping your Profiles.yaml file DRY
+h2. Keeping your Profiles.yaml file DRY
-YAML allows you to write an object (map, array, etc) once and reference it in
-several places using anchors and aliases (@&@ and @*@). For example, if you
-have several profiles, all with the same information, you can write this:
+YAML allows you to use anchors (@&@), similar to ID attributes in XML, and
+reference them later on (@*@). For example, if you have two profiles that are
+identical, you can tell YAML that one is an alias for the other:
{{{!yaml
development: &common
@@ -57,22 +57,31 @@
production: *common
}}}
-You can use the merge key (@<<@) to create a name/value map that merges default
-values from another name/value map, for example:
+If you have two elements that are almost identical, you can merge the values of
+one element into another (@<<@), for example:
{{{!yaml
-common: &common
- db: oracle
- port: 8080
-development:
- <<: *common
+development: &common
db: hsql
-test: *common
-production: *common
+ jdbc: hsqldb:mem:devdb
+test:
+ <<: *common
+ jdbc: hsqldb:file:testdb
+}}}
+
+
+h2. Speeding JRuby
+
+When using JRuby you will notice that Buildr takes a few seconds to start up.
+To speed it up, we recommend switching to Java 1.6 and running the JVM in
+client mode:
+
+{{{!
+$ export JAVA_OPTS=-client
}}}
-h4. Continuous Integration with Atlassian Bamboo
+h2. Continuous Integration with Atlassian Bamboo
This recipe outlines how to configure a new Bamboo project to use Buildr. The
following steps assume that you have logged-on to Bamboo as an Administrator.
Modified: incubator/buildr/trunk/doc/pages/testing.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/testing.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/testing.textile (original)
+++ incubator/buildr/trunk/doc/pages/testing.textile Fri Feb 1 20:57:25 2008
@@ -163,7 +163,7 @@
$ buildr test=no
}}}
-Or set it once in your environment[1]:
+Or set it once in your environment:
{{{!sh
$ export TEST=no
@@ -364,19 +364,10 @@
classifier) your checks must call @package@ with the same qualifying arguments
to return the very same package task.
-Buildr expectations are based on RSpec. Check the RSpec documentation if want
-to see all the supported matchers, or want to write your own.
+Buildr expectations are based on RSpec. "RSpec":http://rspec.info/ is the
+behavior-driven development framework we use to test Buildr itself. Check the
+RSpec documentation if want to see all the supported matchers, or want to write
+your own.
-We're almost done, but there's "a few more things":more_stuff.html you'll want
-to learn.
-
-
-fn1. When Buildr sees @foo=bar@ on the command line, it sets the environment
-variable @foo@ to the value "bar". Environment variables are available from
-the @ENV@ global variable and are case sensitive. You can use that to other
-effects, for example, you can use an environment variable called build with
-values like "dev", "stage", "deploy" to change how your build works in
-different settings.
-
-fn2. "RSpec":http://rspec.info/ is the behavior-driven development
-framework we use to test Buildr itself.
+Next, let's talk about "customizing your environment and using
+profiles":settings_profiles.html
Modified: incubator/buildr/trunk/doc/pages/troubleshooting.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/troubleshooting.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/troubleshooting.textile (original)
+++ incubator/buildr/trunk/doc/pages/troubleshooting.textile Fri Feb 1 20:57:25 2008
@@ -3,7 +3,7 @@
Common troubleshooting tips collected from the mailing list.
-h4. Running out of heap space
+h2. Running out of heap space
You can give the JVM more heap space by setting the @JAVA_OPTS@ environment
variables. This environment variable provides arguments for staring the JVM.
@@ -25,7 +25,7 @@
}}}
-h4. RJB fails to compile
+h2. RJB fails to compile
On Linux, BSD and Cygwin, RJB locates the JDK headers files -- which it uses to
compile a native C extension -- based on the @JAVA_HOME@ environment variable.
@@ -40,7 +40,7 @@
}}}
-h4. Segmentation Fault when running Java code
+h2. Segmentation Fault when running Java code
This is most likely a JVM inconsistency, for example, when part of the RJB
library uses JDK 1.6, the other part uses JDK 1.5.
@@ -58,7 +58,7 @@
}}}
-h4. Bugs resulting from a dangling comma or period
+h2. Bugs resulting from a dangling comma or period
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
Modified: incubator/buildr/trunk/doc/pages/whats_new.textile
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/whats_new.textile?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/whats_new.textile (original)
+++ incubator/buildr/trunk/doc/pages/whats_new.textile Fri Feb 1 20:57:25 2008
@@ -86,6 +86,37 @@
"Read more ...":download.html#jruby
+h4. Profiles
+
+Different environments may require different configurations, some you will want
+to control with code, others you will want to specify in the profiles file.
+
+The profiles file is a YAML file called @profiles.yaml@ that you place in the
+same directory as the Buildfile. We selected YAML because it's easier to read
+and edit than XML.
+
+For example, to support three different database configurations, we could write:
+
+{{{!yaml
+# HSQL, don't bother storing to disk.
+development:
+ db: hsql
+ jdbc: hsqldb:mem:devdb
+
+# Make sure we're not messing with bigstrong.
+test:
+ db: oracle
+ jdbc: oracle:thin:@localhost:1521:test
+
+# The real deal.
+production:
+ db: oracle
+ jdbc: oracle:thin:@bigstrong:1521:mighty
+}}}
+
+"Read more ...":settings_profiles.html#profiles
+
+
h4. New API for accessing Java libraries
Java classes are accessed as static methods on the @Java@ module, for example:
@@ -115,7 +146,7 @@
Java classes to give Buildr a chance to load the libraries specified in the
classpath.
-"Read more ...":extending.html#using_java_libraries
+"Read more ...":more_stuff.html#using_java_libraries
h4. Creating Extensions
@@ -197,6 +228,11 @@
* A new "Contributing":contributing.html page has more details on how to file
bugs, policy for submitting patches, running Buildr test cases, and helping
with the documentation.
+
+* A new page for "Settings and Profiles":settings_profiles.html.
+
+* The "Extending Buildr":extending.html page that deals with writing your own
+tasks, creating extensions and specifying alternative layouts.
* The site also includes "RSpec test report":report.html and "Test coverage
report":coverage/index.html.
Modified: incubator/buildr/trunk/doc/print.toc.yaml
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/print.toc.yaml?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/print.toc.yaml (original)
+++ incubator/buildr/trunk/doc/print.toc.yaml Fri Feb 1 20:57:25 2008
@@ -5,6 +5,7 @@
- Artifcats: artifacts.html
- Packaging: packaging.html
- Testing: testing.html
+- Settings/Profiles: settings_profiles.html
- More Stuff: more_stuff.html
- Extending: extending.html
- Recipes: recipes.html
Modified: incubator/buildr/trunk/doc/web.toc.yaml
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/web.toc.yaml?rev=617749&r1=617748&r2=617749&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/web.toc.yaml (original)
+++ incubator/buildr/trunk/doc/web.toc.yaml Fri Feb 1 20:57:25 2008
@@ -10,6 +10,7 @@
- Artifcats: artifacts.html
- Packaging: packaging.html
- Testing: testing.html
+ - Settings/Profiles: settings_profiles.html
- More Stuff: more_stuff.html
- Extending: extending.html
- Recipes: recipes.html