-
Notifications
You must be signed in to change notification settings - Fork 4.5k
/
DependencyHandler.java
545 lines (516 loc) · 19.4 KB
/
DependencyHandler.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
/*
* Copyright 2009 the original author or authors.
*
* 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
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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.
*/
package org.gradle.api.artifacts.dsl;
import groovy.lang.Closure;
import org.gradle.api.Action;
import org.gradle.api.Incubating;
import org.gradle.api.artifacts.Dependency;
import org.gradle.api.artifacts.query.ArtifactResolutionQuery;
import org.gradle.api.artifacts.transform.TransformAction;
import org.gradle.api.artifacts.transform.TransformParameters;
import org.gradle.api.artifacts.transform.TransformSpec;
import org.gradle.api.artifacts.transform.VariantTransform;
import org.gradle.api.artifacts.type.ArtifactTypeContainer;
import org.gradle.api.attributes.AttributesSchema;
import org.gradle.api.plugins.ExtensionAware;
import javax.annotation.Nullable;
import java.util.Map;
/**
* <p>A {@code DependencyHandler} is used to declare dependencies. Dependencies are grouped into
* configurations (see {@link org.gradle.api.artifacts.Configuration}).</p>
*
* <p>To declare a specific dependency for a configuration you can use the following syntax:</p>
*
* <pre>
* dependencies {
* <i>configurationName</i> <i>dependencyNotation</i>
* }
* </pre>
*
* <p>Example shows a basic way of declaring dependencies.
* <pre class='autoTested'>
* apply plugin: 'java'
* //so that we can use 'implementation', 'testImplementation' for dependencies
*
* dependencies {
* //for dependencies found in artifact repositories you can use
* //the group:name:version notation
* implementation 'commons-lang:commons-lang:2.6'
* testImplementation 'org.mockito:mockito:1.9.0-rc1'
*
* //map-style notation:
* implementation group: 'com.google.code.guice', name: 'guice', version: '1.0'
*
* //declaring arbitrary files as dependencies
* implementation files('hibernate.jar', 'libs/spring.jar')
*
* //putting all jars from 'libs' onto compile classpath
* implementation fileTree('libs')
* }
* </pre>
*
* <h2>Advanced dependency configuration</h2>
* <p>To do some advanced configuration on a dependency when it is declared, you can additionally pass a configuration closure:</p>
*
* <pre>
* dependencies {
* <i>configurationName</i>(<i>dependencyNotation</i>){
* <i>configStatement1</i>
* <i>configStatement2</i>
* }
* }
* </pre>
*
* Examples of advanced dependency declaration including:
* <ul>
* <li>Forcing certain dependency version in case of the conflict.</li>
* <li>Excluding certain dependencies by name, group or both.
* More details about per-dependency exclusions can be found in
* docs for {@link org.gradle.api.artifacts.ModuleDependency#exclude(java.util.Map)}.</li>
* <li>Avoiding transitive dependencies for certain dependency.</li>
* </ul>
*
* <pre class='autoTested'>
* apply plugin: 'java' //so that I can declare 'implementation' dependencies
*
* dependencies {
* implementation('org.hibernate:hibernate:3.1') {
* //in case of versions conflict '3.1' version of hibernate wins:
* force = true
*
* //excluding a particular transitive dependency:
* exclude module: 'cglib' //by artifact name
* exclude group: 'org.jmock' //by group
* exclude group: 'org.unwanted', module: 'iAmBuggy' //by both name and group
*
* //disabling all transitive dependencies of this dependency
* transitive = false
* }
* }
* </pre>
*
* More examples of advanced configuration, useful when dependency module has multiple artifacts:
* <ul>
* <li>Declaring dependency to a specific configuration of the module.</li>
* <li>Explicit specification of the artifact. See also {@link org.gradle.api.artifacts.ModuleDependency#artifact(groovy.lang.Closure)}.</li>
* </ul>
*
* <pre class='autoTested'>
* apply plugin: 'java' //so that I can declare 'implementation' dependencies
*
* dependencies {
* //configuring dependency to specific configuration of the module
* implementation configuration: 'someConf', group: 'org.someOrg', name: 'someModule', version: '1.0'
*
* //configuring dependency on 'someLib' module
* implementation(group: 'org.myorg', name: 'someLib', version:'1.0') {
* //explicitly adding the dependency artifact:
* artifact {
* //useful when some artifact properties unconventional
* name = 'someArtifact' //artifact name different than module name
* extension = 'someExt'
* type = 'someType'
* classifier = 'someClassifier'
* }
* }
* }
* </pre>
*
* <h2>Dependency notations</h2>
*
* <p>There are several supported dependency notations. These are described below. For each dependency declared this
* way, a {@link Dependency} object is created. You can use this object to query or further configure the
* dependency.</p>
*
* <p>You can also always add instances of
* {@link org.gradle.api.artifacts.Dependency} directly:</p>
*
* <code><i>configurationName</i> <instance></code>
*
* <h3>External dependencies</h3>
*
* <p>There are two notations supported for declaring a dependency on an external module.
* One is a string notation formatted this way:</p>
*
* <code><i>configurationName</i> "<i>group</i>:<i>name</i>:<i>version</i>:<i>classifier</i>@<i>extension</i>"</code>
*
* <p>The other is a map notation:</p>
*
* <code><i>configurationName</i> group: <i>group</i>, name: <i>name</i>, version: <i>version</i>, classifier:
* <i>classifier</i>, ext: <i>extension</i></code>
*
* <p>In both notations, all properties, except name, are optional.</p>
*
* <p>External dependencies are represented by a {@link
* org.gradle.api.artifacts.ExternalModuleDependency}.</p>
*
* <pre class='autoTested'>
* apply plugin: 'java'
* //so that we can use 'implementation', 'testImplementation' for dependencies
*
* dependencies {
* //for dependencies found in artifact repositories you can use
* //the string notation, e.g. group:name:version
* implementation 'commons-lang:commons-lang:2.6'
* testImplementation 'org.mockito:mockito:1.9.0-rc1'
*
* //map notation:
* implementation group: 'com.google.code.guice', name: 'guice', version: '1.0'
* }
* </pre>
*
* <h3>Project dependencies</h3>
*
* <p>To add a project dependency, you use the following notation:
* <p><code><i>configurationName</i> project(':someProject')</code>
*
* <p>The notation <code>project(':projectA')</code> is similar to the syntax you use
* when configuring a projectA in a multi-module gradle project.
*
* <p>By default, when you declare dependency to projectA, you actually declare dependency to the 'default' configuration of the projectA.
* If you need to depend on a specific configuration of projectA, use map notation for projects:
* <p><code><i>configurationName</i> project(path: ':projectA', configuration: 'someOtherConfiguration')</code>
*
* <p>Project dependencies are represented using a {@link org.gradle.api.artifacts.ProjectDependency}.
*
* <h3>File dependencies</h3>
*
* <p>You can also add a dependency using a {@link org.gradle.api.file.FileCollection}:</p>
* <code><i>configurationName</i> files('a file')</code>
*
* <pre class='autoTested'>
* apply plugin: 'java'
* //so that we can use 'implementation', 'testImplementation' for dependencies
*
* dependencies {
* //declaring arbitrary files as dependencies
* implementation files('hibernate.jar', 'libs/spring.jar')
*
* //putting all jars from 'libs' onto compile classpath
* implementation fileTree('libs')
* }
* </pre>
*
* <p>File dependencies are represented using a {@link org.gradle.api.artifacts.SelfResolvingDependency}.</p>
*
* <h3>Dependencies to other configurations</h3>
*
* <p>You can add a dependency using a {@link org.gradle.api.artifacts.Configuration}.</p>
*
* <p>When the configuration is from the same project as the target configuration, the target configuration is changed
* to extend from the provided configuration.</p>
*
* <p>When the configuration is from a different project, a project dependency is added.</p>
*
* <h3>Gradle distribution specific dependencies</h3>
*
* <p>It is possible to depend on certain Gradle APIs or libraries that Gradle ships with.
* It is particularly useful for Gradle plugin development. Example:</p>
*
* <pre class='autoTested'>
* //Our Gradle plugin is written in groovy
* apply plugin: 'groovy'
* //now we can use the 'implementation' configuration for declaring dependencies
*
* dependencies {
* //we will use the Groovy version that ships with Gradle:
* implementation localGroovy()
*
* //our plugin requires Gradle API interfaces and classes to compile:
* implementation gradleApi()
*
* //we will use the Gradle test-kit to test build logic:
* testImplementation gradleTestKit()
* }
* </pre>
*
* <h3>Client module dependencies</h3>
*
* <p>To add a client module to a configuration you can use the notation:</p>
*
* <pre>
* <i>configurationName</i> module(<i>moduleNotation</i>) {
* <i>module dependencies</i>
* }
* </pre>
*
* The module notation is the same as the dependency notations described above, except that the classifier property is
* not available. Client modules are represented using a {@link org.gradle.api.artifacts.ClientModule}.
*/
public interface DependencyHandler extends ExtensionAware {
/**
* Adds a dependency to the given configuration.
*
* @param configurationName The name of the configuration.
* @param dependencyNotation
*
* The dependency notation, in one of the notations described above.
* @return The dependency.
*/
@Nullable
Dependency add(String configurationName, Object dependencyNotation);
/**
* Adds a dependency to the given configuration, and configures the dependency using the given closure.
*
* @param configurationName The name of the configuration.
* @param dependencyNotation The dependency notation, in one of the notations described above.
* @param configureClosure The closure to use to configure the dependency.
* @return The dependency.
*/
Dependency add(String configurationName, Object dependencyNotation, Closure configureClosure);
/**
* Creates a dependency without adding it to a configuration.
*
* @param dependencyNotation The dependency notation, in one of the notations described above.
* @return The dependency.
*/
Dependency create(Object dependencyNotation);
/**
* Creates a dependency without adding it to a configuration, and configures the dependency using
* the given closure.
*
* @param dependencyNotation The dependency notation, in one of the notations described above.
* @param configureClosure The closure to use to configure the dependency.
* @return The dependency.
*/
Dependency create(Object dependencyNotation, Closure configureClosure);
/**
* Creates a dependency on a client module.
*
* @param notation The module notation, in one of the notations described above.
* @return The dependency.
*/
Dependency module(Object notation);
/**
* Creates a dependency on a client module. The dependency is configured using the given closure before it is
* returned.
*
* @param notation The module notation, in one of the notations described above.
* @param configureClosure The closure to use to configure the dependency.
* @return The dependency.
*/
Dependency module(Object notation, Closure configureClosure);
/**
* Creates a dependency on a project.
*
* @param notation The project notation, in one of the notations described above.
* @return The dependency.
*/
Dependency project(Map<String, ?> notation);
/**
* Creates a dependency on the API of the current version of Gradle.
*
* @return The dependency.
*/
Dependency gradleApi();
/**
* Creates a dependency on the <a href="https://docs.gradle.org/current/userguide/test_kit.html" target="_top">Gradle test-kit</a> API.
*
* @return The dependency.
* @since 2.6
*/
Dependency gradleTestKit();
/**
* Creates a dependency on the Groovy that is distributed with the current version of Gradle.
*
* @return The dependency.
*/
Dependency localGroovy();
/**
* Returns the dependency constraint handler for this project.
*
* @return the dependency constraint handler for this project
* @since 4.5
*/
@Incubating
DependencyConstraintHandler getConstraints();
/**
* Configures dependency constraint for this project.
*
* <p>This method executes the given action against the {@link org.gradle.api.artifacts.dsl.DependencyConstraintHandler} for this project.</p>
*
* @param configureAction the action to use to configure module metadata
* @since 4.5
*/
@Incubating
void constraints(Action<? super DependencyConstraintHandler> configureAction);
/**
* Returns the component metadata handler for this project. The returned handler can be used for adding rules
* that modify the metadata of depended-on software components.
*
* @return the component metadata handler for this project
* @since 1.8
*/
ComponentMetadataHandler getComponents();
/**
* Configures component metadata for this project.
*
* <p>This method executes the given action against the {@link org.gradle.api.artifacts.dsl.ComponentMetadataHandler} for this project.</p>
*
* @param configureAction the action to use to configure module metadata
* @since 1.8
*/
void components(Action<? super ComponentMetadataHandler> configureAction);
/**
* Returns the component module metadata handler for this project. The returned handler can be used for adding rules
* that modify the metadata of depended-on software components.
*
* @return the component module metadata handler for this project
* @since 2.2
*/
ComponentModuleMetadataHandler getModules();
/**
* Configures module metadata for this project.
*
* <p>This method executes the given action against the {@link org.gradle.api.artifacts.dsl.ComponentModuleMetadataHandler} for this project.
*
* @param configureAction the action to use to configure module metadata
* @since 2.2
*/
void modules(Action<? super ComponentModuleMetadataHandler> configureAction);
/**
* Creates an artifact resolution query.
*
* @since 2.0
*/
ArtifactResolutionQuery createArtifactResolutionQuery();
/**
* Configures the attributes schema. The action is passed a {@link AttributesSchema} instance.
* @param configureAction the configure action
* @return the configured schema
*
* @since 3.4
*/
AttributesSchema attributesSchema(Action<? super AttributesSchema> configureAction);
/**
* Returns the attributes schema for this handler.
* @return the attributes schema
*
* @since 3.4
*/
AttributesSchema getAttributesSchema();
/**
* Returns the artifact type definitions for this handler.
* @since 4.0
*/
@Incubating
ArtifactTypeContainer getArtifactTypes();
/**
* Configures the artifact type definitions for this handler.
* @since 4.0
*/
@Incubating
void artifactTypes(Action<? super ArtifactTypeContainer> configureAction);
/**
* Registers an artifact transform.
*
* @deprecated use {@link #registerTransform(Class, Action)} instead.
* @see org.gradle.api.artifacts.transform.ArtifactTransform
* @since 3.5
*/
@Deprecated
void registerTransform(Action<? super VariantTransform> registrationAction);
/**
* Registers an artifact transform.
*
* <p>
* The registration action needs to specify the {@code from} and {@code to} attributes.
* It may also provide parameters for the transform action by using {@link TransformSpec#parameters(Action)}.
* </p>
*
* <p>Example: When you have a transform action like this:</p>
*
* <pre class='autoTested'>
* abstract class MyTransform implements TransformAction<Parameters> {
* interface Parameters extends TransformParameters {
* {@literal @}Input
* Property<String> getStringParameter();
* {@literal @}InputFiles
* ConfigurableFileCollection getInputFiles();
* }
*
* void transform(TransformOutputs outputs) {
* // ...
* }
* }
*
* // Then you can register the action like this:
*
* def artifactType = Attribute.of('artifactType', String)
*
* dependencies.registerTransform(MyTransform) {
* from.attribute(artifactType, "jar")
* to.attribute(artifactType, "java-classes-directory")
*
* parameters {
* stringParameter.set("Some string")
* inputFiles.from("my-input-file")
* }
* }
* </pre>
*
* @see TransformAction
* @since 5.3
*/
@Incubating
<T extends TransformParameters> void registerTransform(Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction);
/**
* Declares a dependency on a platform. If the target coordinates represent multiple
* potential components, the platform component will be selected, instead of the library.
*
* @param notation the coordinates of the platform
*
* @since 5.0
*/
@Incubating
Dependency platform(Object notation);
/**
* Declares a dependency on a platform. If the target coordinates represent multiple
* potential components, the platform component will be selected, instead of the library.
*
* @param notation the coordinates of the platform
* @param configureAction the dependency configuration block
*
* @since 5.0
*/
@Incubating
Dependency platform(Object notation, Action<? super Dependency> configureAction);
/**
* Declares a dependency on an enforced platform. If the target coordinates represent multiple
* potential components, the platform component will be selected, instead of the library.
* An enforced platform is a platform for which the direct dependencies are forced, meaning
* that they would override any other version found in the graph.
*
* @param notation the coordinates of the platform
*
* @since 5.0
*/
@Incubating
Dependency enforcedPlatform(Object notation);
/**
* Declares a dependency on an enforced platform. If the target coordinates represent multiple
* potential components, the platform component will be selected, instead of the library.
* An enforced platform is a platform for which the direct dependencies are forced, meaning
* that they would override any other version found in the graph.
*
* @param notation the coordinates of the platform
* @param configureAction the dependency configuration block
*
* @since 5.0
*/
@Incubating
Dependency enforcedPlatform(Object notation, Action<? super Dependency> configureAction);
}