Add a transform method when merging artifacts to transform file contents
[buildr.git] / doc / artifacts.textile
1 ---
2 layout: default
3 title: Artifacts
4 ---
5
6
7 In Buildr, almost everything is a file or a file task. You compile source files that come from the file system using dependencies found on the file system, generating even more files. But how do you get these dependencies to start with, and how do you share them with others?
8
9 Artifacts. We designed Buildr to work as a drop-in replacement for Maven 2.0, and share artifacts through the same local and remote repositories. Artifact tasks know how to download a file from one of the remote repositories, and install it in the local repository, where Buildr can find it. Packages know how to create files and upload them to remote repositories.
10
11 We'll get into all of that in a second, but first, let's introduce the artifact specification. It's a simple string that takes one of two forms:
12
13 {% highlight text %}
14 group:id:type:version
15 group:id:type:classifier:version
16 {% endhighlight %}
17
18 For example, @'org.apache.axis2:axis2:jar:1.2'@ refers to an artifact with group identifier org.apache.axis2, artifact identifier axis2, a JAR file with version 1.2.  Classifiers are typically used to distinguish between similar file types, for example, a source distribution and a binary distribution that otherwise have the same identifier and are both ZIP files.
19
20
21 h2(#specifying). Specifying Artifacts
22
23 If your Buildfile spells out @'org.apache.axis2:axis2:jar:1.2'@ more than once, you're doing something wrong.  Repeating the same string over and over will make your code harder to maintain.  You'll know that when you upgrade to a new version in one place, forget to do it in another, and end up with a mismatch.
24
25 You can use Ruby's syntax to do simple string substitution, for example:
26
27 {% highlight ruby %}
28 AXIS_VERSION = '1.2'
29
30 compile.with "org.apache.axis2:axis2:jar:#{AXIS_VERSION}"
31 {% endhighlight %}
32
33 Better yet, you can define all your artifacts at the top of the Buildfile and use constants to reference them in your project definition.  For example:
34
35 {% highlight ruby %}
36 AXIS2 = 'org.apache.axis2:axis2:jar:1.2'
37
38 compile.with AXIS2
39 {% endhighlight %}
40
41 Note that we're not using a separate constant for the version number.  In our experience, it's unnecessary.  The version number intentionally appears at the end of the string, where it stands out easily.
42
43 If you have a set of artifacts that belong to the same group and version, and that's quite common, you can use the @group@ shortcut:
44
45 {% highlight ruby %}
46 AXIOM  = group('axiom-api', 'axiom-impl', 'axiom-dom',
47   :under=>'org.apache.ws.commons.axiom', :version=>'1.2.4')
48 {% endhighlight %}
49
50 p(note). Buildr projects also define a @group@ attribute which can lead to some confusion.  If you want to define an artifact group within a project definition, you should use the explicit qualifier @Buildr::group@.
51
52 If you have several artifacts you always use together, consider placing them in an array.  Methods that accept lists of artifacts also accept arrays.  For example:
53
54 {% highlight ruby %}
55 OPENJPA = ['org.apache.openjpa:openjpa:jar:1.2.1',
56   'net.sourceforge.serp:serp:jar:1.12.0']
57 AXIS_OF_WS = [AXIS2, AXIOM]
58
59 compile.with OPENJPA, AXIS_OF_WS
60 {% endhighlight %}
61
62 Another way to group related artifacts together and access them individually is using the @struct@ shortcut.  For example:
63
64 {% highlight ruby %}
65 JAVAX = struct(
66   :activation  =>'javax.activation:activation:jar:1.1',
67   :persistence =>'javax.persistence:persistence-api:jar:1.0',
68   :stream      =>'stax:stax-api:jar:1.0.1',
69 )
70
71 compile.with JAVAX.persistence, OPENJPA
72 {% endhighlight %}
73
74 In our experience, using constants in this manner makes your Buildfile much easier to write and maintain.
75
76 And, of course, you can always place your artifact specifications in a separate file and require it into your Buildfile.  For example, if you're working on several different projects that all share the same artifacts:
77
78 {% highlight ruby %}
79 require '../shared/artifacts'
80 {% endhighlight %}
81
82 When you use @require@, Ruby always looks for a filename with the @.rb@ extension, so in this case it expects to find @artifacts.rb@ in the @shared@ directory.
83
84 One last thing.  You can also treat artifact specifications as hashes.  For example:
85
86 {% highlight ruby %}
87 AXIS = { :group=>'org.apache.axis2', :id=>'axis2', :version=>'1.2' }
88 compile.with AXIS
89 puts compile.dependencies.first.to_hash
90 => { :group=>'org.apache.axis2', :id=>'axis2',
91      :version=>'1.2', :type=>:jar }
92 {% endhighlight %}
93
94
95 h2(#repositories). Specifying Repositories
96
97 Buildr can download artifacts for you, but only if you tell it where to find them.  You need to specify at least one remote repository, from which to download these artifacts.
98
99 When you call @repositories.remote@, you get an array of URLs for the various remote repositories.  Initially, it's an empty array, to which you can add new repositories.  For example:
100
101 {% highlight ruby %}
102 repositories.remote << 'http://www.ibiblio.org/maven2/'
103 {% endhighlight %}
104
105 If your repository requires HTTP authentication, you can write,
106
107 {% highlight ruby %}
108 repositories.remote << URI.parse("http://user:password@repository.example.com")
109 {% endhighlight %}
110
111 or
112
113 {% highlight ruby %}
114 repositories.remote << { :url => "http://repository.example.com", :user => "user", :pass => "password" }
115 {% endhighlight %}
116
117 If you need to use a proxy server to access remote repositories, you can set the environment variable @HTTP_PROXY@ to the proxy server URL (use @HTTPS_PROXY@ for proxying HTTPS connections).  You can also work without a proxy for certain hosts by specifying the @NO_PROXY@ environment variable.  For example:
118
119 {% highlight sh %}
120 $ export HTTP_PROXY = 'http://myproxy:8080'
121 $ export NO_PROXY = '*.mycompany.com,localhost,special:800'
122 {% endhighlight %}
123
124 Alternatively you can use the Buildr options @proxy.http@ and @proxy.exclude@:
125
126 {% highlight ruby %}
127 options.proxy.http = 'http://myproxy:8080'
128 options.proxy.exclude << '*.mycompany.com'
129 options.proxy.exclude << 'localhost'
130 {% endhighlight %}
131
132 All the artifacts download into the local repository.  Since all your projects share the same local repository, you only need to download each artifact once. Buildr was designed to be used alongside Maven 2.0, for example, when migrating projects from Maven 2.0 over to Buildr.  By default it will share the same local repository, expecting the repository to be the @.m2/repository@ directory inside your home directory.
133
134 You can choose to relocate the local repository by giving it a different path, for example:
135
136 {% highlight ruby %}
137 repositories.local = '/usr/local/maven/repository'
138 {% endhighlight %}
139
140 That's one change you don't want to commit into the Buildfile, so the best place to do it is in the @buildr.rb@ file in the @.buildr@ directory under your home directory.
141
142 Buildr downloads artifacts when it needs to use them, for example, to compile a project.  You don't need to download artifacts directly.  Except when you do, for example, if you want to download all the latest artifacts and then go off-line.  It's as simple as:
143
144 {% highlight sh %}
145 $ buildr artifacts
146 {% endhighlight %}
147
148 h3(#mirrors). Mirrors
149
150 You can specify mirrors to override remote repositories. This is useful when you use a Nexus proxy or Artifactory, for example.
151
152 You can use the same syntax as @repositories.remote@, for example:
153
154 {% highlight ruby %}
155 repositories.mirrors << 'http://corporateserver001.com/repository'
156 {% endhighlight %}
157
158 This is even more useful when you place this in your user settings.
159
160 See the "Settings/Profiles section":/settings_profiles.html.
161
162
163 h2(#downloading). Downloading Artifacts
164
165 Within your buildfile you can download artifacts directly by invoking them, for example:
166
167 {% highlight ruby %}
168 artifact('org.apache.openjpa:openjpa:jar:1.2.1').invoke
169 artifacts(OPENJPA).each(&:invoke)
170 {% endhighlight %}
171
172 When you let Buildr download artifacts for you, or by invoking the artifact task yourself, it scans through the remote repositories assuming each repository follows the Maven 2 structure.  Starting from the root repository URL, it will look for each artifact using the path @group/id/version/id-version.type@ (or ...@/id-version-classifier.type@).  The group identifier becomes a path by turning periods (@.@) into slashes (@/@). So to find @org.apache.axis2:axis2:jar:1.2@, we're going to look for @org/apache/axis2/axis2/1.2/axis2-1.2.jar@.
173
174 You'll find a lot of open source Java libraries in public repositories that support this structure (for example, the "Ibiblio Maven":http://www.ibiblio.org/maven2/ repository).  And, of course, every remote repository you setup for your projects.
175
176 But there are exceptions to the rule.  Say we want to download the Dojo widget library and use it in our project.  It's available from the Dojo Web site, but that site doesn't follow the Maven repository conventions, so our feeble attempt to use existing remote repositories will fail.
177
178 We can still treat Dojo as an artifact, by telling Buildr where to download it from:
179
180 {% highlight ruby %}
181 DOJO = '0.2.2'
182
183 url = "http://download.dojotoolkit.org/release-#{DOJO}/dojo-#{DOJO}-widget.zip"
184 download(artifact("dojo:dojo:zip:widget:#{DOJO}")=>url)
185 {% endhighlight %}
186
187 Explaining how it works is tricky, skip if you don't care for the details.  On the other hand, it will give you a better understanding of Buildr/Rake, so if not now, come back and read it later.
188
189 We use the @artifact@ method to create an @Artifact@ task that references the Dojo widget in our local repository.  The @Artifact@ task is a file task with some additional behavior added by Buildr.  When you call @compile.with@, that's exactly what it does internally, turning each of your artifact specifications into an @Artifact@ task.
190
191 But the @Artifact@ task doesn't know how to download the Dojo widget, only how to handle conventional repositories.  So we're going to create a download task as well.  We use the @download@ method to create a file task that downloads the file from a remote URL.  (Of course, it will only download the file if it doesn't already exist.)
192
193 But which task gets used when?  We could have defined these tasks separately and used some glue code to make one use the other.  Instead, we call @download@ with the results of @artifact@.  Essentially, we're telling @download@ to use the same file path as @artifact@.  So now we have two file tasks that point to the very same file.  We wired them together.
194
195 You can't have more than one task pointing to the same file.  Rake's rule of the road.  What Rake does is merge the tasks together, creating a single file task for @artifact@, and then enhancing it with another action from @download@. One task, two actions.  Statistically, we've doubled the odds that at least one of these actions will manage to download the Dojo widget and install it in the local repository.
196
197 Since we ordered the calls to @artifact@ first and @download@ second, we know the actions will execute in that order.  But @artifact@ is slightly devilish: when its action runs, it adds another action to the end of the list.  So the @artifact@ action runs first, adds an action at the end, the @download@ action runs second, and downloads the Dojo widget for us.  The second @artifact@ action runs last, but checks that the file already exist and doesn't try to download it again.
198
199 Magic.
200
201 h3(#ssl). SSL and Self-signed certificates
202
203 There's always that Maven repository you learnt to hate, because it's using a faulty SSL certificate, or a self-signed one.
204
205 On top of installing that certificate everywhere, it's messing with your build!
206
207 To get out of there, you can use the environment variable SSL_CA_CERTS to point at a folder containing your certificates.
208 For example:
209
210 {% highlight bash %}
211 export SSL_CA_CERTS=/Users/john/certs
212 buildr package
213 {% endhighlight %}
214
215 You can also change the OpenSSL verify mode so it won't barf on your certificate. Use the environment variable @SSL_VERIFY_MODE@ to specify one of the following: @VERIFY_NONE@, @VERIFY_PEER@, @VERIFY_CLIENT_ONCE@, @VERIFY_FAIL_IF_NO_PEER_CERT@. See @OpenSSL::SSL@ for more info.
216
217 For example:
218 {% highlight bash %}
219 # Don't verify certificates
220 export SSL_VERIFY_MODE=VERIFY_NONE
221 buildr package
222 {% endhighlight %}
223
224 h2(#install_upload). Install and Upload
225
226 Generally you use artifacts that download from remote repositories into the local repository, or artifacts packaged by the project itself (see "Packaging":packaging.html), which are then installed into the local repository and uploaded to the release server.
227
228 Some artifacts do not fall into either category.  In this example we're going to download a ZIP file, extract a JAR file from it, and use that JAR file as an artifact.  We would then expect to install this JAR in the local repository and upload it to the release server, where it can be shared with other projects.
229
230 So let's start by creating a task that downloads the ZIP, and another one to extract it and create the JAR file:
231
232 {% highlight ruby %}
233 app_zip = download('target/app.zip'=>url)
234 bean_jar = file('target/app/bean.jar'=>unzip('target/app'=>app_zip))
235 {% endhighlight %}
236
237 When you call @artifact@, it returns an @Artifact@ task that points to the artifact file in the local repository, downloading the file if it doesn't already exist.  You can override this behavior by enhancing the task and creating the file yourself (you may also want to create a POM file).  Or much simpler, call the @from@ method on the artifact and tell it where to find the source file.
238
239 So the next step is to specify the artifact and tell it to use the extracted JAR file:
240
241 {% highlight ruby %}
242 bean = artifact('example.com:beans:jar:1.0').from(bean_jar)
243 {% endhighlight %}
244
245 The artifact still points to the local repository, but when we invoke the task it copies the source file over to the local repository, instead of attempting a download.
246
247 Use the @install@ method if you want the artifact and its POM installed in the local repository when you run the @install@ task.  Likewise, use the @upload@ method if you want the artifact uploaded to the release server when you run the @upload@ task.  You do not need to do this on artifacts downloaded from a remote server, or created with the @package@ method, the later are automatically added to the list of installed/uploaded artifacts.
248
249 Our example ends by including the artifact in the @install@ and @upload@ tasks:
250
251 {% highlight ruby %}
252 install bean
253 upload bean
254 {% endhighlight %}
255
256 p(tip).  Calling the @install@ (and likewise @upload@) method on an artifact run @buildr install@.  If you need to download and install an artifact, invoke the task directly with @install(<artifact>).invoke@.
257
258
259 We'll talk more about installing and uploading in the next chapter, but right now we're going to "package some artifacts":packaging.html.