lock_jar 0.10.0 → 0.10.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +59 -59
  3. data/.travis.yml +8 -8
  4. data/CHANGELOG.md +30 -21
  5. data/Gemfile +13 -13
  6. data/Guardfile +9 -9
  7. data/README.md +375 -375
  8. data/Rakefile +24 -24
  9. data/bundler/Gemfile +21 -21
  10. data/bundler/LICENSE.txt +22 -22
  11. data/bundler/README.md +29 -29
  12. data/bundler/Rakefile +2 -2
  13. data/bundler/lib/lock_jar_bundler/bundler.rb +35 -35
  14. data/bundler/lib/lock_jar_bundler/piggy_back.rb +97 -97
  15. data/bundler/lib/lock_jar_bundler/version.rb +5 -5
  16. data/bundler/lib/lock_jar_bundler.rb +4 -4
  17. data/bundler/lock_jar_bundler.gemspec +24 -24
  18. data/bundler/spec/Jarfile +2 -2
  19. data/bundler/spec/dummy_gem/dummy_gem.gemspec +19 -19
  20. data/bundler/spec/lock_jar_bundler_spec.rb +48 -48
  21. data/bundler/spec/spec_helper.rb +88 -88
  22. data/lib/lock_jar/buildr.rb +144 -144
  23. data/lib/lock_jar/bundler.rb +154 -154
  24. data/lib/lock_jar/cli.rb +64 -64
  25. data/lib/lock_jar/domain/artifact.rb +123 -123
  26. data/lib/lock_jar/domain/dsl.rb +187 -187
  27. data/lib/lock_jar/domain/dsl_helper.rb +83 -83
  28. data/lib/lock_jar/domain/gem_dsl.rb +44 -44
  29. data/lib/lock_jar/domain/jarfile_dsl.rb +46 -46
  30. data/lib/lock_jar/domain/lockfile.rb +113 -113
  31. data/lib/lock_jar/maven.rb +111 -111
  32. data/lib/lock_jar/registry.rb +92 -92
  33. data/lib/lock_jar/resolver.rb +95 -95
  34. data/lib/lock_jar/runtime.rb +359 -355
  35. data/lib/lock_jar/version.rb +3 -3
  36. data/lib/lock_jar.rb +172 -177
  37. data/lock_jar.gemspec +27 -27
  38. data/spec/fixtures/Jarfile +13 -13
  39. data/spec/fixtures/Jarfile2 +1 -0
  40. data/spec/lock_jar/class_loader_spec.rb +57 -57
  41. data/spec/lock_jar/cli_spec.rb +100 -100
  42. data/spec/lock_jar/domain/dsl_helper_spec.rb +52 -52
  43. data/spec/lock_jar/domain/dsl_spec.rb +57 -57
  44. data/spec/lock_jar/maven_spec.rb +23 -23
  45. data/spec/lock_jar/resolver_spec.rb +26 -26
  46. data/spec/lock_jar/runtime_spec.rb +26 -26
  47. data/spec/lock_jar_spec.rb +372 -295
  48. data/spec/pom.xml +34 -34
  49. data/spec/spec_helper.rb +38 -38
  50. data/spec/support/helper.rb +44 -44
  51. metadata +3 -1
data/README.md CHANGED
@@ -1,375 +1,375 @@
1
- # LockJar
2
-
3
- [![Build Status](https://secure.travis-ci.org/mguymon/lock_jar.png?branch=master)](http://travis-ci.org/mguymon/lock_jar)
4
-
5
- LockJar manages Java Jars for Ruby. Powered by [Naether](https://github.com/mguymon/naether) to
6
- create a frankenstein of Bundler and Maven. A Jarfile ([example](https://github.com/mguymon/lock_jar/blob/master/spec/Jarfile)) is used to generate a Jarfile.lock that contains all the resolved jar dependencies. The Jarfile.lock can be used to populate the classpath.
7
-
8
- LockJar can:
9
- * Be used directly in MRI 1.9.3, 2.0, 2.1 and JRuby 1.6.x, 1.7.x
10
- * From the [command line](https://github.com/mguymon/lock_jar/blob/master/README.md#command-line)
11
- * [Triggered from a Gem install](https://github.com/mguymon/lock_jar/blob/master/README.md#gem-integration)
12
- * [Integrated into Buildr](https://github.com/mguymon/lock_jar/blob/master/README.md#buildr-integration)
13
- * Experimental [integration with Bundler](https://github.com/mguymon/lock_jar/blob/master/README.md#bundler-integration)
14
-
15
- https://github.com/mguymon/lock_jar
16
-
17
- [RDoc](http://rubydoc.info/gems/lock_jar/frames)
18
-
19
- ## Install
20
-
21
- gem install lock_jar
22
-
23
- ## Ruby Usage
24
-
25
- JRuby is natively supported. Ruby 1.9.3 and 2.1 uses [Rjb](http://rjb.rubyforge.org/) to proxy over JNI.
26
-
27
- ### Jarfile
28
-
29
- A Jarfile is a simple file using a Ruby DSL for defining a project's dependencies using the following
30
- methods:
31
-
32
- * **local_repo( path )**: Set the local Maven repository, this were dependencies are downloaded to.
33
- * **remote_repo( url )**: Add additional url of remote Maven repository.
34
- * **group( groups )**: Set the group for nested jar or pom. A single or Array of groups can be set.
35
- * **jar( notations, opts = {} )**: Add Jar dependency in artifact notation, artifact:group:version as the bare minimum. A single or Array of notations can be passed. Default group is _default_, can be specified by setting _opts = { :group => ['group_name'] }_
36
- * **local( path )**: Add a local path to a Jar
37
- * **pom( pom_path, opts = {} )**: Add a local Maven pom, default is to load dependencies for `runtime` and `compile` scopes. To select the scopes to be loaded from the pom, set the _opts = { :scopes => ['test'] }_
38
-
39
- #### Example Jarfile
40
-
41
- repository 'http://repository.jboss.org/nexus/content/groups/public-jboss'
42
-
43
- // Default group is default
44
- jar "org.apache.mina:mina-core:2.0.4"
45
- local 'spec/fixtures/naether-0.13.0.jar'
46
-
47
- group 'runtime' do
48
- jar 'org.apache.tomcat:servlet-api:jar:6.0.35'
49
- end
50
-
51
- group 'test' do
52
- jar 'junit:junit:jar:4.10', :group => 'test'
53
- end
54
-
55
- ### Resolving dependencies
56
-
57
- **LockJar.lock( *args )**: Using a Jarfile, creates a lock file. Depending on the type of arg, a different configuration is set.
58
- * _[String]_ will set the Jarfile path, e.g. `'/somewhere/Jarfile.different'`. Default jarfile is `'Jarfile'`
59
- * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
60
- * **:download** _[Boolean]_ if true, will download jars to local repo. Defaults to true.
61
- * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
62
- * **:lockfile** _[String]_ sets the Jarfile.lock path. Default lockfile is `'Jarfile.lock'`.
63
-
64
- When the Jarfile is locked, the transitive dependencies are resolved and saved to the Jarfile.lock file.
65
-
66
- Example of locking a Jarfile to a Jarfile.lock
67
-
68
- LockJar.lock
69
-
70
-
71
- ### Jarfile.lock
72
-
73
- The _Jarfile.lock_ generated is a YAML file containing information on how to handle the classpath for grouped dependencies and their nested transitive dependencies.
74
-
75
- #### The Jarfile.lock
76
-
77
- ---
78
- version: 0.7.0
79
- groups:
80
- default:
81
- dependencies:
82
- - ch.qos.logback:logback-classic:jar:0.9.24
83
- - ch.qos.logback:logback-core:jar:0.9.24
84
- - com.metapossum:metapossum-scanner:jar:1.0
85
- - com.slackworks:modelcitizen:jar:0.2.2
86
- - commons-beanutils:commons-beanutils:jar:1.8.3
87
- - commons-io:commons-io:jar:1.4
88
- - commons-lang:commons-lang:jar:2.6
89
- - commons-logging:commons-logging:jar:1.1.1
90
- - junit:junit:jar:4.7
91
- - org.apache.mina:mina-core:jar:2.0.4
92
- - org.slf4j:slf4j-api:jar:1.6.1
93
- artifacts:
94
- - jar:org.apache.mina:mina-core:jar:2.0.4:
95
- transitive:
96
- org.slf4j:slf4j-api:jar:1.6.1: {}
97
- - pom:spec/pom.xml:
98
- scopes:
99
- - runtime
100
- - compile
101
- transitive:
102
- com.metapossum:metapossum-scanner:jar:1.0:
103
- junit:junit:jar:4.7: {}
104
- commons-io:commons-io:jar:1.4: {}
105
- commons-beanutils:commons-beanutils:jar:1.8.3:
106
- commons-logging:commons-logging:jar:1.1.1: {}
107
- ch.qos.logback:logback-classic:jar:0.9.24:
108
- ch.qos.logback:logback-core:jar:0.9.24: {}
109
- commons-lang:commons-lang:jar:2.6: {}
110
- development:
111
- dependencies:
112
- - com.typesafe:config:jar:0.5.0
113
- artifacts:
114
- - jar:com.typesafe:config:jar:0.5.0:
115
- transitive: {}
116
- test:
117
- dependencies:
118
- - junit:junit:jar:4.10
119
- - org.hamcrest:hamcrest-core:jar:1.1
120
- artifacts:
121
- - jar:junit:junit:jar:4.10:
122
- transitive:
123
- org.hamcrest:hamcrest-core:jar:1.1: {}
124
- ...
125
-
126
-
127
-
128
- ### Accessing Jars
129
- **LockJar.install(*args)**: Download Jars in the Jarfile.lock
130
- * _[String]_ will set the Jarfile.lock path, e.g. `'Better.lock'`. Default lock file is `'Jarfile.lock'`.
131
- * _[Array<String>]_ will set the groups, e.g. `['compile','test']`. Defaults group is _default_.
132
- * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
133
- * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
134
-
135
- **LockJar.list(*args)**: Lists all dependencies as notations for groups from the Jarfile.lock. Depending on the type of arg, a different configuration is set.
136
- * _[String]_ will set the Jarfile.lock path, e.g. `'Better.lock'`. Default lock file is `'Jarfile.lock'`.
137
- * _[Array<String>]_ will set the groups, e.g. `['default', 'runtime']`. Defaults group is _default_.
138
- * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
139
- * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
140
- * **:local_paths** _[Boolean]_ converts the notations to paths of jars in the local repo
141
- * **:resolve** _[Boolean]_ to true will make transitive dependences resolve before returning list of jars
142
-
143
- **LockJar.load(*args)**: Loads all dependencies to the classpath for groups from the Jarfile.lock. Default group is _default_. Default lock file is _Jarfile.lock_.
144
- * _[String]_ will set the Jarfile.lock, e.g. `'Better.lock'`
145
- * _[Array<String>]_ will set the groups, e.g. `['default', 'runtime']`
146
- * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
147
- * **:local_repo** _[String]_ sets the local repo path
148
- * **:resolve** _[Boolean]_ to true will make transitive dependences resolve before loading to classpath
149
-
150
- Once a _Jarfile.lock_ is generated, you can list all resolved jars by
151
-
152
- jars = LockJar.list
153
-
154
- or directly load all Jars into the classpath
155
-
156
- jars = LockJar.load
157
-
158
- Do not forget, if you change your _Jarfile_, you have to re-generate the _Jarfile.lock_.
159
-
160
- See also [loading Jars into a custom ClassLoader](https://github.com/mguymon/lock_jar/wiki/ClassLoader).
161
-
162
- ### Shortcuts
163
-
164
- #### Skipping the Jarfile
165
-
166
- You can skip the _Jarfile_ and _Jarfile.lock_ to directly play with dependencies by passing a block to _LockJar.lock_, _LockJar.list_, and _LockJar.load_
167
-
168
- #### Lock without a Jarfile
169
-
170
- LockJar.lock do
171
- jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
172
- end
173
-
174
- #### List without a Jarfile.lock
175
-
176
- LockJar.list do
177
- jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
178
- end
179
-
180
- #### Load without a Jarfile.lock
181
-
182
- LockJar.load do
183
- jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
184
- end
185
-
186
- Since you skipped the locking part, mostly likely you will need to resolve the dependences in the block, just pass the _:resolve => true_ option to enable dependency resolution (also works for _LockJar.list_).
187
-
188
- LockJar.load( :resolve => true ) do
189
- jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
190
- end
191
-
192
- ## Command line
193
-
194
- There is a simple command line helper. You can lock a _Jarfile_ with the following command
195
-
196
- lockjar lock
197
-
198
- List jars in a _Jarfile.lock_ with
199
-
200
- lockjar list
201
-
202
- Download all jars in a _Jarfile.lock_ with
203
-
204
- lockjar install
205
-
206
- _lockjar_ _--help_ will give you list of all commands and their options.
207
-
208
- ## Gem Integration
209
-
210
- ### Installing Jars with a Gem
211
-
212
- LockJar can be triggered when a Gem is installed by using a [Gem extension](http://docs.rubygems.org/read/chapter/20#extensions)
213
- of type _Rakefile_. The cavaet is the task to install the jars must be the default for the Rakefile.
214
-
215
- A Gem spec with _Rakefile_ extension:
216
-
217
- Gem::Specification.new do |s|
218
- s.extensions = ["Rakefile"]
219
- end
220
-
221
- Rakefile with default to install Jars using LockJar:
222
-
223
- task :default => :prepare
224
-
225
- task :prepare do
226
- require 'lock_jar'
227
-
228
- # get jarfile relative the gem dir
229
- lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
230
-
231
- LockJar.install( :lockfile => lockfile )
232
- end
233
-
234
- #### Work around for Rakefile default
235
-
236
- The downside of using the Gem extension Rakefile is it requires the default to
237
- point at the task to download the jars (from the example Rakefile,
238
- `task :default => :prepare`). To get around this, I used a Rakefile called
239
- _PostInstallRakefile_ to handle the `task :prepare`. When packaging the gem, _PostInstallRakefile_ is
240
- renamed to `Rakefile`.
241
-
242
- ### Manually installing Jars
243
-
244
- Instead of rely in a Rakefile to install Jars when the Gem is installed, Jars can be manually installed. The following
245
- Ruby needs to be called before calling `LockJar.load`. Only Jars that are missing are downloaded.
246
-
247
- #get jarfile relative the gem dir
248
- lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
249
-
250
- # Download any missing Jars
251
- LockJar.install( lockfile )
252
-
253
- ### Loading
254
-
255
- With the Jars installed, loading the classpath for the Gem is simple.
256
- As part of the load process for the Gem (an entry file that is required, etc) use the following:
257
-
258
- #get jarfile relative the gem dir
259
- lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
260
-
261
- # Loads the ClassPath with Jars from the lockfile
262
- LockJar.load( :lockfile => lockfile )
263
-
264
- See also [loading Jars into a custom ClassLoader](https://github.com/mguymon/lock_jar/wiki/ClassLoader).
265
-
266
- ## Buildr Integration
267
-
268
- LockJar integrates with [Buildr](http://buildr.apache.org/) using an [Addon](https://github.com/mguymon/lock_jar/blob/master/lib/lock_jar/buildr.rb). This allows the Jarfile to be defined directly into a _buildfile_. A global LockJar definition can be set and is inherited to all projects. Each project may have its own LockJar definition. A lock file is generated per project based on the project name.
269
-
270
- A new Buildr task is added to generate the lockfile for all projects
271
-
272
- buildr lock_jar:lock
273
-
274
- and a task per project to generate the lockfile for a single project
275
-
276
- buildr <app>:<project>:lock_jar:lock
277
-
278
- In a project, you can access an Array of notations using the **lock_jars** method, accepts same parameters as [LockJar.list](https://github.com/mguymon/lock_jar#accessing-jars)
279
-
280
- lock_jars()
281
-
282
-
283
- The _default_ group dependencies are automatically added to the classpath for compiling. The _test_ group dependencies are automatically added to the classpath for tests. Do not forget, if you change the LockJar definitions, you have to rerun the **lock_jar:lock** task.
284
-
285
-
286
- ### Example
287
-
288
- Sample buildfile with LockJar
289
-
290
- require 'lock_jar/buildr'
291
-
292
- # app definition, inherited into all projects
293
- lock_jar do
294
-
295
- group 'test' do
296
- jar 'junit:junit:jar:4.10'
297
- end
298
- end
299
-
300
- define 'app' do
301
-
302
- def 'project1' do
303
- lock_jar do
304
- jar "org.apache.mina:mina-core:2.0.4"
305
- end
306
- end
307
-
308
- def 'project2' do
309
- lock_jar do
310
- pom 'pom.xml'
311
- end
312
- end
313
-
314
- end
315
-
316
- Generated the following lock files using **lock_jar:lock**
317
-
318
- * _project1.lock_ - contains _junit_ and _mina_ jars.
319
- * _project2.lock_ - contains _junit_ and _pom.xml_ jars.
320
-
321
- ## Bundler Integration
322
-
323
- Bundler integration is **experimental** right now. [LockJar patches Bundler](https://github.com/mguymon/lock_jar/blob/master/lib/lock_jar/bundler.rb)
324
- to allow creation of a _Jarfile.lock_ when Bundler calls `install` and `update`. The dependencies from the _Jarfile.lock_ are automatically loaded when
325
- Bundler calls `setup` and `require`. To enable this support, add this require to your _Gemfile_
326
-
327
- require 'lock_jar/bundler'
328
-
329
- You can optionally create a _Jarfile_ that will automatically be included when you `bundle install` or `bundle update`. Otherwise
330
- Gems with a Jarfile will be merge to generate a _Jarfile.lock_. The Jarfile.lock will be loaded when Bundler calls `setup` or `require`.
331
-
332
- ### Bundler to LockJar groups
333
-
334
- LockJar will merge the dependencies from the `default` and `runtime` group of a Gem's _Jarfile_. These will be placed in the
335
- lockfile under Gem's corresponding Bundler group. For example, the following Gemfile:
336
-
337
- group :development do
338
- gem 'solr_sail', '~>0.1.0'
339
- end
340
-
341
- Would produce the follow _Jarfile.lock_ excerpt:
342
-
343
- ---
344
- version: 0.7.0
345
- merged:
346
- - gem:solr_sail:gems/solr_sail-0.1.0-java/Jarfile
347
- groups:
348
- default:
349
- dependencies: []
350
- artifacts: []
351
- development:
352
- dependencies:
353
- - ch.qos.logback:logback-classic:jar:1.0.6
354
- - ch.qos.logback:logback-core:jar:1.0.6
355
- - com.google.guava:guava:jar:r05
356
-
357
- Since `solr_sail` is defined in the _Gemfile's_ `development` group, the corresponding _Jarfile.lock_ dependencies are also under the `development` group.
358
-
359
- ## License
360
-
361
- Licensed to the Apache Software Foundation (ASF) under one or more
362
- contributor license agreements. See the NOTICE file distributed with this
363
- work for additional information regarding copyright ownership. The ASF
364
- licenses this file to you under the Apache License, Version 2.0 (the
365
- "License"); you may not use this file except in compliance with the License.
366
- You may obtain a copy of the License at
367
-
368
- http://www.apache.org/licenses/LICENSE-2.0
369
-
370
- Unless required by applicable law or agreed to in writing, software
371
- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
372
- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
373
- License for the specific language governing permissions and limitations under
374
- the License.
375
-
1
+ # LockJar
2
+
3
+ [![Build Status](https://secure.travis-ci.org/mguymon/lock_jar.png?branch=master)](http://travis-ci.org/mguymon/lock_jar)
4
+
5
+ LockJar manages Java Jars for Ruby. Powered by [Naether](https://github.com/mguymon/naether) to
6
+ create a frankenstein of Bundler and Maven. A Jarfile ([example](https://github.com/mguymon/lock_jar/blob/master/spec/Jarfile)) is used to generate a Jarfile.lock that contains all the resolved jar dependencies. The Jarfile.lock can be used to populate the classpath.
7
+
8
+ LockJar can:
9
+ * Be used directly in MRI 1.9.3, 2.0, 2.1 and JRuby 1.6, 1.7
10
+ * From the [command line](https://github.com/mguymon/lock_jar/blob/master/README.md#command-line)
11
+ * [Triggered from a Gem install](https://github.com/mguymon/lock_jar/blob/master/README.md#gem-integration)
12
+ * [Integrated into Buildr](https://github.com/mguymon/lock_jar/blob/master/README.md#buildr-integration)
13
+ * Experimental [integration with Bundler](https://github.com/mguymon/lock_jar/blob/master/README.md#bundler-integration)
14
+
15
+ https://github.com/mguymon/lock_jar
16
+
17
+ [RDoc](http://rubydoc.info/gems/lock_jar/frames)
18
+
19
+ ## Install
20
+
21
+ gem install lock_jar
22
+
23
+ ## Ruby Usage
24
+
25
+ JRuby is natively supported. Ruby 1.9.3 and 2.1 uses [Rjb](http://rjb.rubyforge.org/) to proxy over JNI.
26
+
27
+ ### Jarfile
28
+
29
+ A Jarfile is a simple file using a Ruby DSL for defining a project's dependencies using the following
30
+ methods:
31
+
32
+ * **local_repo( path )**: Set the local Maven repository, this were dependencies are downloaded to.
33
+ * **remote_repo( url )**: Add additional url of remote Maven repository.
34
+ * **group( groups )**: Set the group for nested jar or pom. A single or Array of groups can be set.
35
+ * **jar( notations, opts = {} )**: Add Jar dependency in artifact notation, artifact:group:version as the bare minimum. A single or Array of notations can be passed. Default group is _default_, can be specified by setting _opts = { :group => ['group_name'] }_
36
+ * **local( path )**: Add a local path to a Jar
37
+ * **pom( pom_path, opts = {} )**: Add a local Maven pom, default is to load dependencies for `runtime` and `compile` scopes. To select the scopes to be loaded from the pom, set the _opts = { :scopes => ['test'] }_
38
+
39
+ #### Example Jarfile
40
+
41
+ repository 'http://repository.jboss.org/nexus/content/groups/public-jboss'
42
+
43
+ // Default group is default
44
+ jar "org.apache.mina:mina-core:2.0.4"
45
+ local 'spec/fixtures/naether-0.13.0.jar'
46
+
47
+ group 'runtime' do
48
+ jar 'org.apache.tomcat:servlet-api:jar:6.0.35'
49
+ end
50
+
51
+ group 'test' do
52
+ jar 'junit:junit:jar:4.10', :group => 'test'
53
+ end
54
+
55
+ ### Resolving dependencies
56
+
57
+ **LockJar.lock( *args )**: Using a Jarfile, creates a lock file. Depending on the type of arg, a different configuration is set.
58
+ * _[String]_ will set the Jarfile path, e.g. `'/somewhere/Jarfile.different'`. Default jarfile is `'Jarfile'`
59
+ * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
60
+ * **:download** _[Boolean]_ if true, will download jars to local repo. Defaults to true.
61
+ * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
62
+ * **:lockfile** _[String]_ sets the Jarfile.lock path. Default lockfile is `'Jarfile.lock'`.
63
+
64
+ When the Jarfile is locked, the transitive dependencies are resolved and saved to the Jarfile.lock file.
65
+
66
+ Example of locking a Jarfile to a Jarfile.lock
67
+
68
+ LockJar.lock
69
+
70
+
71
+ ### Jarfile.lock
72
+
73
+ The _Jarfile.lock_ generated is a YAML file containing information on how to handle the classpath for grouped dependencies and their nested transitive dependencies.
74
+
75
+ #### The Jarfile.lock
76
+
77
+ ---
78
+ version: 0.7.0
79
+ groups:
80
+ default:
81
+ dependencies:
82
+ - ch.qos.logback:logback-classic:jar:0.9.24
83
+ - ch.qos.logback:logback-core:jar:0.9.24
84
+ - com.metapossum:metapossum-scanner:jar:1.0
85
+ - com.slackworks:modelcitizen:jar:0.2.2
86
+ - commons-beanutils:commons-beanutils:jar:1.8.3
87
+ - commons-io:commons-io:jar:1.4
88
+ - commons-lang:commons-lang:jar:2.6
89
+ - commons-logging:commons-logging:jar:1.1.1
90
+ - junit:junit:jar:4.7
91
+ - org.apache.mina:mina-core:jar:2.0.4
92
+ - org.slf4j:slf4j-api:jar:1.6.1
93
+ artifacts:
94
+ - jar:org.apache.mina:mina-core:jar:2.0.4:
95
+ transitive:
96
+ org.slf4j:slf4j-api:jar:1.6.1: {}
97
+ - pom:spec/pom.xml:
98
+ scopes:
99
+ - runtime
100
+ - compile
101
+ transitive:
102
+ com.metapossum:metapossum-scanner:jar:1.0:
103
+ junit:junit:jar:4.7: {}
104
+ commons-io:commons-io:jar:1.4: {}
105
+ commons-beanutils:commons-beanutils:jar:1.8.3:
106
+ commons-logging:commons-logging:jar:1.1.1: {}
107
+ ch.qos.logback:logback-classic:jar:0.9.24:
108
+ ch.qos.logback:logback-core:jar:0.9.24: {}
109
+ commons-lang:commons-lang:jar:2.6: {}
110
+ development:
111
+ dependencies:
112
+ - com.typesafe:config:jar:0.5.0
113
+ artifacts:
114
+ - jar:com.typesafe:config:jar:0.5.0:
115
+ transitive: {}
116
+ test:
117
+ dependencies:
118
+ - junit:junit:jar:4.10
119
+ - org.hamcrest:hamcrest-core:jar:1.1
120
+ artifacts:
121
+ - jar:junit:junit:jar:4.10:
122
+ transitive:
123
+ org.hamcrest:hamcrest-core:jar:1.1: {}
124
+ ...
125
+
126
+
127
+
128
+ ### Accessing Jars
129
+ **LockJar.install(*args)**: Download Jars in the Jarfile.lock
130
+ * _[String]_ will set the Jarfile.lock path, e.g. `'Better.lock'`. Default lock file is `'Jarfile.lock'`.
131
+ * _[Array<String>]_ will set the groups, e.g. `['compile','test']`. Defaults group is _default_.
132
+ * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
133
+ * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
134
+
135
+ **LockJar.list(*args)**: Lists all dependencies as notations for groups from the Jarfile.lock. Depending on the type of arg, a different configuration is set.
136
+ * _[String]_ will set the Jarfile.lock path, e.g. `'Better.lock'`. Default lock file is `'Jarfile.lock'`.
137
+ * _[Array<String>]_ will set the groups, e.g. `['default', 'runtime']`. Defaults group is _default_.
138
+ * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
139
+ * **:local_repo** _[String]_ sets the local repo path. Defaults to `ENV['M2_REPO']` or `'~/.m2/repository'`
140
+ * **:local_paths** _[Boolean]_ converts the notations to paths of jars in the local repo
141
+ * **:resolve** _[Boolean]_ to true will make transitive dependences resolve before returning list of jars
142
+
143
+ **LockJar.load(*args)**: Loads all dependencies to the classpath for groups from the Jarfile.lock. Default group is _default_. Default lock file is _Jarfile.lock_.
144
+ * _[String]_ will set the Jarfile.lock, e.g. `'Better.lock'`
145
+ * _[Array<String>]_ will set the groups, e.g. `['default', 'runtime']`
146
+ * _[Hash]_ will set the options, e.g. `{ :local_repo => 'path' }`
147
+ * **:local_repo** _[String]_ sets the local repo path
148
+ * **:resolve** _[Boolean]_ to true will make transitive dependences resolve before loading to classpath
149
+
150
+ Once a _Jarfile.lock_ is generated, you can list all resolved jars by
151
+
152
+ jars = LockJar.list
153
+
154
+ or directly load all Jars into the classpath
155
+
156
+ jars = LockJar.load
157
+
158
+ Do not forget, if you change your _Jarfile_, you have to re-generate the _Jarfile.lock_.
159
+
160
+ See also [loading Jars into a custom ClassLoader](https://github.com/mguymon/lock_jar/wiki/ClassLoader).
161
+
162
+ ### Shortcuts
163
+
164
+ #### Skipping the Jarfile
165
+
166
+ You can skip the _Jarfile_ and _Jarfile.lock_ to directly play with dependencies by passing a block to _LockJar.lock_, _LockJar.list_, and _LockJar.load_
167
+
168
+ #### Lock without a Jarfile
169
+
170
+ LockJar.lock do
171
+ jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
172
+ end
173
+
174
+ #### List without a Jarfile.lock
175
+
176
+ LockJar.list do
177
+ jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
178
+ end
179
+
180
+ #### Load without a Jarfile.lock
181
+
182
+ LockJar.load do
183
+ jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
184
+ end
185
+
186
+ Since you skipped the locking part, mostly likely you will need to resolve the dependences in the block, just pass the _:resolve => true_ option to enable dependency resolution (also works for _LockJar.list_).
187
+
188
+ LockJar.load( :resolve => true ) do
189
+ jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
190
+ end
191
+
192
+ ## Command line
193
+
194
+ There is a simple command line helper. You can lock a _Jarfile_ with the following command
195
+
196
+ lockjar lock
197
+
198
+ List jars in a _Jarfile.lock_ with
199
+
200
+ lockjar list
201
+
202
+ Download all jars in a _Jarfile.lock_ with
203
+
204
+ lockjar install
205
+
206
+ _lockjar_ _--help_ will give you list of all commands and their options.
207
+
208
+ ## Gem Integration
209
+
210
+ ### Installing Jars with a Gem
211
+
212
+ LockJar can be triggered when a Gem is installed by using a [Gem extension](http://docs.rubygems.org/read/chapter/20#extensions)
213
+ of type _Rakefile_. The cavaet is the task to install the jars must be the default for the Rakefile.
214
+
215
+ A Gem spec with _Rakefile_ extension:
216
+
217
+ Gem::Specification.new do |s|
218
+ s.extensions = ["Rakefile"]
219
+ end
220
+
221
+ Rakefile with default to install Jars using LockJar:
222
+
223
+ task :default => :prepare
224
+
225
+ task :prepare do
226
+ require 'lock_jar'
227
+
228
+ # get jarfile relative the gem dir
229
+ lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
230
+
231
+ LockJar.install( lockfile )
232
+ end
233
+
234
+ #### Work around for Rakefile default
235
+
236
+ The downside of using the Gem extension Rakefile is it requires the default to
237
+ point at the task to download the jars (from the example Rakefile,
238
+ `task :default => :prepare`). To get around this, I used a Rakefile called
239
+ _PostInstallRakefile_ to handle the `task :prepare`. When packaging the gem, _PostInstallRakefile_ is
240
+ renamed to `Rakefile`.
241
+
242
+ ### Manually installing Jars
243
+
244
+ Instead of rely in a Rakefile to install Jars when the Gem is installed, Jars can be manually installed. The following
245
+ Ruby needs to be called before calling `LockJar.load`. Only Jars that are missing are downloaded.
246
+
247
+ #get jarfile relative the gem dir
248
+ lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
249
+
250
+ # Download any missing Jars
251
+ LockJar.install( lockfile )
252
+
253
+ ### Loading
254
+
255
+ With the Jars installed, loading the classpath for the Gem is simple.
256
+ As part of the load process for the Gem (an entry file that is required, etc) use the following:
257
+
258
+ #get jarfile relative the gem dir
259
+ lockfile = File.expand_path( "../Jarfile.lock", __FILE__ )
260
+
261
+ # Loads the ClassPath with Jars from the lockfile
262
+ LockJar.load( lockfile )
263
+
264
+ See also [loading Jars into a custom ClassLoader](https://github.com/mguymon/lock_jar/wiki/ClassLoader).
265
+
266
+ ## Buildr Integration
267
+
268
+ LockJar integrates with [Buildr](http://buildr.apache.org/) using an [Addon](https://github.com/mguymon/lock_jar/blob/master/lib/lock_jar/buildr.rb). This allows the Jarfile to be defined directly into a _buildfile_. A global LockJar definition can be set and is inherited to all projects. Each project may have its own LockJar definition. A lock file is generated per project based on the project name.
269
+
270
+ A new Buildr task is added to generate the lockfile for all projects
271
+
272
+ buildr lock_jar:lock
273
+
274
+ and a task per project to generate the lockfile for a single project
275
+
276
+ buildr <app>:<project>:lock_jar:lock
277
+
278
+ In a project, you can access an Array of notations using the **lock_jars** method, accepts same parameters as [LockJar.list](https://github.com/mguymon/lock_jar#accessing-jars)
279
+
280
+ lock_jars()
281
+
282
+
283
+ The _default_ group dependencies are automatically added to the classpath for compiling. The _test_ group dependencies are automatically added to the classpath for tests. Do not forget, if you change the LockJar definitions, you have to rerun the **lock_jar:lock** task.
284
+
285
+
286
+ ### Example
287
+
288
+ Sample buildfile with LockJar
289
+
290
+ require 'lock_jar/buildr'
291
+
292
+ # app definition, inherited into all projects
293
+ lock_jar do
294
+
295
+ group 'test' do
296
+ jar 'junit:junit:jar:4.10'
297
+ end
298
+ end
299
+
300
+ define 'app' do
301
+
302
+ def 'project1' do
303
+ lock_jar do
304
+ jar "org.apache.mina:mina-core:2.0.4"
305
+ end
306
+ end
307
+
308
+ def 'project2' do
309
+ lock_jar do
310
+ pom 'pom.xml'
311
+ end
312
+ end
313
+
314
+ end
315
+
316
+ Generated the following lock files using **lock_jar:lock**
317
+
318
+ * _project1.lock_ - contains _junit_ and _mina_ jars.
319
+ * _project2.lock_ - contains _junit_ and _pom.xml_ jars.
320
+
321
+ ## Bundler Integration
322
+
323
+ Bundler integration is **experimental** right now. [LockJar patches Bundler](https://github.com/mguymon/lock_jar/blob/master/lib/lock_jar/bundler.rb)
324
+ to allow creation of a _Jarfile.lock_ when Bundler calls `install` and `update`. The dependencies from the _Jarfile.lock_ are automatically loaded when
325
+ Bundler calls `setup` and `require`. To enable this support, add this require to your _Gemfile_
326
+
327
+ require 'lock_jar/bundler'
328
+
329
+ You can optionally create a _Jarfile_ that will automatically be included when you `bundle install` or `bundle update`. Otherwise
330
+ Gems with a Jarfile will be merge to generate a _Jarfile.lock_. The Jarfile.lock will be loaded when Bundler calls `setup` or `require`.
331
+
332
+ ### Bundler to LockJar groups
333
+
334
+ LockJar will merge the dependencies from the `default` and `runtime` group of a Gem's _Jarfile_. These will be placed in the
335
+ lockfile under Gem's corresponding Bundler group. For example, the following Gemfile:
336
+
337
+ group :development do
338
+ gem 'solr_sail', '~>0.1.0'
339
+ end
340
+
341
+ Would produce the follow _Jarfile.lock_ excerpt:
342
+
343
+ ---
344
+ version: 0.7.0
345
+ merged:
346
+ - gem:solr_sail:gems/solr_sail-0.1.0-java/Jarfile
347
+ groups:
348
+ default:
349
+ dependencies: []
350
+ artifacts: []
351
+ development:
352
+ dependencies:
353
+ - ch.qos.logback:logback-classic:jar:1.0.6
354
+ - ch.qos.logback:logback-core:jar:1.0.6
355
+ - com.google.guava:guava:jar:r05
356
+
357
+ Since `solr_sail` is defined in the _Gemfile's_ `development` group, the corresponding _Jarfile.lock_ dependencies are also under the `development` group.
358
+
359
+ ## License
360
+
361
+ Licensed to the Apache Software Foundation (ASF) under one or more
362
+ contributor license agreements. See the NOTICE file distributed with this
363
+ work for additional information regarding copyright ownership. The ASF
364
+ licenses this file to you under the Apache License, Version 2.0 (the
365
+ "License"); you may not use this file except in compliance with the License.
366
+ You may obtain a copy of the License at
367
+
368
+ http://www.apache.org/licenses/LICENSE-2.0
369
+
370
+ Unless required by applicable law or agreed to in writing, software
371
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
372
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
373
+ License for the specific language governing permissions and limitations under
374
+ the License.
375
+