Add a transform method when merging artifacts to transform file contents
[buildr.git] / doc / languages.textile
1 ---
2 layout: default
3 title: Languages
4 ---
5
6
7 h2(#java). Java
8
9
10 h3. Compiling Java
11
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.
13
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@.
15
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.
17
18 The Java compiler supports the following options:
19
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. |
28
29 h3. ECJ
30
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:
33 {% highlight ruby %}
34 compile.using :ecj
35 {% endhighlight %}
36
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@:
39
40 {% highlight yaml %}
41 ecj: 3.5.1
42 {% endhighlight %}
43
44 h3.  Testing with Java
45
46 h4. JUnit
47
48 The default test framework for Java projects is "JUnit 4":http://www.junit.org.
49
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@.
51
52 The JUnit test framework supports the following options:
53
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. |
60
61 For example, to pass properties to the test case:
62
63 {% highlight ruby %}
64 test.using :properties=>{ :currency=>'USD' }
65 {% endhighlight %}
66
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.
68
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. |
73
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.
75
76 In addition, you can get a consolidated XML or HTML report by running the @junit:report@ task.  For example:
77
78 {% highlight sh %}
79 $ buildr test junit:report test=all
80 $ firefox report/junit/html/index.html
81 {% endhighlight %}
82
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.
84
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:
86
87 {% highlight yaml %}
88 junit: 4.4
89 jmock: 2.0
90 {% endhighlight %}
91
92
93 h4. TestNG
94
95 You can use "TestNG":http://testng.org instead of JUnit.  To select TestNG as the test framework, add this to your project:
96
97 {% highlight ruby %}
98 test.using :testng
99 {% endhighlight %}
100
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)
102
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.
104
105 The TestNG test framework supports the following options:
106
107 |_. Option        |_. Value |
108 | @:properties@   | Hash of system properties available to the test case. |
109 | @:java_args@    | Arguments passed as is to the JVM. |
110
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:
112
113 {% highlight yaml %}
114 testng: 5.7
115 {% endhighlight %}
116
117
118 h4. JBehave
119
120 "JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language.
121
122 To use JBehave in your project you can select it with @test.using :jbehave@.
123
124 This framework will search for the following patterns under your project:
125
126 {% highlight text %}
127 src/spec/java/**/*Behaviour.java
128 {% endhighlight %}
129
130 Supports the following options:
131
132 |_. Option        |_. Value |
133 | @:properties@   | Hash of system properties available to the test case. |
134 | @:java_args@    | Arguments passed as is to the JVM. |
135
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:
137
138 {% highlight yaml %}
139 jbehave: 1.0.1
140 {% endhighlight %}
141
142
143 h3. Documentation
144
145 Buildr offers support for using JavaDoc to generate documentation from any Java sources in a project.  This is done using the @doc@ task:
146
147 {% highlight sh %}
148 $ buildr doc
149 {% endhighlight %}
150
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):
152
153 {% highlight ruby %}
154 define 'foo' do
155   # ...
156
157   doc.from projects('foo:bar', 'foo')
158
159   define 'bar' do
160     # ...
161   end
162 end
163 {% endhighlight %}
164
165 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
166 @foo@.
167
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:
169
170 {% highlight ruby %}
171 define 'foo' do
172   # ...
173
174   doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
175 end
176 {% endhighlight %}
177
178
179 h2(#scala). Scala
180
181 Before using Scala, you must first @require@ the Scala compiler:
182
183 {% highlight ruby %}
184 require 'buildr/scala'
185 {% endhighlight %}
186
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@:
188
189 {% highlight yaml %}
190 scala.version: 2.8.0.Beta1  # Pick your version
191 {% endhighlight %}
192
193 Or, you can do the same programmatically:
194
195 {% highlight yaml %}
196 # Must be placed before require 'buildr/scala'
197 Buildr.settings.build['scala.version'] = "2.8.0.Beta1"
198 {% endhighlight %}
199
200 You may also determine the version in use by querying the @Scala.version@ attribute:
201
202 {% highlight ruby %}
203 Scala.version       # => '2.8.0'
204 {% endhighlight %}
205
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.
207
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@.
210
211
212 h3. Compiling Scala
213
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.
215
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.
217
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.
219
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.
221
222 When using the Scala compiler, if you don't specify the packaging type, it defaults to JAR.
223
224 The Scala compiler supports the following options:
225
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. |
236
237 h4. Fast Scala Compiler
238
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.
240
241 (Note @fsc@ is not compatible with @zinc@ incremental compilation.)
242
243 h4. Rebuild detection
244
245 *Scala 2.7*
246
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.
248
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.
250
251 *Scala 2.8*
252
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:
254
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*)
260
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:
262
263 {% highlight ruby %}
264 compile.using :make => :all
265 {% endhighlight %}
266
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).
268
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).
270
271 *Scala 2.9 and later*
272
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,
274
275 1) By setting the compiler's option directly,
276
277 {% highlight ruby %}
278 compile.using :incremental => true
279
280 compile.options.incremental = true  # same as above
281 {% endhighlight %}
282
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).
284
285 2) By setting the project's @scalac_options.incremental@,
286
287 {% highlight ruby %}
288 project.scalac_options.incremental = true
289 {% endhighlight %}
290
291 3) By setting the global @scalac.incremental@ option,
292
293 in your @buildfile@:
294
295 {% highlight ruby %}
296 Buildr.settings.build['scalac.incremental'] = true
297 {% endhighlight %}
298
299 or in your @build.yaml@:
300
301 {% highlight yaml %}
302 scalac.incremental: true
303 {% endhighlight %}
304
305 h4. Support for different Scala versions
306
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.
308
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.
310
311 You may select the Scala version by dynamically in different ways,
312
313 1) By reassigning @SCALA_HOME@ at the top of the buildfile (*before* @require 'buildr/scala'@):
314
315 {% highlight ruby %}
316 ENV['SCALA_HOME'] = ENV['SCALA28_HOME']
317
318 require 'buildr/scala'
319 ...
320 {% endhighlight %}
321
322 2) By setting the @scala.version@ build property in your build.yaml file:
323
324 {% highlight yaml %}
325 scala.version: 2.9.1.RC1
326 {% endhighlight %}
327
328 3) By setting the @scala.version@ build property in your buildfile:
329
330 {% highlight ruby %}
331 require 'buildr/scala'
332 ...
333 Buildr.settings.build['scala.version'] = '2.10-M6'
334 {% endhighlight %}
335
336 h3. Testing with Scala
337
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.
339
340 {% highlight ruby %}
341 test.using(:scalatest)
342 {% endhighlight %}
343
344 h4. ScalaTest
345
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.
347
348 Buildr automatically detects and runs tests that extend the @org.scalatest.Suite@ interface.
349
350 A very simplistic test class might look like,
351
352 {% highlight scala %}
353 class MySuite extends org.scalatest.FunSuite {
354   test("addition") {
355     val sum = 1 + 1
356     assert(sum === 2)
357   }
358 }
359 {% endhighlight %}
360
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:
362
363 {% highlight scala %}
364 import org.scalatest._
365
366 class PropertyTestSuite extends FunSuite {
367   var properties = Map[String, Any]()
368
369   test("testProperty") {
370     assert(properties("name") === "value")
371   }
372
373   protected override def runTests(testName: Option[String],
374     reporter: Reporter, stopper: Stopper, includes: Set[String],
375     excludes: Set[String], properties: Map[String, Any])
376   {
377     this.properties = properties;
378     super.runTests(testName, reporter, stopper,
379                    includes, excludes, properties)
380   }
381 }
382 {% endhighlight %}
383
384 h4. Specs
385
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.
387
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.
389
390 A simple specification might look like this:
391
392 {% highlight scala %}
393 import org.specs._
394 import org.specs.runner._
395
396 object StringSpecs extends Specification {
397   "empty string" should {
398     "have a zero length" in {
399       "".length mustBe 0
400     }
401   }
402 }
403 {% endhighlight %}
404
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@:
406
407 {% highlight ruby %}
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'
412
413 define 'killer-app' do
414   ...
415
416   test.with MOCKITO, CGLIB, ASM, OBJENESIS
417 end
418 {% endhighlight %}
419
420 The dependencies for Specs's optional features are defined "here":http://code.google.com/p/specs/wiki/RunningSpecs#Dependencies.
421
422 h4. ScalaCheck
423
424 You may use ScalaCheck inside ScalaTest- and Specs-inherited classes.  Here is an example illustrating checks inside a ScalaTest suite,
425
426 {% highlight scala %}
427 import org.scalatest.prop.PropSuite
428 import org.scalacheck.Arbitrary._
429 import org.scalacheck.Prop._
430
431 class MySuite extends PropSuite {
432
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)
438   }
439
440   test(
441     "list concatenation using a test method",
442     (a: List[Int], b: List[Int]) => a.size + b.size == (a ::: b).size
443   )
444 }
445 {% endhighlight %}
446
447
448 h3. Documentation
449
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:
451
452 {% highlight sh %}
453 $ buildr doc
454 {% endhighlight %}
455
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):
457
458 {% highlight ruby %}
459 define 'foo' do
460   # ...
461
462   doc.from projects('foo:bar', 'foo')
463
464   define 'bar' do
465     # ...
466   end
467 end
468 {% endhighlight %}
469
470 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
471 @foo@.
472
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:
474
475 {% highlight ruby %}
476 define 'foo' do
477   # ...
478
479   doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
480 end
481 {% endhighlight %}
482
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:
484
485 {% highlight ruby %}
486 define 'foo' do
487   doc.using :vscaladoc
488 end
489 {% endhighlight %}
490
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.
492
493 h2(#kotlin). Kotlin
494
495 h3. Compiling Kotlin
496
497 To start using Kotlin, you must first require it on your Buildfile:
498
499 {% highlight ruby %}
500 require 'buildr/kotlin'
501 {% endhighlight %}
502
503 Any project with a .kt file under the @src/main/kotlin@ directory (by default), compiling them into @target/classes@.
504
505 If the project has any java files, they will be compiled using javac.
506
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. |
516
517 h2(#groovy). Groovy
518
519 h3. Compiling Groovy
520
521 Before using the Groovy compiler, you must first require it on your buildfile:
522
523 {% highlight ruby %}
524 require 'buildr/java/groovyc'
525 {% endhighlight %}
526
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.
528
529 If the project has java sources in @src/main/java@ they will get compiled using the groovyc joint compiler.
530
531 Sources found in @src/test/groovy@ are compiled into the @target/test/classes@.
532
533 If you don't specify the packaging type, it defaults to JAR.
534
535 The Groovy compiler supports the following options:
536
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. |
552
553 h3. Testing with Groovy
554
555 h4. EasyB
556
557 "EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/.
558
559 Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy.
560
561 To use this framework in your project you can select it with @test.using :easyb@.
562
563 This framework will search for the following patterns under your project:
564
565 {% highlight text %}
566 src/spec/groovy/**/*Behavior.groovy
567 src/spec/groovy/**/*Story.groovy
568 {% endhighlight %}
569
570 Supports the following options:
571
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@ |
576
577
578 h3. Documentation
579
580 Buildr offers support for using GroovyDoc to generate documentation from any Groovy sources in a project.  This is done using the @doc@ task:
581
582 {% highlight sh %}
583 $ buildr doc
584 {% endhighlight %}
585
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):
587
588 {% highlight ruby %}
589 define 'foo' do
590   # ...
591
592   doc.from projects('foo:bar', 'foo')
593
594   define 'bar' do
595     # ...
596   end
597 end
598 {% endhighlight %}
599
600 With this configuration, the @doc@ task will use sources from both @foo:bar@ and
601 @foo@.
602
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:
604
605 {% highlight ruby %}
606 define 'foo' do
607   # ...
608
609   doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
610 end
611 {% endhighlight %}
612
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.
614
615
616 h2(#ruby).  Ruby
617
618 h3.  Testing with Ruby
619
620 Buildr provides integration with some ruby testing frameworks, allowing you to test your Java code with state of the art tools.
621
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.
623
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.
625
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.
627
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:
629
630 {% highlight yaml %}
631 jruby: 1.3.1
632 {% endhighlight %}
633
634 h4.  RSpec
635
636 "RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself.
637
638 To use this framework in your project you can select it with @test.using :rspec@.
639
640 This framework will search for the following patterns under your project:
641
642 {% highlight text %}
643 src/spec/ruby/**/*_spec.rb
644 {% endhighlight %}
645
646 Supports the following options:
647
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) |