buildr 1.2.10 → 1.3.0

data/doc/pages/troubleshooting.textile

@@ -0,0 +1,121 @@
+h1. Troubleshooting
+
+Common troubleshooting tips collected from the mailing list.
+
+
+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.
+For example, to set the heap space to 1GB:
+
+{{{!sh
+$ export "JAVA_OPTS=-Xms1g -Xmx1g"
+$ buildr compile
+}}}
+
+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.
+
+For example:
+
+{{{!ruby
+ENV['JAVA_OPTS'] = '-Xms1g -Xmx1g'
+}}}
+
+
+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.
+Make sure @JAVA_HOME@ points to the JDK, not JRE.
+
+If you are using @sudo gem install@, note that some environments do not pass
+the @JAVA_HOME@ environment variable over to @sudo@.  To get around this, run
+@gem@ with the @env JAVA_HOME=$JAVA_HOME@ option:
+
+{{{!sh
+$ sudo env JAVA_HOME=$JAVA_HOME gem install buildr
+}}}
+
+
+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.
+
+During installation RJB builds a native C extension using header files supplied by
+the JVM, and compiles a Java bridge class using the Javac.  It is possible for RJB
+to use two different versions of the JVM, for example, if @JAVA_HOME@ points to
+JDK 1.5, but @/usr/bin/javac@ points to JDK 1.6.
+
+Make sure @JAVA_HOME@ and @/usr/bin/javac@ both point to the same JDK:
+
+{{{!sh
+echo $JAVA_HOME
+ls -l /usr/bin/javac
+}}}
+
+*Note:*  It seems that RJB works with Java 6, except when it doesn't, and for a
+few people it doesn't.  In that case, either switch to Java 1.5, or simply run
+Buildr on JRuby using Java 6.
+
+
+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
+line.  For example:
+
+{{{!ruby
+compile.with 'org.apache.axis2:axis2:jar:1.2',
+test.with 'log4j:log4j:jar:1.1'
+}}}
+
+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.
+
+As you can imagine this happens usually after editing, specifically for commas
+and periods which are small enough that you won't notice them from a cursory
+glance at the code, so if all else fails, search for lines that end with one of
+these characters.
+
+
+h2.  Missing POM breaks transitive dependencies
+
+Occasionally, artifacts are deployed to remote repositories with missing or
+broken POMs.  Buildr will fail when attempting to resolve transitive
+dependencies with broken or missing POMs.
+
+In this particular case, failing is doing the right thing.  There's no way for
+Buildr to tell whether the POM is nowhere to be found, or just a temporary
+problem accessing the remote server.
+
+If you can determine that the POM file is missing you can work around the
+problem in three ways.  If you published the artifact, make the release again,
+getting it to upload the missing files.
+
+If the source repository is not under your control, but you are also using your
+own repository for the project, you can always create a dummy POM in your own
+repository.  Buildr will attempt to download the file from either repository,
+using the first file it finds.
+
+Alternatively, you can make Buildr create a dummy POM file in the local
+repository, instead of downloading it from a remote repository.  This example
+creates a dummy POM for Axis JAX-RPC:
+
+{{{!ruby
+artifact 'axis:axis-jaxrpc:pom:1.3' do |task|
+  write task.name, <<-POM
+    <project>
+      <modelVersion>4.0.0</modelVersion>
+      <groupId>axis</groupId>
+      <artifactId>axis-jaxrpc</artifactId>
+      <version>1.4</version>
+    </project>
+  POM
+end
+}}}
+

data/doc/pages/whats_new.textile

@@ -0,0 +1,389 @@
+h1.  What's New
+
+h2.  Buildr 1.3
+
+h3.  Multiple Languages
+
+The main focus of this release is supporting multiple languages for compiling
+and testing.
+
+For each project, Buildr will attempt to infer which compiler to use based on
+the source files it finds, for example, if it finds @.java@ files in the
+@src/main/java@ directory, it will switch to the javac compiler, if it finds
+@.scala@ files in the @src/main/scala@ directory, to the scalac compiler and so
+forth.
+
+Different compilers may use different target directory, @target/classes@ is
+picked for JVM compilers (Java, Scala, Groovy, etc), so resources are not copied to
+their own directory, @target/resources@.  The prepare task has been removed.
+
+Not all languages have classpaths, so @compile.classpath@ is now known as
+@compile.dependencies@, but the old attribute still exists for backward
+compatibility.
+
+Also, for consistency, the test target directories have changed to
+@target/test/classes@ and @target/test/resources@, respectively.
+
+Speaking of tests, you can compile code in one language and use a different
+language to test it, say, if you're interested in compiling Java code and
+testing it with Ruby, or compiling Flash and running a Java test suite.
+
+As before, you can pick the test framework by calling
+@test.using(<framework>)@.  Buildr will attempt to pick one by default, for
+example, if the tests are written in Java, it will default to JUnit.
+
+And, since not all languages package to JARs, the default packaging is either
+inferred from the compiler (so @:jar@ when compiling Java code), otherwise to
+@:zip@.  All this defaulting means that @package()@ with no arguments does the
+right thing in more cases, and most probably won't break anyone's buildfiles.
+
+I've tried to keep the compiler API as simple as possible, making it easy to
+add new compilers; however, I had to change the test framework API to
+accommodate the new features, so old test frameworks will not work on 1.3.
+
+
+h3.  Scala Support
+
+Buildr now supports Scala, using both native and fast Scala compiler.
+
+Read more about "using Scala":building.html#compiling_scala.
+
+
+h3.  Groovy Support
+
+Buildr now supports Groovy, using the Groovyc Ant task.
+
+Read more about "using Groovy":building.html#compiling_groovy.
+
+
+h3.  Packaging Files
+
+The @package@ method is convenient enough that you can now use it to generate
+artifacts, an in addition to generate regular file tasks, specifying the file
+name using the @:file@ attribute.  For example:
+
+{{{!ruby
+package :zip, :file=>_('target/interesting.zip')
+}}}
+
+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.
+
+
+h3.  Packaging EARs
+
+EAR packages support four component types:
+
+|_. Argument  |_. Component                     |
+| @:war@      | J2EE Web Application (WAR).     |
+| @:ejb@      | Enterprise Java Bean (JAR).     |
+| @:jar@      | J2EE Application Client (JAR).  |
+| @:lib@      | Shared library (JAR).           |
+
+This example shows two ways for adding components built by other projects:
+
+{{{!ruby
+package(:ear) << project('coolWebService').package(:war)
+package(:ear).add project('commonLib') # By default, the JAR package
+}}}
+
+EAR packages include an @application.xml@ file in the @META-INF@ directory that
+describes the application and its component.  This file is created for you
+during packaging, by referencing all the components added to the EAR.  There
+are a couple of things you will typically want to change.
+
+* *display-name* -- The application's display name defaults to the project's
+identifier.  You can change that by setting the @display_name@ attribute.
+
+* *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
+
+
+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
+
+
+h3. Behaviour-Driven Development
+
+Given that many languages are now supported by Buildr, the same is true for
+testing, the convention is to store BDD files under the @src/spec/{lang}@ 
+directory. 
+The following table shows the framework's name you can use to select them 
+for your projects. Buildr follows each framework's naming convention.
+
+|_. test.using     |_. Test file name convention                  |
+| @:jbehave@       |  @src/spec/java/**/*Behaviour.java@            |
+| @:rspec@         |  @src/spec/ruby/**/*_spec.rb@                  |
+| @:easyb@         |  @src/spec/groovy/**/*{Story,Behavior}.groovy@ |
+
+"Read more ...":testing.html#bdd
+
+
+h3.  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
+}}}
+
+You can also use profiles to specify default filters for the "@resources@
+task":building.html#resources.
+
+"Read more ...":settings_profiles.html#profiles
+
+
+h3.  Settings and build YAML files
+
+In addition to profiles, we also allow you to specify personal and build
+settings using two YAML files.
+
+Personal settings are placed in the @.buildr/settings.yaml@ file under your
+home directory. Settings stored there will be applied the same across all
+builds.
+
+For example:
+
+{{{!yaml
+# The repositories hash is read automatically by buildr.
+repositories:
+
+  # customize user local maven2 repository location
+  local: some/path/to/my_repo
+
+  relase_to:
+    url: http://intra.net/maven2
+    username: john
+    password: secret
+
+# You can place settings of your own, and reference them 
+# on buildfiles. 
+im:
+  server: jabber.company.com
+  usr: notifier@company-jabber.com
+  pwd: secret
+}}}
+
+"Read more ...":settings_profiles.html#personal_settings
+
+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.
+
+For example:
+
+{{{!yaml
+# This project requires the following ruby gems, buildr addons
+gems: 
+  # Suppose we want to notify developers when testcases fail.
+  - buildr-twitter-notifier-addon >=1
+  # we test with ruby mock objects
+  - mocha
+  - ci_reporter
+
+# The artifact declarations will be automatically loaded by buildr, so that
+# you can reference artifacts by name (a ruby-symbol) on your buildfile.
+artifacts:
+  spring: org.springframework:spring:jar:2.0
+  log4j: log4j:log4j:jar:1.0
+  j2ee: geronimo-spec:geronimo-spec:j2ee:jar:1.4-rc4
+
+# Of course project settings can be defined here
+jira: 
+  uri: https://jira.corp.org
+}}}
+
+"Read more ...":settings_profiles.html#build_settings
+
+
+h3.  Using Gems for extensions and 3rd party libraries
+
+"RubyGems":http://rubygems.rubyforge.org provides the @gem@ command line tool
+that you can use to search, install, upgrade, package and distribute gems. It
+installs all gems into a local repository that is shared across your builds and
+all other Ruby applications you may have running.  You can install a gem from a
+local file, or download and install it from any number of remote repositories.
+
+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:
+
+{{{!yaml
+# This project requires the following gems
+gems: 
+  # Suppose we want to notify developers when testcases fail.
+  - buildr-twitter-notifier-addon >=1
+  # we test with ruby mock objects
+  - mocha
+  - ci_reporter
+}}}
+
+"Read more ...":more_stuff.html#using_gems
+
+
+h3.  New API for accessing Java libraries
+
+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.
+
+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.
+
+"Read more ...":more_stuff.html#using_java_libraries
+
+
+h3.  Creating Extensions
+
+A module defines instance methods that are then mixed into the project and
+become instance methods of the project.  There are two general ways for
+extending projects.  You can extend all projects by including the module in
+Project:
+
+{{{!ruby
+class Project
+  include MyExtension
+end
+}}}
+
+You can also extend a given project instance and only that instance by
+extending it with the module:
+
+{{{!ruby
+define 'foo' do
+  extend MyExtension
+end
+}}}
+
+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
+
+
+h3.  Using Alternative Layouts
+
+Buildr follows a common convention for project layouts: Java source files
+appear in @src/main/java@ and compile to @target/classes@, resources are
+copied over from @src/main/resources@ and so forth.  Not all projects follow
+this convention, so it's now possible to specify an alternative project
+layout.
+
+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
+
+
+h3.  Other
+
+* Buildr 1.3 upgrades to Rake 0.8, RSpec 1.1, RJB 1.1 and OpenJPA
+1.0.1.  Buildr no longer includes or uses Facets.
+
+* JUnit tests now operate on all compiled test classes that extend
+@junit.framework.TestCase@ or use the @Test@ annotation; TestNG test cases are
+filtered by annotation.  Test cases no longer have to use a specific file name.
+
+* Remote repositories now support HTTP Basic Authentication.
+
+* The prepare task has been removed, if you need to, simply add a prerequisite
+to the compile task.
+
+
+h3.  Documentation
+
+* The "What's new?":whats_new.html page (this one, actually), summarizes all
+the important new features and changes in each release.
+
+* The "Recipes":recipes.html page (also available in the PDF) lists recipes for
+using Buildr, collected from the mailing list.  Feel free to contribute tips,
+tricks and techniques.
+
+* The "Troubleshooting":troubleshooting.html page (also available in the PDF)
+collects troubleshooting ideas from the mailing list.
+
+* The "Getting Started":getting_started.html has been rewritten to cover all
+you need to know about downloading and installing Buildr on Linux, OS/X,
+Windows and with JRuby (1.1 or later).
+
+* 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 report":specs.html and "Test coverage
+report":coverage/index.html.