buildr 1.3.4 → 1.3.5

Sign up to get free protection for your applications and to get access to all the features.
Files changed (105) hide show
  1. data/CHANGELOG +35 -0
  2. data/README.rdoc +1 -1
  3. data/Rakefile +1 -1
  4. data/buildr.buildfile +6 -1
  5. data/buildr.gemspec +10 -9
  6. data/doc/_config.yml +1 -0
  7. data/doc/_layouts/default.html +25 -19
  8. data/doc/artifacts.textile +0 -36
  9. data/doc/building.textile +0 -38
  10. data/doc/contributing.textile +51 -15
  11. data/doc/css/default.css +11 -4
  12. data/doc/css/print.css +32 -24
  13. data/doc/download.textile +2 -1
  14. data/doc/extending.textile +10 -20
  15. data/doc/images/1442160941-frontcover.jpg +0 -0
  16. data/doc/images/asf-logo.png +0 -0
  17. data/doc/images/note.png +0 -0
  18. data/doc/images/project-structure.png +0 -0
  19. data/doc/images/tip.png +0 -0
  20. data/doc/images/zbuildr.png +0 -0
  21. data/doc/index.textile +39 -17
  22. data/doc/{getting_started.textile → installing.textile} +2 -67
  23. data/doc/languages.textile +50 -52
  24. data/doc/more_stuff.textile +154 -62
  25. data/doc/packaging.textile +0 -82
  26. data/doc/preface.textile +41 -15
  27. data/doc/projects.textile +0 -18
  28. data/doc/quick_start.textile +210 -0
  29. data/doc/scripts/install-linux.sh +10 -2
  30. data/doc/settings_profiles.textile +1 -33
  31. data/doc/testing.textile +6 -32
  32. data/lib/buildr.rb +2 -1
  33. data/lib/buildr/core.rb +6 -0
  34. data/lib/buildr/core/application.rb +2 -5
  35. data/lib/buildr/core/build.rb +29 -19
  36. data/lib/buildr/core/compile.rb +22 -4
  37. data/lib/buildr/core/filter.rb +2 -4
  38. data/lib/buildr/core/project.rb +5 -4
  39. data/lib/buildr/core/shell.rb +198 -0
  40. data/lib/buildr/core/test.rb +2 -0
  41. data/lib/buildr/core/transports.rb +18 -19
  42. data/lib/buildr/core/util.rb +178 -9
  43. data/lib/buildr/groovy.rb +1 -0
  44. data/lib/buildr/groovy/bdd.rb +5 -5
  45. data/lib/buildr/groovy/shell.rb +48 -0
  46. data/lib/buildr/ide/eclipse.rb +148 -36
  47. data/lib/buildr/ide/eclipse/java.rb +53 -0
  48. data/lib/buildr/ide/eclipse/plugin.rb +68 -0
  49. data/lib/buildr/ide/eclipse/scala.rb +66 -0
  50. data/lib/buildr/java/bdd.rb +16 -8
  51. data/lib/buildr/java/cobertura.rb +44 -13
  52. data/lib/buildr/java/commands.rb +5 -3
  53. data/lib/buildr/java/org/apache/buildr/JavaTestFilter.class +0 -0
  54. data/lib/buildr/java/org/apache/buildr/JavaTestFilter.java +18 -0
  55. data/lib/buildr/java/packaging.rb +2 -2
  56. data/lib/buildr/java/rjb.rb +1 -1
  57. data/lib/buildr/java/test_result.rb +48 -1
  58. data/lib/buildr/java/tests.rb +8 -5
  59. data/lib/buildr/packaging/artifact_namespace.rb +1 -1
  60. data/lib/buildr/packaging/package.rb +6 -2
  61. data/lib/buildr/packaging/zip.rb +10 -1
  62. data/lib/buildr/packaging/ziptask.rb +5 -2
  63. data/lib/buildr/scala.rb +1 -0
  64. data/lib/buildr/scala/bdd.rb +17 -8
  65. data/lib/buildr/scala/compiler.rb +66 -21
  66. data/lib/buildr/scala/org/apache/buildr/SpecsSingletonRunner$.class +0 -0
  67. data/lib/buildr/scala/org/apache/buildr/SpecsSingletonRunner.class +0 -0
  68. data/lib/buildr/scala/org/apache/buildr/SpecsSingletonRunner.scala +35 -0
  69. data/lib/buildr/scala/shell.rb +55 -0
  70. data/lib/buildr/scala/tests.rb +6 -5
  71. data/lib/buildr/shell.rb +180 -0
  72. data/rakelib/doc.rake +2 -3
  73. data/rakelib/jekylltask.rb +42 -32
  74. data/rakelib/package.rake +4 -2
  75. data/rakelib/rspec.rake +3 -3
  76. data/rakelib/setup.rake +7 -1
  77. data/rakelib/stage.rake +9 -2
  78. data/rakelib/stage.rake~ +213 -0
  79. data/spec/core/application_spec.rb +84 -1
  80. data/spec/core/build_spec.rb +54 -2
  81. data/spec/core/common_spec.rb +1 -1
  82. data/spec/core/compile_spec.rb +2 -1
  83. data/spec/core/extension_spec.rb +93 -0
  84. data/spec/core/test_spec.rb +2 -2
  85. data/spec/core/transport_spec.rb +1 -1
  86. data/spec/groovy/bdd_spec.rb +6 -6
  87. data/spec/groovy/compiler_spec.rb +1 -0
  88. data/spec/ide/eclipse_spec.rb +262 -72
  89. data/spec/java/{ant.rb → ant_spec.rb} +0 -0
  90. data/spec/java/bdd_spec.rb +15 -0
  91. data/spec/java/cobertura_spec.rb +9 -1
  92. data/spec/java/emma_spec.rb +1 -1
  93. data/spec/java/java_spec.rb +26 -0
  94. data/spec/java/packaging_spec.rb +9 -7
  95. data/spec/java/{test_coverage_spec.rb → test_coverage_helper.rb} +6 -4
  96. data/spec/java/tests_spec.rb +22 -0
  97. data/spec/packaging/archive_spec.rb +14 -0
  98. data/spec/packaging/artifact_spec.rb +2 -2
  99. data/spec/packaging/packaging_spec.rb +97 -2
  100. data/spec/sandbox.rb +3 -1
  101. data/spec/scala/bdd_spec.rb +17 -48
  102. data/spec/scala/compiler_spec.rb +31 -2
  103. data/spec/scala/tests_spec.rb +1 -0
  104. data/spec/spec_helpers.rb +12 -0
  105. metadata +145 -148
@@ -2,27 +2,53 @@
2
2
  layout: preface
3
3
  ---
4
4
 
5
- div(title). !{width:20em}images/buildr-hires.png!
5
+ p(title). !images/zbuildr.png!
6
6
 
7
- #(toc) "Getting Started":getting_started.html
8
- # "Projects":projects.html
9
- # "Building":building.html
10
- # "Artifacts":artifacts.html
11
- # "Packaging":packaging.html
12
- # "Testing":testing.html
13
- # "Settings & Profiles":settings_profiles.html
14
- # "Languages":languages.html
15
- # "More Stuff":more_stuff.html
16
- # "Extending Buildr":extending.html
17
- # "Contributing":contributing.html
7
+ <ol class='toc'>
8
+ <li>"Quick Start":quick_start.html</li>
9
+ <li>"Installing and Running":installing.html</li>
10
+ <li>"Projects":projects.html</li>
11
+ <li>"Building":building.html</li>
12
+ <li>"Artifacts":artifacts.html</li>
13
+ <li>"Packaging":packaging.html</li>
14
+ <li>"Testing":testing.html</li>
15
+ <li>"Settings & Profiles":settings_profiles.html</li>
16
+ <li>"Languages":languages.html</li>
17
+ <li>"More Stuff":more_stuff.html</li>
18
+ <li>"Extending Buildr":extending.html</li>
19
+ <li>"Contributing":contributing.html</li>
20
+ </ol>
18
21
 
19
22
 
20
- p(preface). Copyright 2007-2009 Apache Buildr
23
+ p(preface). !images/asf-logo.png!
24
+
25
+ Copyright 2007-2009 Apache Buildr
21
26
 
22
27
  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
23
28
 
24
- "http://www.apache.org/licenses/LICENSE-2.0":http://www.apache.org/licenses/LICENSE-2.0
29
+ http://www.apache.org/licenses/LICENSE-2.0
25
30
 
26
31
  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
27
32
 
28
- p(preface). <blank>
33
+
34
+
35
+ <div class='preface quotes'>
36
+ "Daniel Spiewak":http://www.codecommit.com/blog:
37
+
38
+ bq. If you think about it, the question isn’t “Why use Buildr?”, it’s really “Why use anything else?” The advantages afforded by Buildr are so substantial, I really can’t see myself going with any other tool, at least not when I have a choice.
39
+
40
+ "Tristan Juricek":http://tristanhunt.com/:
41
+
42
+ bq. That’s still the strongest sell: it builds everything I need, and as I’ve needed more, I just got things working without a lot of fuss.
43
+
44
+ "Matthieu Riou":http://offthelip.org/:
45
+
46
+ bq. We used to rely on Ant, with a fairly extensive set of scripts. It worked but was expensive to maintain. The biggest mistake afterward was to migrate to Maven2. I could write pages of rants explaining all the problems we ran into and we still ended up with thousands of lines of XML.
47
+
48
+ "Martin Grotzke":http://www.javakaffee.de/blog/:
49
+
50
+ bq. The positive side effect for me as a java user is that I learn a little ruby, and that’s easy but lots of fun… :-)
51
+ </div>
52
+
53
+
54
+ p(preface).
@@ -12,7 +12,6 @@ Feed it a project definition, and Buildr will set up all these tasks for you. Th
12
12
 
13
13
  The remainder of this guide deals with what it takes to build a project. But first, let's pick up a sample project to work with. We'll call it _killer-app_:
14
14
 
15
- <notextile>
16
15
  {% highlight ruby %}
17
16
  require 'buildr'
18
17
 
@@ -58,7 +57,6 @@ define 'killer-app' do
58
57
 
59
58
  end
60
59
  {% endhighlight %}
61
- </notextile>
62
60
 
63
61
  A project definition requires four pieces of information: the project name, group identifier, version number and base directory. The project name ... do we need to explain why its necessary? The group identifier and version number are used for packaging and deployment, we'll talk more about that in the "Packaging":packaging.html section. The base directory lets you find files inside the project.
64
62
 
@@ -102,7 +100,6 @@ The @projects@ method takes a list of names and returns a list of projects. If
102
100
 
103
101
  Let's illustrate this with a few examples:
104
102
 
105
- <notextile>
106
103
  {% highlight ruby %}
107
104
  puts projects.inspect
108
105
  => [project("killer-app"), project("killer-app:teh-api") ... ]
@@ -119,7 +116,6 @@ puts project('killer-app:teh-api').inspect
119
116
  puts project('killer-app').project('teh-api').inspect
120
117
  => project("killer-app:teh-api")
121
118
  {% endhighlight %}
122
- </notextile>
123
119
 
124
120
  To see a list of all projects defined in your Buildfile run @buildr help:projects@.
125
121
 
@@ -128,7 +124,6 @@ h2(#tasks). Running Project Tasks
128
124
 
129
125
  Most times, you run tasks like @build@ or @package@ that operate on the current project and recursively on its sub-projects. The "current project" is the one that uses the current working directory. So if you're in the @la-web/src@ directory looking at source files, _la-web_ is the current project. For example:
130
126
 
131
- <notextile>
132
127
  {% highlight sh %}
133
128
  # build killer-app and all its sub-projects
134
129
  $ buildr build
@@ -141,11 +136,9 @@ $ buildr test
141
136
  $ cd ../la-web
142
137
  $ buildr package
143
138
  {% endhighlight %}
144
- </notextile>
145
139
 
146
140
  You can use the project's full name to invoke one of its tasks directly, and it doesn't matter which directory you're in. For example:
147
141
 
148
- <notextile>
149
142
  {% highlight sh %}
150
143
  # build killer-app and all its sub-projects
151
144
  $ buildr killer-app:build
@@ -156,11 +149,9 @@ $ buildr killer-app:teh-impl:test
156
149
  # package only la-web
157
150
  $ buildr killer-app:la-web:package
158
151
  {% endhighlight %}
159
- </notextile>
160
152
 
161
153
  Buildr provides the following tasks that you can run on the current project, or on a specific project by prefixing them with the project's full name:
162
154
 
163
- <notextile>
164
155
  {% highlight text %}
165
156
  clean # Clean files generated during a build
166
157
  compile # Compile all projects
@@ -172,7 +163,6 @@ package # Create packages
172
163
  test # Run all test cases
173
164
  uninstall # Remove previously installed packages
174
165
  {% endhighlight %}
175
- </notextile>
176
166
 
177
167
  To see a list of all the tasks provided by Buildr run @buildr help:tasks@.
178
168
 
@@ -183,7 +173,6 @@ We mentioned the group identifier, version number and base directory. These are
183
173
 
184
174
  There are two ways to set project properties. You can pass them as a hash when you call @define@, or use accessors to set them on the project directly. For example:
185
175
 
186
- <notextile>
187
176
  {% highlight ruby %}
188
177
  define 'silly', :version=>'1.0' do
189
178
  project.group = 'acme'
@@ -194,7 +183,6 @@ puts project('silly').version
194
183
  puts project('silly').group
195
184
  => acme
196
185
  {% endhighlight %}
197
- </notextile>
198
186
 
199
187
  Project properties are inherited. You can specify them once in the parent project, and they'll have the same value in all its sub-projects. In the example, we only specify the version number once, for use in all sub-projects.
200
188
 
@@ -209,7 +197,6 @@ The @path_to@ method takes an array of strings and concatenates them into a path
209
197
 
210
198
  For example:
211
199
 
212
- <notextile>
213
200
  {% highlight ruby %}
214
201
  # Relative to the current project
215
202
  path_to('src', 'main', 'java')
@@ -220,7 +207,6 @@ _('src/main/java')
220
207
  # Relative to the teh-impl project
221
208
  project('teh-impl')._('src/main/java')
222
209
  {% endhighlight %}
223
- </notextile>
224
210
 
225
211
 
226
212
  h2(#defining). Defining The Project
@@ -229,7 +215,6 @@ The project definition itself gives you a lot of pre-canned tasks to start with,
229
215
 
230
216
  Since the project definition executes each time you run Buildr, you don't want to perform any work directly inside the project definition block. Rather, you want to use it to specify how different build task work when you invoke them. Here's an example to illustrate the point:
231
217
 
232
- <notextile>
233
218
  {% highlight ruby %}
234
219
  define 'silly' do
235
220
  puts 'Running buildr'
@@ -239,7 +224,6 @@ define 'silly' do
239
224
  end
240
225
  end
241
226
  {% endhighlight %}
242
- </notextile>
243
227
 
244
228
  Each time you run Buildr, it will execute the project definition and print out "Running buildr". We also extend the @build@ task, and whenever we run it, it will print "Building silly". Incidentally, @build@ is the default task, so if you run Buildr with no arguments, it will print both messages while executing the build. If you run Buildr with a different task, say @clean@, it will only print the first message.
245
229
 
@@ -253,7 +237,6 @@ One project can reference another ahead of its definition. If Buildr detects a
253
237
 
254
238
  In this example we define one project in terms of another, using the same dependencies, so we only need to specify them once:
255
239
 
256
- <notextile>
257
240
  {% highlight ruby %}
258
241
  define 'bar' do
259
242
  compile.with project('foo').compile.dependencies
@@ -263,7 +246,6 @@ define 'foo' do
263
246
  compile.with ..lots of stuff..
264
247
  end
265
248
  {% endhighlight %}
266
- </notextile>
267
249
 
268
250
  One last thing to remember. Actually three, but they all go hand in hand.
269
251
 
@@ -0,0 +1,210 @@
1
+ ---
2
+ layout: default
3
+ title: Quick Start
4
+ ---
5
+
6
+ This quick start guide is meant to be a _very_ simple introduction to Buildr and its most basic concepts. However, despite its basic level, we will still cover most of the concepts you will ever need to be productive with Buildr. We will leave out some important things (like "sub-projects":projects.html), and we will over-simplify some other concepts (such as "artifacts":artifacts.html). Nevertheless, most Buildr projects never need to go beyond the techniques contained within these pages.
7
+
8
+ *No knowledge of Ruby is assumed.* Buildr is designed to be a very intuitive, very easy-to-use tool. You can create buildfiles which describe incredibly intricate projects, write custom tasks which do things far beyond Ant, and still never need to pick up more than a smattering of Ruby syntax. With that said, if you do know Ruby, Buildr's DSL will seem very natural and welcoming. We do assume that you have already "downloaded and installed":installing.html Buildr and are ready to put the tool to good use.
9
+
10
+
11
+ h2(#first-project). Your First Project
12
+
13
+ Much like Maven, Buildr is oriented around projects and tasks. You define your project in a concise, declarative fashion and most common tasks (such as compilation and testing) will be made available to you "at no extra charge". Most of the project definition is contained within the _buildfile_ -- or _Buildfile_, if you're really in love with the Make convention -- a single file sitting at the root of your project. A project definition does not need to be any more complicated than the following:
14
+
15
+ {% highlight ruby %}
16
+ define 'killer-app'
17
+ {% endhighlight %}
18
+
19
+ h3. Compiling
20
+
21
+ Of course, this isn't really giving Buildr much information. What it can't learn from the buildfile, Buildr will figure out by inspecting your directory structure. Java sources are expected to exist within the @src/main/java/@ directory. If Buildr finds these sources, it will automatically configure the compilation to source that directory, depositing the results in the @target/classes/@ directory (all under the project directory of course). We can run this compilation using the following command:
22
+
23
+ {% highlight sh %}
24
+ $ buildr compile
25
+ {% endhighlight %}
26
+
27
+ Information about the classpath and dependencies is described "later on":#dependencies.
28
+
29
+ p(tip). By default, Buildr projects assume the Java language and the @src/main/java/@ source directory. You can also have projects in the Scala or Groovy language (both languages support joint compilation with Java). To use Scala, place your @.scala@ files in the @src/main/scala/@ directory and include the following invocation at the head of your buildfile: @require 'buildr/scala'@ Similarly, Groovy expects sources in the @src/main/groovy/@ directory and necessitates @require 'buildr/groovy'@ (see "languages":languages.html for more information).
30
+
31
+ The @compile@ task will also detect _any_ files which exist under the @src/main/resources/@ directory. These resources are copied verbatim to the @target/resources/@ directory as part of the compilation task. Buildr also performs some basic change detection to minimize compilation. If your source files haven't changed since the last compile, then they will not be recompiled.
32
+
33
+ h3. Packaging
34
+
35
+ At some point, we're going to want to wrap up our classes and produce a single JAR file for distribution. Buildr can certainly help us with this, but we are going to need to provide it with a little bit more information. Specifically, we need to say the type of package to produce (e.g. @:jar@, @:war@, etc) as well as the current version of our project. This information is placed within the buildfile:
36
+
37
+ {% highlight ruby %}
38
+ define 'killer-app' do
39
+ project.version = '0.1.0'
40
+ package :jar
41
+ end
42
+ {% endhighlight %}
43
+
44
+ The @project.version@ attribute can be any value you like. Even non-numeric versions are perfectly acceptable (e.g. @'ikj-0.3.1-E'@). This version -- coupled with the packaging information -- will be used to generate a JAR file: @killer-app-0.1.0.jar@. As would be expected, this file is placed within the @target/@ directory when the following command is run:
45
+
46
+ {% highlight sh %}
47
+ $ buildr package
48
+ {% endhighlight %}
49
+
50
+ The @package@ task depends upon the @compile@ task, so if a rebuild is necessary prior to the creation of the JAR, Buildr will see to it.
51
+
52
+ We can also chain tasks together in a single invocation. For example, we may want to clean all of the old compilation results prior to recompiling and generating a packaged result:
53
+
54
+ {% highlight sh %}
55
+ $ buildr clean package
56
+ {% endhighlight %}
57
+
58
+ The @clean@ task simply removes the @target/@ directory, effectively wiping out any compilation results like class files or resources.
59
+
60
+ h3. Directory Structure
61
+
62
+ As you may have noticed, Buildr does have some default notions about what a project should look like and how it should be organized. We think that these defaults are quite nice and make for a more navigable project. However, we do understand that not all projects are exactly alike. Buildr's "layouts":extending.html#layouts make it possible for any project to easily change these defaults. For example, this would allow you to easily migrate a project that had been based on a different directory structure, such as the @src/@ and @bin/@ convention often used by Ant.
63
+
64
+
65
+ h2(#dependencies). Dependencies
66
+
67
+ So far, we have seen how Buildr can automatically infer what amounts to dozens of lines of @build.xml@ contents, all based on a buildfile and a directory structure. However, the best is yet to come. Buildr also provides Maven-style dependency management (but without the long loading times!). In other words, you specify each dependent library using a string descriptor and Buildr figures out how to download and configure your classpath (the library descriptors are just a Ruby array, therefore they are separated by commas (@,@)). You must specify at least one remote repository so that Buildr knows from where to download these libraries. For example, we can configure our project to reference the "Apache Commons CLI":http://commons.apache.org/cli/ library and download libraries from the Ibiblio repository:
68
+
69
+ {% highlight ruby %}
70
+ repositories.remote << 'http://www.ibiblio.org/maven2'
71
+
72
+ define 'killer-app' do
73
+ project.version = '0.1.0'
74
+ compile.with 'commons-cli:commons-cli:jar:1.2'
75
+ package :jar
76
+ end
77
+ {% endhighlight %}
78
+
79
+ This sort of dependency declaration should look quite familiar if you are at all familiar with Maven. The general format for an artifact descriptor is _groupId:artifactId:packageType:version_. Any Maven artifacts included in this fashion will be retrieved from the "list of remote repositories":artifacts.html#repositories (in this case, Ibiblio) and installed in your local repository at @~/.m2/repository/@.
80
+
81
+ p(tip). You can search the global repository of artifacts at sites like "MvnBrowser":http://www.mvnbrowser.com. Simply enter the name of the library you are looking for, and the search should pull up the groupId, artifactId and a list of available versions.
82
+
83
+ Unfortunately, not all libraries are quite as simple as Commons CLI. Many libraries (such as Apache Wicket) have dependencies of their own. While we may be able to _compile_ against Apache Wicket without these extra libraries on our classpath, we cannot actually _run_ our application without its transitive dependencies. To avoid tracking down each of these dependencies and adding them manually, we can simply use the @transitive@ directive (this is how Maven behaves by default):
84
+
85
+ {% highlight ruby %}
86
+ repositories.remote << 'http://www.ibiblio.org/maven2'
87
+
88
+ define 'killer-app' do
89
+ project.version = '0.1.0'
90
+ compile.with transitive('org.apache.wicket:wicket:jar:1.4-rc6')
91
+ package :jar
92
+ end
93
+ {% endhighlight %}
94
+
95
+ The @compile.with@ property accepts a full array of comma-separated artifacts, making it possible to specify any number of dependencies as necessary. Of course, such a long list of verbose string descriptors could get very tiresome and messy. For this reason, it is conventional to assign each dependency to a constant (e.g. @WICKET@) which is declared just above the project in the buildfile and passed to @compile.with@ in a clean, easy-to-read style:
96
+
97
+ {% highlight ruby %}
98
+ repositories.remote << 'http://www.ibiblio.org/maven2'
99
+
100
+ WICKET = transitive('org.apache.wicket:wicket:jar:1.4-rc6')
101
+ SLF4J = 'org.slf4j:slf4j-jdk14:jar:1.5.8'
102
+
103
+ define 'killer-app' do
104
+ project.version = '0.1.0'
105
+ compile.with WICKET, SLF4J
106
+ package :jar
107
+ end
108
+ {% endhighlight %}
109
+
110
+ Unfortunate as it may seem, not all libraries are available in Maven repositories. While most of the major libraries (e.g. Hibernate, Spring, etc) are kept updated by intrepid volunteers, some of the more obscure frameworks are left out in the cold. An example of one such framework is "DBPool":http://www.snaq.net/java/DBPool, a very fast connection pool designed to integrate with JDBC. However, like most Java libraries, DBPool does provide a zip archive which contains the JAR file, as well as some documentation and perhaps a license or two.
111
+
112
+ Almost magically, we can instruct Buildr to get the DBPool artifact from this URL. Buildr will treat this download just like any other artifact, retrieving it when requried by the @compile@ task. However, unlike a normal Maven artifact, Buildr will do some extra processing once the download is complete. It will actually dig into the downloaded archive, detect and extract the JAR file, installing it into the local repository just like any other artifact:
113
+
114
+ {% highlight ruby %}
115
+ DBPOOL = 'net.snaq:dbpool:jar:4.8.3'
116
+ download artifact(DBPOOL) => 'http://www.snaq.net/java/DBPool/DBPool_v4.8.3.zip'
117
+
118
+ define 'killer-app' do
119
+ project.version '0.1.0'
120
+ compile.with DBPool
121
+ package :jar
122
+ end
123
+ {% endhighlight %}
124
+
125
+ This is one area where Buildr's dependency management vastly excedes Maven's. With Maven, you would have to install the DBPool dependency manually. Buildr's auto-magical download and extraction keeps the dependency definitions centralized within the buildfile, available to your entire team and automatically resolved as needed by the compilation tasks.
126
+
127
+
128
+ h2(#testing). Testing
129
+
130
+ Buildr supports auto-magical integration with a number of mainstream testing frameworks. For Java, this includes the ubiquitus JUnit4, as well as TestNG and a number of others. Scala supports Specs and ScalaTest, while Groovy supports EasyB. Configuration is as simple as placing your test sources in the appropriate directory. In the case of JUnit or TestNG, this would be @src/test/java/@. Once these tests are in place, we can run them using the @test@ task:
131
+
132
+ {% highlight sh %}
133
+ $ buildr test
134
+ {% endhighlight %}
135
+
136
+ When the @test@ task runs, it will ensure that your main sources are compiled, as well as the tests themselves. In the case of JUnit4, test classes are auto-detected based on which base class they extend (@TestCase@). These tests will be invoked using the special test classpath. This classpath includes all of the dependencies passed to @compile.with@ along with the dependencies required for testing. Thus, Buildr will actually go out and download JUnit 4.5 (if necessary) and place that JAR on the classpath in order to run your tests. It is also possible to add artifacts specifically required for testing. So, if your tests make use of the Commons Collections library, but your main sources do not, you can include that dependency only for the tests by using the @test.with@ property. This functions identically to @compile.with@:
137
+
138
+ {% highlight ruby %}
139
+ define 'killer-app' do
140
+ project.version = '0.1.0'
141
+ compile.with 'commons-cli:commons-cli:jar:1.2'
142
+ test.with 'commons-collections:commons-collections:jar:3.2'
143
+ package :jar
144
+ end
145
+ {% endhighlight %}
146
+
147
+ Of course, not everyone _likes_ JUnit4. As mentioned previously, Buildr supports a number of test frameworks. It is possible to use TestNG instead of JUnit4 by setting the @test.using@ property to @:testng@:
148
+
149
+ {% highlight ruby %}
150
+ define 'killer-app' do
151
+ project.version = '0.1.0'
152
+ compile.with 'commons-cli:commons-cli:jar:1.2'
153
+ test.with 'commons-collections:commons-collections:jar:3.2'
154
+ test.using :testng
155
+ package :jar
156
+ end
157
+ {% endhighlight %}
158
+
159
+ Note that only one test framework per-project may be used. This may seem like an obvious restriction given that both frameworks introduced so far have used the same directory, but other frameworks such as Specs and EasyB do not follow the same convention. In cases of ambiguity (for example, when tests are present in both @src/test/java/@ _and_ @src/spec/scala/@), only one test framework will be chosen, but this choice is not well-defined. When in doubt, explicitly specify the test framework with the @test.using@ property. This overrides Buildr's auto-detection and ensures sane behavior.
160
+
161
+ Other test frameworks are documented "here":testing.html and "here":languages.html.
162
+
163
+
164
+ h2(#custom-tasks). Custom Tasks
165
+
166
+ If there is one area in which Buildr excels, it is defining custom tasks. This is something which is notoriously difficult in both Ant and Maven, often requiring separate Java plugins and mountains of code simply to perform basic tasks. For example, let's imagine that we wanted to define a @run@ task which would compile and run our "killer-app" project. This is a simple matter of invoking the @java@ command against our main class:
167
+
168
+ {% highlight ruby %}
169
+ define 'killer-app' do
170
+ project.version = '0.1.0'
171
+ package :jar
172
+
173
+ task :run => :compile do
174
+ system 'java -cp target/classes org.apache.killer.Main'
175
+ end
176
+ end
177
+ {% endhighlight %}
178
+
179
+ This code defines a new task, @run@, which depends upon the @compile@ task. This task only performs a single operation: it invokes the @system@ method, passing the relevant command as a string. Note that the @system@ method documentation may be found "here":http://www.ruby-doc.org/core/classes/Kernel.html#M005971. Tasks use real Ruby (actually, the entire buildfile is real Ruby too), so if you are familiar with that language, then you should be right at home writing custom tasks in Buildr. We can invoke this task in the following way:
180
+
181
+ {% highlight sh %}
182
+ $ buildr killer-app:run
183
+ {% endhighlight %}
184
+
185
+ This works, but it's clumsy. The reason we had to give the "@killer-app:@" prefix is because we defined the @run@ task _within_ our project, rather than outside of the @define@ block. However, if we define @run@ outside of the project, then we don't really have access to the @compile@ task (which is project-specific). The solution here is a bit of magic known as @local_task@. This is how tasks like @compile@ and @test@, which are technically project-specific (think: instance methods) can be invoked without the fully-qualified project name:
186
+
187
+ {% highlight ruby %}
188
+ local_task :run
189
+
190
+ define 'killer-app' do
191
+ project.version '0.1.0'
192
+
193
+ package :jar
194
+
195
+ task :run => :compile do
196
+ system 'java -cp target/classes org.apache.killer.Main'
197
+ end
198
+ end
199
+ {% endhighlight %}
200
+
201
+ Now, we can invoke @run@ exactly the way we want, with a minimum of wasted characters:
202
+
203
+ {% highlight sh %}
204
+ $ buildr run
205
+ {% endhighlight %}
206
+
207
+
208
+ h2(#summary). Summary
209
+
210
+ As long as this guide was, we have barely even scratched the surface of Buildr's true power. This was meant only to get you up and running as quickly as possible, exploiting some of Buildr's unique features to ease your build process. For more comprehensive documentation, start reading about "projects in Buildr":projects.html and work your way from there.
@@ -16,6 +16,7 @@
16
16
  if [ -z `which ruby` ] ; then
17
17
  echo "You do not have Ruby 1.8.6 ..."
18
18
  # yum comes first since some people have apt-get installed in addition to yum.
19
+ # urpmi is added in case of mandriva : apt-get or yum are working for mandriva too
19
20
  if [ `which yum` ] ; then
20
21
  echo "Installing Ruby using yum"
21
22
  sudo yum install ruby rubygems ruby-devel gcc
@@ -24,7 +25,7 @@ if [ -z `which ruby` ] ; then
24
25
  # ruby package does not contain RDoc, IRB, etc; ruby-full is a meta-package.
25
26
  # build-essentials not installed by default in Ubuntu, required for C extensions.
26
27
  sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential
27
- # RubyGems broken on Ubunutu, installing directly from source.
28
+ # RubyGems broken on Ubuntu, installing directly from source.
28
29
  echo "Installing RubyGems from RubyForge"
29
30
  wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
30
31
  tar xzf rubygems-1.3.1.tgz
@@ -34,8 +35,15 @@ if [ -z `which ruby` ] ; then
34
35
  rm -rf rubygems-1.3.1
35
36
  # ruby is same as ruby1.8, we need gem that is same as gem1.8
36
37
  sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
38
+ elif [ `which urpmi` ] ; then
39
+ echo "Installing Ruby using urpmi"
40
+ sudo urpmi ruby rubygems ruby-devel gcc
41
+ if [ $? -ne 0 ] ; then
42
+ echo "URPMI install error"
43
+ exit 1
44
+ fi
37
45
  else
38
- echo "Can only install Ruby 1.8.6 using apt-get or yum, and can't find either one"
46
+ echo "Can only install Ruby 1.8.6 using apt-get, yum or urpmi, and can't find any of them"
39
47
  exit 1
40
48
  fi
41
49
  echo
@@ -10,30 +10,24 @@ Buildr uses several environment variables that help you control how it works. So
10
10
 
11
11
  For example:
12
12
 
13
- <notextile>
14
13
  {% highlight sh %}
15
14
  $ export HTTP_PROXY=http://myproxy:8080
16
15
  {% endhighlight %}
17
- </notextile>
18
16
 
19
17
  There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:
20
18
 
21
- <notextile>
22
19
  {% highlight sh %}
23
20
  $ buildr test=no
24
21
  {% endhighlight %}
25
- </notextile>
26
22
 
27
- For convenience, when you set environment variables on the command line, the variable name is case insensitive, you can use either @test=no@ or @TEST=no@. Any other way (@export@, @ENV@, etc) the variable names are case sensitive.
23
+ For convenience, the environment variables @TEST@ and @DEBUG@ are case insensitive, you can use either @test=no@ or @TEST=no@. Any other environment variable names are case sensitive.
28
24
 
29
25
  You can also set environment variables from within your Buildfile. For example, if you discover that building your project requires gobs of JVM heap space, and you want all other team members to run with the same settings:
30
26
 
31
- <notextile>
32
27
  {% highlight ruby %}
33
28
  # This project builds a lot of code.
34
29
  ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
35
30
  {% endhighlight %}
36
- </notextile>
37
31
 
38
32
  Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even @require@).
39
33
 
@@ -58,12 +52,10 @@ p(note). Buildr does not check any of the arguments in @JAVA_OPTS@. A common mi
58
52
 
59
53
  Some extensions may use additional environment variables, and of course, you can always add your own. This example uses two environment variables for specifying the username and password:
60
54
 
61
- <notextile>
62
55
  {% highlight ruby %}
63
56
  repositories.upload_to[:username] = ENV['USERNAME']
64
57
  repositories.upload_to[:password] = ENV['PASSWORD']
65
58
  {% endhighlight %}
66
- </notextile>
67
59
 
68
60
 
69
61
  h2(#personal). Personal Settings
@@ -76,7 +68,6 @@ The prefered way to store personal settings is to create a @.buildr/settings.yam
76
68
 
77
69
  Here's an example @settings.yaml@:
78
70
 
79
- <notextile>
80
71
  {% highlight yaml %}
81
72
  # The repositories hash is read automatically by buildr.
82
73
  repositories:
@@ -101,11 +92,9 @@ im:
101
92
  usr: notifier@company-jabber.com
102
93
  pwd: secret
103
94
  {% endhighlight %}
104
- </notextile>
105
95
 
106
96
  Later your buildfile or addons can reference user preferences using the hash returned by the @Buildr.settings.user@ accessor.
107
97
 
108
- <notextile>
109
98
  {% highlight ruby %}
110
99
  task 'relase-notification' do
111
100
  usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
@@ -113,7 +102,6 @@ task 'relase-notification' do
113
102
  jabber.msg("We are pleased to announce the last stable version #{VERSION}")
114
103
  end
115
104
  {% endhighlight %}
116
- </notextile>
117
105
 
118
106
 
119
107
  h2(#build). Build Settings
@@ -122,7 +110,6 @@ Build settings are local to the project being built, and are placed in the @buil
122
110
 
123
111
  They help keep the buildfile and build.yaml file simple and readable, working to the advantages of each one. Example for build settings are gems, repositories and artifacts used by that build.
124
112
 
125
- <notextile>
126
113
  {% highlight yaml %}
127
114
  # This project requires the following ruby gems, buildr addons
128
115
  gems:
@@ -151,24 +138,20 @@ twitter:
151
138
  jira:
152
139
  uri: https://jira.corp.org
153
140
  {% endhighlight %}
154
- </notextile>
155
141
 
156
142
  When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.
157
143
 
158
144
  Artifacts defined on @build.yaml@ can be referenced on your buildfile by supplying the ruby symbol to the @Buildr.artifact@ and @Buildr.artifacts@ methods. The @compile.with@, @test.with@ methods can also be given these names.
159
145
 
160
- <notextile>
161
146
  {% highlight ruby %}
162
147
  define 'my_project' do
163
148
  compile.with artifacts(:log4j, :j2ee)
164
149
  test.with :spring, :j2ee
165
150
  end
166
151
  {% endhighlight %}
167
- </notextile>
168
152
 
169
153
  Build settings can be retreived using the @Buildr.settings.build@ accessor.
170
154
 
171
- <notextile>
172
155
  {% highlight ruby %}
173
156
  task 'create_patch' do
174
157
  patch = Git.create_patch :interactive => true
@@ -178,7 +161,6 @@ Build settings can be retreived using the @Buildr.settings.build@ accessor.
178
161
  end
179
162
  end
180
163
  {% endhighlight %}
181
- </notextile>
182
164
 
183
165
 
184
166
  h2(#variable). Non constant settings
@@ -189,7 +171,6 @@ The loading order allows you to place global settings that affect all your build
189
171
 
190
172
  Here's an example @buildr.rb@:
191
173
 
192
- <notextile>
193
174
  {% highlight ruby %}
194
175
  # Only I should know that
195
176
  repositories.upload_to[:username] = 'assaf'
@@ -197,7 +178,6 @@ repositories.upload_to[:password] = 'supersecret'
197
178
  # Search here first, it's faster
198
179
  repositories.remote << 'http://inside-the-firewall'
199
180
  {% endhighlight %}
200
- </notextile>
201
181
 
202
182
 
203
183
  h2(#environments). Environments
@@ -206,35 +186,29 @@ One common use case is adapting the build to different environments. For exampl
206
186
 
207
187
  So let's start by talking about the build environment. Buildr has a global attributes that indicates which environment it's running in, accessible from the @environment@ method. You can set the current build environment in one of two ways. Using the @-e/--environment@ command line option:
208
188
 
209
- <notextile>
210
189
  {% highlight sh %}
211
190
  $ buildr -e test
212
191
  (in /home/john/project, test)
213
192
  {% endhighlight %}
214
- </notextile>
215
193
 
216
194
  Or by setting the environment variable @BUILDR_ENV@:
217
195
 
218
- <notextile>
219
196
  {% highlight text %}
220
197
  $ export BUILDR_ENV=production
221
198
  $ buildr
222
199
  (in /home/john/project, production)
223
200
  {% endhighlight %}
224
- </notextile>
225
201
 
226
202
  Unless you tell it otherwise, Buildr assumes you're developing and sets the environment to @development@.
227
203
 
228
204
  Here's a simple example for handling different environments within the Buildfile:
229
205
 
230
- <notextile>
231
206
  {% highlight ruby %}
232
207
  project 'db-module' do
233
208
  db = (environment == 'production' ? 'oracle' : 'hsql')
234
209
  resources.from(_("src/main/#{db}"))
235
210
  end
236
211
  {% endhighlight %}
237
- </notextile>
238
212
 
239
213
  We recommend picking a convention for your different environments and following it across all your projects. For example:
240
214
 
@@ -252,7 +226,6 @@ The profiles file is a YAML file called @profiles.yaml@ that you place in the sa
252
226
 
253
227
  For example, to support three different database configurations, we could write:
254
228
 
255
- <notextile>
256
229
  {% highlight yaml %}
257
230
  # HSQL, don't bother storing to disk.
258
231
  development:
@@ -269,11 +242,9 @@ production:
269
242
  db: oracle
270
243
  jdbc: oracle:thin:@bigstrong:1521:mighty
271
244
  {% endhighlight %}
272
- </notextile>
273
245
 
274
246
  Here's a simple example for a buildfile that uses the profile information:
275
247
 
276
- <notextile>
277
248
  {% highlight ruby %}
278
249
  project 'db-module' do
279
250
  # Copy SQL files specific for the database we're using,
@@ -283,7 +254,6 @@ project 'db-module' do
283
254
  resources.filter.using :jdbc=>Buildr.settings.profile['jdbc']
284
255
  end
285
256
  {% endhighlight %}
286
- </notextile>
287
257
 
288
258
  The @profile@ method returns the current profile, selected based on the current "environment":#environments. You can get a list of all profiles by calling @profiles@.
289
259
 
@@ -293,7 +263,6 @@ We recommend following conventions and using the same environments in all your p
293
263
 
294
264
  YAML allows you to use anchors (@&@), similar to ID attributes in XML, reference the anchored element (@*@) elsewhere, and merge one element into another (@<<@). For example:
295
265
 
296
- <notextile>
297
266
  {% highlight yaml %}
298
267
  # We'll reference this one as common.
299
268
  development: &common
@@ -306,7 +275,6 @@ test:
306
275
  <<: *common
307
276
  jdbc: hsqldb:file:testdb
308
277
  {% endhighlight %}
309
- </notextile>
310
278
 
311
279
 
312
280
  You can "learn more about YAML here":http://www.yaml.org, and use this handy "YAML quick reference":http://www.yaml.org/refcard.html.