12 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.
14 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@.
16 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.
18 The Java compiler supports the following options:
20 |_. Option |_. Usage |
21 | @:debug@ | Generates bytecode with debugging information. You can also override this by setting the environment variable @debug@ to @off@. |
22 | @:deprecation@ | If true, shows deprecation messages. False by default. |
23 | @:lint@ | Defaults to false. Set this option to true to use all lint options, or specify a specific lint option (e.g. @:lint=>'cast'@). |
24 | @:other@ | Array of options passed to the compiler (e.g. @:other=>'-implicit:none'@). |
25 | @:source@ | Source code compatibility (e.g. '1.5'). |
26 | @:target@ | Bytecode compatibility (e.g. '1.4'). |
27 | @:warnings@ | Issue warnings when compiling. True when running in verbose mode. |
31 You can use the "ECJ compiler":http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_batch_compiler.htm instead of javac. ECJ abides to the same options as javac.
32 For example, to configure the project to use ECJ:
37 To use a custom version of ECJ, add an entry to your "settings":/settings_profiles.html.
38 For example, to set the version of ECJ to 3.5.1, add an entry to your project's @buildr.yml@:
48 The default test framework for Java projects is "JUnit 4":http://www.junit.org.
50 When you use JUnit, the dependencies includes JUnit and "JMock":http://www.jmock.org, and Buildr picks up all test classes from the project by looking for classes that either subclass @junit.framework.TestCase@, include methods annotated with @org.junit.Test@, or test suites annotated with @org.org.junit.runner.RunWith@.
52 The JUnit test framework supports the following options:
54 |_. Option |_. Value |
55 | @:fork@ | VM forking, defaults to true. |
56 | @:clonevm@ | If true clone the VM each time it is forked. |
57 | @:properties@ | Hash of system properties available to the test case. |
58 | @:environment@ | Hash of environment variables available to the test case. |
59 | @:java_args@ | Arguments passed as is to the JVM. |
61 For example, to pass properties to the test case:
64 test.using :properties=>{ :currency=>'USD' }
67 There are benefits to running test cases in separate VMs. The default forking mode is @:once@, and you can change it by setting the @:fork@ option.
69 |_. :fork=> |_. Behavior |
70 | @:once@ | Create one VM to run all test classes in the project, separate VMs for each project. |
71 | @:each@ | Create one VM for each test case class. Slow but provides the best isolation between test classes. |
72 | @false@ | Without forking, Buildr runs all test cases in a single VM. This option runs fastest, but at the risk of running out of memory and causing test cases to interfere with each other. |
74 You can see your tests running in the console, and if any tests fail, Buildr will show a list of the failed test classes. In addition, JUnit produces text and XML report files in the project's @reports/junit@ directory. You can use that to get around too-much-stuff-in-my-console, or when using an automated test system.
76 In addition, you can get a consolidated XML or HTML report by running the @junit:report@ task. For example:
79 $ buildr test junit:report test=all
80 $ firefox report/junit/html/index.html
83 The @junit:report@ task generates a report from all tests run so far. If you run tests in a couple of projects, it will generate a report only for these two projects. The example above runs tests in all the projects before generating the reports.
85 You can use the @build.yaml@ settings file to specify a particular version of JUnit or JMock. For example, to force your build to use JUnit version 4.4 and JMock 2.0:
95 You can use "TestNG":http://testng.org instead of JUnit. To select TestNG as the test framework, add this to your project:
101 Like all other options you can set with @test.using@, it affects the projects and all its sub-projects, so you only need to do this once at the top-most project to use TestNG throughout. You can also mix TestNG and JUnit by setting different projects to use different frameworks, but you can't mix both frameworks in the same project. (And yes, @test.using :junit@ will switch a project back to using JUnit)
103 TestNG works much like JUnit, it gets included in the dependency list along with JMock, Buildr picks test classes that contain methods annotated with @org.testng.annotations.Test@, and generates test reports in the @reports/testng@ directory. At the moment we don't have consolidated HTML reports for TestNG.
105 The TestNG test framework supports the following options:
107 |_. Option |_. Value |
108 | @:properties@ | Hash of system properties available to the test case. |
109 | @:java_args@ | Arguments passed as is to the JVM. |
111 You can use the @build.yaml@ settings file to specify a particular version of TestNG, for example, to force your build to use TestNG 5.7:
120 "JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language.
122 To use JBehave in your project you can select it with @test.using :jbehave@.
124 This framework will search for the following patterns under your project:
127 src/spec/java/**/*Behaviour.java
130 Supports the following options:
132 |_. Option |_. Value |
133 | @:properties@ | Hash of system properties available to the test case. |
134 | @:java_args@ | Arguments passed as is to the JVM. |
136 You can use the @build.yaml@ settings file to specify a particular version of JBehave, for example, to force your build to use JBehave 1.0.1:
145 Buildr offers support for using JavaDoc to generate documentation from any Java sources in a project. This is done using the @doc@ task:
151 This will use the same @.java@ sources used by the @compile@ task to produce JavaDoc results in the @target/doc/@ directory. By default, these sources are chosen only from the current project. However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
157 doc.from projects('foo:bar', 'foo')
165 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
168 The @doc@ task supports any option that the @javadoc@ command does (e.g. @-windowtitle@). To pass an option to the JavaDoc generator, simply specify it using the @doc@ method:
174 doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
181 Before using Scala, you must first @require@ the Scala compiler:
184 require 'buildr/scala'
187 By default, Buildr will attempt to use the latest stable release of Scala, which is currently Scala 2.9.0 as of May 2011. Of course you can configure a specific version of Scala for your project by adding the following entry in @build.yaml@:
190 scala.version: 2.8.0.Beta1 # Pick your version
193 Or, you can do the same programmatically:
196 # Must be placed before require 'buildr/scala'
197 Buildr.settings.build['scala.version'] = "2.8.0.Beta1"
200 You may also determine the version in use by querying the @Scala.version@ attribute:
203 Scala.version # => '2.8.0'
206 Regardless of how the Scala version is determined, if you have the same Scala version installed on your system and the SCALA_HOME environment variable points to it, then your local installation will be used. Otherwise, Buildr will download it from the "Sonatype repository":http://oss.sonatype.org/content/repositories/releases which is automatically enlisted when you @require@ Scala. The only drawback if you don't have a local installation is the FSC compiler won't be available.
208 p(tip). For Mac users, if you have installed Scala via "MacPorts":http://www.macports.org/ Buildr will look in the
209 @/opt/local/share/scala/@ directory if you have not set @SCALA_HOME@.
214 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.
216 Any Java source files found in the @src/main/java@ directory will be compiled using the Scala/Java joint compiler into the @target/classes@ directory. Both the Java and the Scala sources are compiled with an inclusive classpath, meaning that you may have a Java class which depends upon a Scala class which depends upon a Java class, all within the same project. The Java sources will be compiled with the same dependencies as the Scala sources with the addition of the @scala-library.jar@ file as required for Scala interop.
218 Note that you cannot use the Groovy *and* the Scala joint compilers in the same project. If both are required, the Groovy joint compiler will take precedence.
220 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@. The joint compilation of Java sources may only be pointed at an alternative directory using the feature to redefine the @_(:src, :main, :java)@ path.
222 When using the Scala compiler, if you don't specify the packaging type, it defaults to JAR.
224 The Scala compiler supports the following options:
226 |_. Option |_. Usage |
227 | @:debug@ | If true, generates bytecode with debugging information. Scala 2.9 also accepts: none,source,line,vars,notc. |
228 | @:deprecation@ | If true, shows deprecation messages. False by default. |
229 | @:make@ | Make strategy to be used by the compiler (e.g. @:make=>'transitive'@). *Scala 2.8 only* |
230 | @:optimise@ | Generates faster bytecode by applying optimisations to the program. |
231 | @:other@ | Array of options passed to the compiler (e.g. @:other=>'-Xprint-types'@). |
232 | @:target@ | Bytecode compatibility (e.g. '1.4'). |
233 | @:warnings@ | Issue warnings when compiling. True when running in verbose mode. |
234 | @:javac@ | A hash of options passed to the @javac@ compiler verbatim. |
235 | @:incremental@ | If true, enables incremental compilation using Zinc. |
237 h4. Fast Scala Compiler
239 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.
241 (Note @fsc@ is not compatible with @zinc@ incremental compilation.)
243 h4. Rebuild detection
247 The Scala 2.7 compiler task assumes that each @.scala@ source file generates a corresponding @.class@ file under @target/classes@ (or @target/test/classses@ for tests). The source may generate more @.class@ files if it contains more than one class, object, trait or for anonymous functions and closures.
249 For example, @src/main/scala/com/example/MyClass.scala@ should generate at least @target/classes/com/example/MyClass.class@. If that it not the case, Buildr will always recompile your sources because it will assume this is a new source file that has never been compiled before.
253 Scala 2.8 provides a substantially better interface for implementing change detection. Whenever you use Scala 2.8 (see below), Buildr will auto-detect the version and enable this feature dynamically. After the @compile@ task runs, the relevant target directory will contain a @.scala-deps@ file, generated by the Scala compiler. The manner in which this file is used can be configured using the @:make@ compiler option. The following values are available:
255 * @:all@ - Disables compiler-level change detection
256 * @:changed@ - Only build changed files without considering file dependencies
257 * @:immediate@ - *unknown*
258 * @:transitive@ - Build changed files as well as their transitive file dependencies
259 * @:transitivenocp@ - Build changed files as well as their transitive file dependencies (*default*)
261 Please note that there are limits to compiler-level change detection. Most notably, dependencies cannot be tracked across separate compilation targets. This would cause problems in the case where an API has been changed in a main source file. The test suite for the project will *not* be detected as requiring recompilation, potentially resulting in unexpected runtime exceptions. When in doubt, run @clean@ to remove all dependency information. In extreme cases, it is possible to completely disable compiler-level change detection by adding the following statement to your project definition:
264 compile.using :make => :all
267 Effectively, this is telling the Scala compiler to ignore the information it has built up regarding source file dependencies. When in this mode, only Buildr's change detection semantics remain in play (as described above).
269 To avoid unusual behavior, compiler-level change detection is disabled whenever the joint Scala-Java compiler is used. Thus, any @.java@ files in a project handled by the Scala compiler will cause the @:make@ option to be ignored and revert to the exclusive use of Buildr's change detection mechanism (as described above).
271 *Scala 2.9 and later*
273 Starting with Buildr 1.4.8, Buildr integrates with the "Zinc":https://github.com/typesafehub/zinc incremental compilation wrapper for @scalac@. Incremental compilation can be enabled 3 ways,
275 1) By setting the compiler's option directly,
278 compile.using :incremental => true
280 compile.options.incremental = true # same as above
283 Note that this won't enable incremental compilation for both @compile@ and @test.compile@, you would have to set options on both. For this reason, it's recommended that you set the option on the project instead (see below).
285 2) By setting the project's @scalac_options.incremental@,
288 project.scalac_options.incremental = true
291 3) By setting the global @scalac.incremental@ option,
296 Buildr.settings.build['scalac.incremental'] = true
299 or in your @build.yaml@:
302 scalac.incremental: true
305 h4. Support for different Scala versions
307 Buildr defaults to the latest stable Scala version available at the time of the release if neither @SCALA_HOME@ nor the @scala.version@ build property are set.
309 If your @SCALA_HOME@ environment variable points to an installation of Scala (2.7, 2.8, 2.9, ...), then Buildr will use that compiler and enable version-specific features.
311 You may select the Scala version by dynamically in different ways,
313 1) By reassigning @SCALA_HOME@ at the top of the buildfile (*before* @require 'buildr/scala'@):
316 ENV['SCALA_HOME'] = ENV['SCALA28_HOME']
318 require 'buildr/scala'
322 2) By setting the @scala.version@ build property in your build.yaml file:
325 scala.version: 2.9.1.RC1
328 3) By setting the @scala.version@ build property in your buildfile:
331 require 'buildr/scala'
333 Buildr.settings.build['scala.version'] = '2.10-M6'
336 h3. Testing with Scala
338 Buildr supports two main Scala testing frameworks: "ScalaTest":http://www.artima.com/scalatest and "Specs":http://code.google.com/p/specs/. "ScalaCheck":http://code.google.com/p/scalacheck/ is also supported within the confines of either of these two frameworks. Thus, your Specs may use ScalaCheck properties, as may your ScalaTest suites.
341 test.using(:scalatest)
346 ScalaTest support is activated automatically when there are any @.scala@ source files contained in the @src/test/scala@ directory. If you are not using this directory convention, you may force the test framework by using the @test.using :scalatest@ directive.
348 Buildr automatically detects and runs tests that extend the @org.scalatest.Suite@ interface.
350 A very simplistic test class might look like,
352 {% highlight scala %}
353 class MySuite extends org.scalatest.FunSuite {
361 You can also pass properties to your tests by doing @test.using :properties => { 'name'=>'value' }@, and by overriding the @Suite.runTests@ method in a manner similar to:
363 {% highlight scala %}
364 import org.scalatest._
366 class PropertyTestSuite extends FunSuite {
367 var properties = Map[String, Any]()
369 test("testProperty") {
370 assert(properties("name") === "value")
373 protected override def runTests(testName: Option[String],
374 reporter: Reporter, stopper: Stopper, includes: Set[String],
375 excludes: Set[String], properties: Map[String, Any])
377 this.properties = properties;
378 super.runTests(testName, reporter, stopper,
379 includes, excludes, properties)
386 Specs is automatically selected whenever there are @.scala@ source files under the @src/spec/scala@ directory. It is also possible to force selection of the test framework by using the @test.using :specs@ directive. This can sometimes be useful when Scala sources may be found in *both* @src/test/scala@ and @src/spec/scala@. Normally in such cases, ScalaTest will have selection precedence, meaning that in case of a conflict between it and Specs, ScalaTest will be chosen.
388 Any objects which extend the @org.specs.Specification@ or @org.specs2.Specification@ superclass will be automatically detected and run. Note that any *classes* which extend @Specification@ will also be invoked. As such classes will not have a @main@ method, such an invocation will raise an error.
390 A simple specification might look like this:
392 {% highlight scala %}
394 import org.specs.runner._
396 object StringSpecs extends Specification {
397 "empty string" should {
398 "have a zero length" in {
405 ScalaCheck is automatically added to the classpath when Specs is used. However, JMock, Mockito, CGlib and similar are _not_. This is to avoid downloading extraneous artifacts which are only used by a small percentage of specifications. To use Specs with Mockito (or any other library) in a Buildr project, simply add the appropriate dependencies to @test.with@:
408 MOCKITO = 'org.mockito:mockito-all:jar:1.7'
409 CGLIB = 'cglib:cglib:jar:2.1_3'
410 ASM = 'asm:asm:jar:1.5.3'
411 OBJENESIS = 'org.objenesis:objenesis:jar:1.1'
413 define 'killer-app' do
416 test.with MOCKITO, CGLIB, ASM, OBJENESIS
420 The dependencies for Specs's optional features are defined "here":http://code.google.com/p/specs/wiki/RunningSpecs#Dependencies.
424 You may use ScalaCheck inside ScalaTest- and Specs-inherited classes. Here is an example illustrating checks inside a ScalaTest suite,
426 {% highlight scala %}
427 import org.scalatest.prop.PropSuite
428 import org.scalacheck.Arbitrary._
429 import org.scalacheck.Prop._
431 class MySuite extends PropSuite {
433 test("list concatenation") {
434 val x = List(1, 2, 3)
435 val y = List(4, 5, 6)
436 assert(x ::: y === List(1, 2, 3, 4, 5, 6))
437 check((a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size)
441 "list concatenation using a test method",
442 (a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size
450 Buildr offers support for using ScalaDoc or VScalaDoc to generate documentation from any Scala sources in a project. This is done using the @doc@ task:
456 This will use the same @.scala@ sources used by the @compile@ task to produce ScalaDoc results in the @target/doc/@ directory. By default, these sources are chosen only from the current project. However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
462 doc.from projects('foo:bar', 'foo')
470 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
473 The @doc@ task supports any option that the @scaladoc@ command does (e.g. @-windowtitle@). To pass an option to the ScalaDoc (or VScalaDoc) generator, simply specify it using the @doc@ method:
479 doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
483 By default, the @doc@ task will use the ScalaDoc generator on Scala projects. To select the VScalaDoc generator, you must use the @doc.using@ invocation:
491 The @doc@ task is *not* joint-compilation aware. Thus, it will only generate ScalaDoc for mixed-source projects, it will not attempt to generate both JavaDoc and ScalaDoc.
497 To start using Kotlin, you must first require it on your Buildfile:
500 require 'buildr/kotlin'
503 Any project with a .kt file under the @src/main/kotlin@ directory (by default), compiling them into @target/classes@.
505 If the project has any java files, they will be compiled using javac.
507 |_. Option |_. Usage |
508 | @verbose@ | Asks the compiler for verbose output, true when running in verbose mode. |
509 | @fork@ | Whether to execute groovyc using a spawned instance of the JVM. Defaults to no. |
510 | @warnings@ | Issue warnings when compiling. True when running in verbose mode. |
511 | @debug@ | Generates bytecode with debugging information. Set from the debug environment variable/global option. |
512 | @optimize@ | Generates faster bytecode by applying optimisations to the program. |
513 | @noStdlib@ | Include the Kotlin runtime libraries from KOTLIN_HOME in the classpath of the compiler. |
514 | @target@ | Bytecode compatibility. |
515 | @javac@ | Hash of options passed to the ant javac task. |
521 Before using the Groovy compiler, you must first require it on your buildfile:
524 require 'buildr/java/groovyc'
527 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.
529 If the project has java sources in @src/main/java@ they will get compiled using the groovyc joint compiler.
531 Sources found in @src/test/groovy@ are compiled into the @target/test/classes@.
533 If you don't specify the packaging type, it defaults to JAR.
535 The Groovy compiler supports the following options:
537 |_. Option |_. Usage |
538 | @encoding@ | Encoding of source files. |
539 | @verbose@ | Asks the compiler for verbose output, true when running in verbose mode. |
540 | @fork@ | Whether to execute groovyc using a spawned instance of the JVM. Defaults to no. |
541 | @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@) |
542 | @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@) |
543 | @listfiles@ | Indicates whether the source files to be compiled will be listed. Defaults to no. |
544 | @stacktrace@ | If true each compile error message will contain a stacktrace. |
545 | @warnings@ | Issue warnings when compiling. True when running in verbose mode. |
546 | @debug@ | Generates bytecode with debugging information. Set from the debug environment variable/global option. |
547 | @deprecation@ | If true, shows deprecation messages. False by default. |
548 | @optimise@ | Generates faster bytecode by applying optimisations to the program. |
549 | @source@ | Source code compatibility. |
550 | @target@ | Bytecode compatibility. |
551 | @javac@ | Hash of options passed to the ant javac task. |
553 h3. Testing with Groovy
557 "EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/.
559 Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy.
561 To use this framework in your project you can select it with @test.using :easyb@.
563 This framework will search for the following patterns under your project:
566 src/spec/groovy/**/*Behavior.groovy
567 src/spec/groovy/**/*Story.groovy
570 Supports the following options:
572 |_. Option |_. Value |
573 | @:properties@ | Hash of system properties available to the test case. |
574 | @:java_args@ | Arguments passed as is to the JVM. |
575 | @:format@ | Report format, either @:txt@ or @:xml@ |
580 Buildr offers support for using GroovyDoc to generate documentation from any Groovy sources in a project. This is done using the @doc@ task:
586 This will use the same @.groovy@ sources used by the @compile@ task to produce GroovyDoc results in the @target/doc/@ directory. By default, these sources are chosen only from the current project. However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
592 doc.from projects('foo:bar', 'foo')
600 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
603 The @doc@ task supports any option that the @groovydoc@ command does (e.g. @-windowtitle@). To pass an option to the GroovyDoc generator, simply specify it using the @doc@ method:
609 doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
613 The @doc@ task is *not* joint-compilation aware. Thus, it will only generate GroovyDoc for mixed-source projects, it will not attempt to generate both JavaDoc and GroovyDoc.
618 h3. Testing with Ruby
620 Buildr provides integration with some ruby testing frameworks, allowing you to test your Java code with state of the art tools.
622 Testing code is written in "Ruby":http://www.ruby-lang.org/en/ language, and is run by using "JRuby":http://jruby.codehaus.org/. That means you have access to all your Java classes and any Java or Ruby tool out there.
624 Because of the use of JRuby, you will notice that running ruby tests is faster when running Buildr on JRuby, as in this case there's no need to run another JVM.
626 p(tip). When not running on JRuby, Buildr will use the @JRUBY_HOME@ environment variable to find the JRuby installation directory. If no @JRUBY_HOME@ is set or it points to an empty directory, Buildr will prompt you to either install JRuby manually or let it extract it for you.
628 You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.4.0@ as of Buildr 1.3.5). For example:
636 "RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself.
638 To use this framework in your project you can select it with @test.using :rspec@.
640 This framework will search for the following patterns under your project:
643 src/spec/ruby/**/*_spec.rb
646 Supports the following options:
648 |_. Option |_. Value |
649 | @:gems@ | Hash of gems needed before running the tests. Keys are gem names, values are the required gem version. An example use of this option would be to require the ci_reporter gem to generate xml reports |
650 | @:requires@ | Array of ruby files to require before running the specs |
651 | @:format@ | Array of valid RSpec @--format@ option values. Defaults to html report on the @reports@ directory and text progress |
652 | @:output@ | File path to output dump. @false@ to supress output |
653 | @:fork@ | Run the tests on a new java vm. (enabled unless running on JRuby) |
654 | @:properties@ | Hash of system properties available to the test case. |
655 | @:java_args@ | Arguments passed as is to the JVM. (only when fork is enabled) |