buildr 1.2.10 → 1.3.0

data/doc/pages/building.textile

@@ -0,0 +1,501 @@
+h1. Building
+
+To remove any confusion, Buildr's build task is actually called @build@.  It's
+also the default task that executes when you run @buildr@ without any task
+name.
+
+The @build@ task runs two other tasks: @compile@ and its associated tasks (that
+would be, @resources@) and @test@ and its associated tasks (@test:compile@,
+@test:setup@ and friends).  We'll talk about @compile@ more in this section,
+and @test@ later on.  We'll also show you how to run @build@ without testing,
+not something we recommend, but a necessary feature.
+
+Why @build@ and not @compile@?  Some projects do more than just compiling.
+Other projects don't compile at all, but perform other build tasks, for
+example, creating a database schema or command line scripts.  So we want you to
+get in the practice of running the @build@ task, and help you by making it the
+default task.
+
+
+h2. Compiling
+
+Each project has its own @compile@ task you can invoke directly, by running
+@buildr compile@ or as part of another build task.  (Yes, that @build@).
+
+The @compile@ task looks for source files in well known directories, determines
+which compiler to use, and sets the target directory accordingly.  For example,
+if it finds any Java source files in the @src/main/java@ directory, it selects
+the Javac compiler and generates bytecode in the @target/classes@ directories.
+If it finds Scala source files in the @src/main/scala@ directory it selects the
+Scalac compiler, and so forth.
+A single project cannot use multiple compilers at the same time, hence you may 
+prefer creating subprojects by programming language. 
+Some compilers like Groovy's are joint-compilers, this means they can handle 
+several languages. When the Groovy compiler is selected for a project, .groovy 
+and .java files are compiled by groovyc.
+
+Most often, that's just good enough and the only change you need to make is
+adding compile dependencies.  You can use @compile.dependencies@ to get the
+array of dependency file tasks.  For Java, each of these tasks points to a JAR
+or a directory containing Java classes, and the entire set of dependencies is
+passed to Javac as the classpath.
+
+Buildr uses file tasks to handle dependencies, but here we're talking about the
+Rake dependency mechanism.  It's a double entendre.  It invokes these tasks
+before running the compiler.  Some of these tasks will download JARs from
+remote repositories, others will create them by compiling and packaging from a
+different project.  Using file task ensures all the dependencies exist before
+the compiler can use them.
+
+An easier way to specify dependencies is by calling the @compile.with@ method.
+It takes a list of arguments and adds them to the dependency list.  The
+@compile.with@ method is easier to use, it accepts several type of
+dependencies.  You can use file names, file tasks, projects, artifacts
+specifications and even pass arrays of dependencies.
+
+Most dependencies fall into the last three categories.  When you pass a project
+to @compile.with@, it picks up all the packages created by that project.  In
+doing so, it establishes an order of dependency between the two projects (see
+"Defining the Project":projects.html#defining_the_project).  For example, if
+you make a change in project _teh-api_ and build _teh-impl_, Buildr will detect
+that change, recompile and package _teh-api_ before compiling _teh-impl_.  You
+can also select a specific package using the @package@ or @packages@ methods
+(see "Packaging":packaging.html).
+
+When you pass an artifact specification to @compile.with@, it creates an
+@Artifact@ task that will download that artifact from one of the remote
+repositories, install it in the local repository, and use it in your project.
+Rake's dependency mechanism is used here to make sure the artifact is
+downloaded once, when needed.  Check the "Artifacts":artifacts.html section for
+more information about artifact specification and repositories.
+
+For now let's just show a simple example:
+
+{{{!ruby
+compile.with 'org.apache.axis2:axis2:jar:1.2',
+  'org.apache.derby:derby:jar:10.1.2.1', projects('teh-api', 'teh-impl')
+}}}
+
+Passing arrays to @compile.with@ is just a convenient for handling multiple
+dependencies, we'll show more examples of that when we talk about
+"Artifacts":#artifacts.
+
+Likewise, the @compile@ task has an array of file tasks that point at the
+source directories you want to compile from.  You can access that array by
+calling @compile.sources@.  You can use @compile.from@ to add new source
+directories by passing a file name or a file task.
+
+For example, let's run the APT tool on our annotated source code before
+compiling it:
+
+{{{!ruby
+compile.from apt
+}}}
+
+When you call @apt@ on a project, it returns a file task that points to the
+@target/generated/apt@ directory.  This file task executes by running APT,
+using the same list of source directories, dependencies and compiler options.
+It then generates new source files in the target directory.  Calling
+@compile.from@ with that file task includes those additional source files in
+the list of compiled sources.
+
+Here's another example:
+
+{{{!ruby
+jjtree = jjtree(_('src/main/jjtree'), :in_package=>'com.acme')
+compile.from javacc(jjtree, :in_package=>'com.acme'), jjtree
+}}}
+
+This time, the variable @jjtree@ is a file task that reads a JJTree source file
+from the @src/main/jjtree@ directory, and generates additional source files in
+the @target/generated/jjtree@ directory.  The second line creates another file
+task that takes those source files, runs JavaCC on them, and generates yet more
+source files in @target/generated/javacc@.  Finally, we include both sets of
+source files in addition to those already in @src/main/java@, and compile the
+lot.
+
+The interesting thing about these two examples is how you're wiring file tasks
+together to create more complicated tasks, piping the output of one task into
+the inputs of another.  Wiring tasks this way is the most common way to handle
+complex builds, and uses Rake's dependency mechanism to only run tasks when it
+detects a change to one of the source files.
+
+You can also control the target directory.  Use @compile.target@ to get the
+target directory file task.  If you need to change the target directory, call
+the @compile.into@ method with the new path.
+
+We use method pairs to give you finer control over the compiler, but also a way
+to easily configure it.  Methods like @dependencies@ and @sources@ give you a
+live array you can manipulate, or iterate over.  On the other hand, methods
+like @with@ and @from@ accept a wider set of arguments and clean them up for
+you.  They also all return the same task you're calling, so you can chain
+methods together.
+
+For example:
+
+{{{!ruby
+compile.from('srcs').with('org.apache.axis2:axis2:jar:1.2').
+  into('classes').using(:target=>'1.4')
+}}}
+
+Buildr uses the method pair and method chaining idiom in many places to make
+your life easier without sacrificing flexibility.
+
+Occasionally, you'll need to post-process the generated bytecode.  Since you
+only want to do that after compiling, and let the compiler decide when to do
+that – only when changes require re-compiling – you'll want to extend the
+@compile@ task.  You can do that by calling @compile@ with a block.
+
+For example, to run the OpenJPA bytecode enhancer after compiling the source
+files:
+
+{{{!ruby
+compile { open_jpa_enhance }
+}}}
+
+You can change various compile options by calling, you guessed,
+@compile.options@.  For example, to set the compiler to VM compatibility with
+Java 1.5 and turn on all Lint messages:
+
+{{{!ruby
+compile.options.target = '1.5'
+compile.options.lint = 'all'
+}}}
+
+Or, if you want to chain methods together:
+
+{{{!ruby
+compile.using :target=>'1.5', :lint=>'all'
+}}}
+
+Sub-projects inherit compile options from their parent project, so you only
+need to change these settings once in the top project.  You can do so, even if
+the top project itself doesn't compile anything.
+
+The options available to you depend on which compiler you are using for this
+particular project, obviously the options are not the same for Java and Flash.
+Two options are designed to work consistently across compilers.
+
+Buildr turns the @warning@ option on by default, but turns it off when you run
+@buildr --silent@.  It also sets the @debug@ option on, but turns it off when
+making a release.  You can also control the @debug@ option from the command
+line, for example:
+
+{{{!ruby
+# When calling buildr
+$ buildr compile debug=off
+
+# Once until we change the variable
+$ export DEBUG=off
+$ buildr compile
+}}}
+
+
+h3. Compiling Java
+
+The Java compiler looks for source files in the project's @src/main/java@
+directory, and defaults to compiling them into the @target/classes@ directory.
+It looks for test cases in the project's @src/test/java@ and defaults to
+compile them into the @target/test/classes@ directory.
+
+If you point the @compile@ task at any other source directory, it will use the
+Java compiler if any of these directories contains files with the extension
+@.java@.
+
+When using the Java compiler, if you don't specify the packaging type, it
+defaults to JAR.  If you don't specify the test framework, it defaults to
+JUnit.
+
+The Java compiler supports the following options:
+
+|_. 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
+
+Before using the Scala compiler, you must first set the environment variable
+@SCALA_HOME@.
+
+The Scala compiler looks for source files in the project's @src/main/scala@
+directory, and defaults to compiling them into the @target/classes@ directory.
+It looks for test cases in the project's @src/test/scala@ and defaults to
+compile them into the @target/test/classes@ directory.
+
+If you point the @compile@ task at any other source directory, it will use the
+Scala compiler if any of these directories contains files with the extension
+@.scala@.
+
+When using the Scala compiler, if you don't specify the packaging type, it
+defaults to JAR.
+
+The Scala compiler supports the following options:
+
+|_. 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
+that @fsc@ _may_ cache class libraries -- don't forget to run @fsc -reset@ if you 
+upgrade a library.
+
+
+h3. Compiling Groovy
+
+Before using the Groovy compiler, you must first require it on your buildfile:
+
+{{{!ruby
+   require 'buildr/java/groovyc'
+}}}
+
+Once loaded, the groovyc compiler will be automatically selected if any .groovy
+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
+the groovyc joint compiler.
+
+Sources found in @src/test/groovy@ are compiled into the @target/test/classes@.
+
+If you don't specify the packaging type, it defaults to JAR.
+
+The Groovy compiler supports the following options:
+
+|_. 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
+
+The @compile@ task comes bundled with a @resources@ task.  It copies files from
+the @src/main/resources@ directory into @target/resources@.  Best used for
+copying files that you want to included in the generated code, like
+configuration files, i18n messages, images, etc.
+
+The @resources@ task uses a filter that can change files as it copies them from
+source to destination.  The most common use is by mapping values using a hash.
+For example, to substitute "${version}" for the project's version number and
+"${copyright}" for "Acme Inc (C) 2007" :
+
+{{{!ruby
+resources.filter.using 'version'=>version,
+  'copyright'=>'Acme Inc (C) 2007'
+}}}
+
+
+You can also use "profiles":settings_profiles.html#profiles to supply a
+name/value map that all @resources@ task should default to, by adding a
+@filter@ element to each of the profiles.  The following examples shows a
+@profiles.yaml@ file that applies the same filter in development and test
+environments:
+
+{{{!yaml
+filter: &alpha1
+  version: experimental
+  copyright: Acme Inc (C) 2007
+  
+development:
+  filter: *alpha1
+test:
+  filter: *alpha1
+}}}
+
+You can specify a different format by passing it as the first argument.
+Supported formats include:
+
+|_. 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:
+
+{{{!ruby
+resources.filter.using :ruby, 'version'=>version,
+  'copyright'=>'Acme Inc (C) 2007'
+}}}
+
+For more complicated mapping you can also pass a method or a proc.  The filter
+will call it once for each file with the file name and content.
+
+If you need to copy resource files from other directories, add these source
+directories by calling the @from@ method, for example:
+
+{{{!ruby
+resources.from _('src/etc')
+}}}
+
+You can select to copy only specific files using common file matching patterns.
+For example, to include only HTML files:
+
+{{{!ruby
+resources.include '*.html'
+}}}
+
+To include all files, except for files in the @scratch@ directory:
+
+{{{!ruby
+resources.exclude 'scratch/*'
+}}}
+
+The filter always excludes the @CVS@ and @.svn@ directories, and all files
+ending with @.bak@ or @~@, so no need to worry about these.
+
+A file pattern can match any file name or part of a file name using an asterisk
+(@*@).  Double asterisk (@**@) matches directories recursively, for example,
+@'src/main/java/**/*.java'@.  You can match any character using a question mark
+(@?@), or a set of characters using square brackets (@[]@), similar to regular
+expressions, for example, @'[Rr]eadme'@. You can also match from a set of names
+using curly braces (@{}@), for example, @'*.{html,css}'@.
+
+You can use filters elsewhere.  The @filter@ method creates a filter, the
+@into@ method sets the target directory, and @using@ specifies the mapping.
+Last, you call @run@ on the filter to activate it.
+
+For example:
+
+{{{!ruby
+filter('src/specs').into('target/specs').
+  using('version'=>version, 'created'=>Time.now).run
+}}}
+
+The @resources@ task is, in fact, just a wrapper around such a filter that
+automatically adds the @src/main/resources@ directory as one of the source
+directories.
+
+
+h2. More On Building
+
+The @build@ task runs the @compile@ (and @resources@) tasks as prerequisites,
+followed by any actions you add to it, and completes by running the @test@
+task.  The @build@ task itself is a prerequisite to other tasks, for example,
+@package@ and @upload@.
+
+You can extend the @build@ task in two ways.  You can add more prerequisites
+that will execute before the task itself, or you can add actions that will
+execute as part of the task.  Which one you choose is up to you, we'll show you
+how they differ in a second.  If you call @build@ with a list of tasks, it adds
+these tasks as prerequisites.  Call @build@ with a block, and it adds that
+block as an action.  Again, a common idiom you'll see elsewhere in Buildr and
+Rake.
+
+Let's look at a simple example.  Say we want to generate a Derby database from
+an SQL file and include it in the ZIP package:
+
+{{{!ruby
+db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
+package(:zip).include db
+}}}
+
+There's nothing fundamentally wrong with this code, if that's what you intend
+to do.  But in practice, you don't always run the @package@ task during
+development, so you won't notice if something is wrong with this task when you
+build.  For example, if it fails to generate the SQL file.  In addition, the
+@package@ task runs after @build@, so you can't use the database in your test
+cases.
+
+So let's refactor it.  We're going to use the variable @db@ to reference the
+file task that creates the database, and make it a prerequisite of the @build@
+task.  And use that same variable again to include the database in the ZIP
+package:
+
+{{{!ruby
+db = Derby.create(_('target/derby/db')=>_('src/main/sql/derby.sql'))
+build db
+package(:zip).include db
+}}}
+
+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.
+
+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'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:
+
+{{{!ruby
+build do
+  filter('src/specs').into('target/specs').
+    using('version'=>version, 'created'=>Time.now).run
+end
+}}}
+
+The @build@ task is recursive, so running @buildr build@ picks the current
+project and runs its @build@ task, which in turn runs the @build@ task on each
+of its sub-projects.  One @build@ task to rule them all.
+
+
+h2. Cleaning
+
+The @build@ task has an evil twin, the @clean@ task.  It's the task you use to
+remove all the files created during the build, especially when you mess things
+up and want to start all over.
+
+It basically erases the target directories, the one called @target@, and if you
+get creative and change the target directory for tasks like @compile@, it will
+also erase those.  If you decide to generate files outside the target directory
+and want to cleanup after yourself, just extend the @clean@ task.
+
+For example: 
+
+{{{!ruby
+clean { rm_rf _('staged') }
+}}}
+
+The @rm_rf@ method deletes the directory and all files in it.  It's named after
+UNIX's infamous @rm -rf@.  Use it wisely.  This is also a good time to
+introduce you to @FileUtils@, a standard Ruby library that contains convenient
+methods for creating and deleting directories, copying and moving files, even
+comparing two files.  They're all free of charge when you use Buildr.
+
+Now let's "talk about the artifacts":artifacts.html we mentioned before.