Author: assaf
Date: Sat Feb 2 13:39:30 2008
New Revision: 617900
URL: http://svn.apache.org/viewvc?rev=617900&view=rev
Log:
Added settings and profiles page
Added:
incubator/buildr/trunk/doc/pages/settings_profiles.textile
Added: incubator/buildr/trunk/doc/pages/settings_profiles.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/settings_profiles.textile?rev=617900&view=auto
==============================================================================
--- incubator/buildr/trunk/doc/pages/settings_profiles.textile (added)
+++ incubator/buildr/trunk/doc/pages/settings_profiles.textile Sat Feb 2
13:39:30 2008
@@ -0,0 +1,227 @@
+h1. Settings/Profiles
+
+
+h2. Environment Variables
+
+Buildr uses several environment variables that help you control how it works.
+Some environment variables you will only set once or change infrequently. You
+can set these in your profile, OS settings or any tool you use to launch Buildr
+(e.g. continuous integration).
+
+For example:
+
+{{{!sh
+$ export HTTP_PROXY=http://myproxy:8080
+}}}
+
+There are other environment variables you will want to set when running Buildr,
+for example, to do a full build without running the tests:
+
+{{{!sh
+$ buildr test=no
+}}}
+
+For convenience, when you set environment variables on the command line, the
+variable name is case insensitive, you can use either @test=no@ or @[EMAIL
PROTECTED]
+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:
+
+{{{!ruby
+# This project builds a lot of code.
+ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
+}}}
+
+Make sure to set any environment variables at the very top of the Buildfile[1],
+above any Ruby statement (even @require@).
+
+Buildr supports the following environment variables:
+
+|_. Variable |_. Description |
+| @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). |
+| @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'@). |
+| @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). |
+| @USER@ | Tasks that need your user name, for example to log to remote
+servers, will use this environment variable. |
+
+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:
+
+{{{!ruby
+repositories.upload_to[:username] = ENV['USERNAME']
+repositories.upload_to[:password] = ENV['PASSWORD']
+}}}
+
+
+h2. Personal/Project Settings
+
+Some things clearly do not belong in the Buildfile. For example, the username
+and 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 other files: the
[EMAIL PROTECTED]@ file it finds in your home directory, followed by the
@buildr.rb@
+file it finds in the build directory.
+
+The loading order 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'
+}}}
+
+
+h2. 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 running 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
[EMAIL PROTECTED]@ method. You can set the current build environment in one of
two
+ways. Using the @-e/--environment@ 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)
+}}}
+
+Unless you tell it otherwise, Buildr assumes you're developing and sets the
+environment to @[EMAIL PROTECTED]
+
+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
+}}}
+
+We recommend picking a convention for your different environments and following
+it across all your projects. For example:
+
+|_. Environment |_. Use when ... |
+| development | Developing on your machine. |
+| test | Running in test environment, continuous integration. |
+| production | Building for release/production. |
+
+
+h2. 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
+}}}
+
+Here's a simple example for a buildfile that uses the profile information:
+
+{{{!ruby
+project 'db-module' do
+ # Copy SQL files specific for the database we're using,
+ # for example, everything under src/main/hsql.
+ resources.from(_(:source, :main, profile['db']))
+ # Set the JDBC URL in copied resource files (config.xml needs this).
+ resources.filter :jdbc=>profile['jdbc']
+end
+}}}
+
+The @profile@ method returns the current profile, selected based on the current
+"environment":#environments. You can get a list of all profiles by calling
[EMAIL PROTECTED]@.
+
+When you run the above example in @development@, the current profile will
+return the hash @{ 'db'=>'hsql', 'jdbc'=>'hsqldb:mem:devdb' [EMAIL PROTECTED]
+
+We recommend following conventions and using the same environments in all your
+projects, but sometimes the profiles end up being the same, so here's a trick
+you can use to keep your profiles DRY.
+
+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:
+
+
+{{{!yaml
+# We'll reference this one as common.
+development: &common
+ db: hsql
+ jdbc: hsqldb:mem:devdb
+ resources:
+ copyright: Me (C) 2008
+# Merge the values from common, override JDBC URL.
+test:
+ <<: *common
+ jdbc: hsqldb:file:testdb
+}}}
+
+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 @[EMAIL PROTECTED] A common
+mistake is to pass an option like @mx512mb@, where it should be @[EMAIL
PROTECTED]
+Make sure to double check @[EMAIL PROTECTED]
