-
Notifications
You must be signed in to change notification settings - Fork 4.6k
/
Settings.java
422 lines (386 loc) · 14.7 KB
/
Settings.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
/*
* 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.initialization;
import org.gradle.StartParameter;
import org.gradle.api.Action;
import org.gradle.api.Incubating;
import org.gradle.api.UnknownProjectException;
import org.gradle.api.cache.CacheConfigurations;
import org.gradle.api.file.BuildLayout;
import org.gradle.api.initialization.dsl.ScriptHandler;
import org.gradle.api.initialization.resolve.DependencyResolutionManagement;
import org.gradle.api.invocation.Gradle;
import org.gradle.api.plugins.ExtensionAware;
import org.gradle.api.plugins.PluginAware;
import org.gradle.api.provider.Provider;
import org.gradle.api.provider.ProviderFactory;
import org.gradle.api.toolchain.management.ToolchainManagement;
import org.gradle.caching.configuration.BuildCacheConfiguration;
import org.gradle.declarative.dsl.model.annotations.Adding;
import org.gradle.declarative.dsl.model.annotations.Configuring;
import org.gradle.declarative.dsl.model.annotations.Restricted;
import org.gradle.internal.HasInternalProtocol;
import org.gradle.plugin.management.PluginManagementSpec;
import org.gradle.vcs.SourceControl;
import javax.annotation.Nullable;
import java.io.File;
import java.util.Arrays;
/**
* <p>Declares the configuration required to instantiate and configure the hierarchy of {@link
* org.gradle.api.Project} instances which are to participate in a build.</p>
*
* <p>There is a one-to-one correspondence between a <code>Settings</code> instance and a <code>{@value
* #DEFAULT_SETTINGS_FILE}</code> settings file. Before Gradle assembles the projects for a build, it creates a
* <code>Settings</code> instance and executes the settings file against it.</p>
*
* <h3>Assembling a Multi-Project Build</h3>
*
* <p>One of the purposes of the <code>Settings</code> object is to allow you to declare the projects which are to be
* included in the build. You add projects to the build using the {@link #include(String...)} method. There is always a
* root project included in a build. It is added automatically when the <code>Settings</code> object is created. The
* root project's name defaults to the name of the directory containing the settings file. The root project's project
* directory defaults to the directory containing the settings file.</p>
*
* <p>When a project is included in the build, a {@link ProjectDescriptor} is created. You can use this descriptor to
* change the default values for several properties of the project.</p>
*
* <h3>Using Settings in a Settings File</h3>
*
* <h4>Dynamic Properties</h4>
*
* <p>In addition to the properties of this interface, the {@code Settings} object makes some additional read-only
* properties available to the settings script. This includes properties from the following sources:</p>
*
* <ul>
*
* <li>Defined in the {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the settings directory of the
* build.</li>
*
* <li>Defined the {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the user's {@code .gradle}
* directory.</li>
*
* <li>Provided on the command-line using the -P option.</li>
*
* </ul>
*/
@HasInternalProtocol
public interface Settings extends PluginAware, ExtensionAware {
/**
* <p>The default name for the settings file.</p>
*/
String DEFAULT_SETTINGS_FILE = "settings.gradle";
/**
* <p>Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to
* add to the build. Note that these path are not file paths, but instead specify the location of the new project in
* the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').</p>
*
* <p>The last element of the supplied path is used as the project name. The supplied path is converted to a project
* directory relative to the root project directory. The project directory can be altered by changing the 'projectDir'
* property after the project has been included (see {@link ProjectDescriptor#setProjectDir(File)})</p>
*
* <p>As an example, the path {@code a:b} adds a project with path {@code :a:b}, name {@code b} and project
* directory {@code $rootDir/a/b}. It also adds the a project with path {@code :a}, name {@code a} and project
* directory {@code $rootDir/a}, if it does not exist already.</p>
*
* <p>Some common examples of using the project path are:</p>
*
* <pre class='autoTestedSettings'>
* // include two projects, 'foo' and 'foo:bar'
* // directories are inferred by replacing ':' with '/'
* include 'foo:bar'
*
* // include one project whose project dir does not match the logical project path
* include 'baz'
* project(':baz').projectDir = file('foo/baz')
*
* // include many projects whose project dirs do not match the logical project paths
* file('subprojects').eachDir { dir ->
* include dir.name
* project(":${dir.name}").projectDir = dir
* }
* </pre>
*
* @param projectPaths the projects to add.
*/
default void include(String... projectPaths) {
include(Arrays.asList(projectPaths));
}
/**
* <p>Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to
* add to the build. Note that these path are not file paths, but instead specify the location of the new project in
* the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').</p>
*
* <p>The last element of the supplied path is used as the project name. The supplied path is converted to a project
* directory relative to the root project directory. The project directory can be altered by changing the 'projectDir'
* property after the project has been included (see {@link ProjectDescriptor#setProjectDir(File)})</p>
*
* <p>As an example, the path {@code a:b} adds a project with path {@code :a:b}, name {@code b} and project
* directory {@code $rootDir/a/b}. It also adds the a project with path {@code :a}, name {@code a} and project
* directory {@code $rootDir/a}, if it does not exist already.</p>
*
* <p>Some common examples of using the project path are:</p>
*
* <pre class='autoTestedSettings'>
* // include two projects, 'foo' and 'foo:bar'
* // directories are inferred by replacing ':' with '/'
* include(['foo:bar'])
*
* // include one project whose project dir does not match the logical project path
* include(['baz'])
* project(':baz').projectDir = file('foo/baz')
*
* // include many projects whose project dirs do not match the logical project paths
* file('subprojects').eachDir { dir ->
* include([dir.name])
* project(":${dir.name}").projectDir = dir
* }
* </pre>
*
* @param projectPaths the projects to add.
*
* @since 7.4
*/
void include(Iterable<String> projectPaths);
/**
* <p>Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to
* add to the build.</p>
*
* <p>The supplied name is converted to a project directory relative to the <em>parent</em> directory of the root
* project directory.</p>
*
* <p>As an example, the name {@code a} add a project with path {@code :a}, name {@code a} and project directory
* {@code $rootDir/../a}.</p>
*
* @param projectNames the projects to add.
*/
default void includeFlat(String... projectNames) {
includeFlat(Arrays.asList(projectNames));
}
/**
* <p>Adds the given projects to the build. Each name in the supplied list is treated as the name of a project to
* add to the build.</p>
*
* <p>The supplied name is converted to a project directory relative to the <em>parent</em> directory of the root
* project directory.</p>
*
* <p>As an example, the name {@code a} add a project with path {@code :a}, name {@code a} and project directory
* {@code $rootDir/../a}.</p>
*
* @param projectNames the projects to add.
*
* @since 7.4
*/
void includeFlat(Iterable<String> projectNames);
/**
* <p>Returns this settings object.</p>
*
* @return This settings object. Never returns null.
*/
Settings getSettings();
/**
* Provides access to important locations for a Gradle build.
*
* @since 8.5
*/
@Incubating
BuildLayout getLayout();
/**
* Returns the build script handler for settings. You can use this handler to query details about the build
* script for settings, and manage the classpath used to compile and execute the settings script.
*
* @return the classpath handler. Never returns null.
*
* @since 4.4
*/
ScriptHandler getBuildscript();
/**
* <p>Returns the settings directory of the build. The settings directory is the directory containing the settings
* file.</p>
*
* @return The settings directory. Never returns null.
*/
File getSettingsDir();
/**
* <p>Returns the root directory of the build. The root directory is the project directory of the root project.</p>
*
* @return The root directory. Never returns null.
*/
File getRootDir();
/**
* <p>Returns the root project of the build.</p>
*
* @return The root project. Never returns null.
*/
@Restricted
ProjectDescriptor getRootProject();
/**
* <p>Returns the project with the given path.</p>
*
* @param path The path.
* @return The project with the given path. Never returns null.
* @throws UnknownProjectException If no project with the given path exists.
*/
ProjectDescriptor project(String path) throws UnknownProjectException;
/**
* <p>Returns the project with the given path.</p>
*
* @param path The path
* @return The project with the given path. Returns null if no such project exists.
*/
@Nullable
ProjectDescriptor findProject(String path);
/**
* <p>Returns the project with the given project directory.</p>
*
* @param projectDir The project directory.
* @return The project with the given project directory. Never returns null.
* @throws UnknownProjectException If no project with the given path exists.
*/
ProjectDescriptor project(File projectDir) throws UnknownProjectException;
/**
* <p>Returns the project with the given project directory.</p>
*
* @param projectDir The project directory.
* @return The project with the given project directory. Returns null if no such project exists.
*/
@Nullable
ProjectDescriptor findProject(File projectDir);
/**
* <p>Returns the set of parameters used to invoke this instance of Gradle.</p>
*
* @return The parameters. Never returns null.
*/
StartParameter getStartParameter();
/**
* Provides access to methods to create various kinds of {@link Provider} instances.
*
* @since 6.8
*/
ProviderFactory getProviders();
/**
* Returns the {@link Gradle} instance for the current build.
*
* @return The Gradle instance. Never returns null.
*/
Gradle getGradle();
/**
* Includes a build at the specified path to the composite build.
* @param rootProject The path to the root project directory for the build.
*
* @since 3.1
*/
void includeBuild(Object rootProject);
/**
* Includes a build at the specified path to the composite build, with the supplied configuration.
* @param rootProject The path to the root project directory for the build.
* @param configuration An action to configure the included build.
*
* @since 3.1
*/
void includeBuild(Object rootProject, Action<ConfigurableIncludedBuild> configuration);
/**
* Returns the build cache configuration.
*
* @since 3.5
*/
BuildCacheConfiguration getBuildCache();
/**
* Configures build cache.
*
* @since 3.5
*/
void buildCache(Action<? super BuildCacheConfiguration> action);
/**
* Configures plugin management.
*
* @since 3.5
*/
@Configuring
void pluginManagement(Action<? super PluginManagementSpec> pluginManagementSpec);
/**
* Returns the plugin management configuration.
*
* @since 3.5
*/
@Restricted
PluginManagementSpec getPluginManagement();
/**
* Configures source control.
*
* @since 4.4
*/
void sourceControl(Action<? super SourceControl> configuration);
/**
* Returns the source control configuration.
*
* @since 4.4
*/
SourceControl getSourceControl();
/**
* Enables a feature preview by name.
*
* @param name the name of the feature to enable
*
* @since 4.6
*/
@Adding
void enableFeaturePreview(String name);
/**
* Configures the cross-project dependency resolution aspects
* @param dependencyResolutionConfiguration the configuration
*
* @since 6.8
*/
@Configuring
void dependencyResolutionManagement(Action<? super DependencyResolutionManagement> dependencyResolutionConfiguration);
/**
* Returns the dependency resolution management handler.
*
* @since 6.8
*/
@Restricted
DependencyResolutionManagement getDependencyResolutionManagement();
/**
* Configures toolchain management.
*
* @since 7.6
*/
@Incubating
void toolchainManagement(Action<? super ToolchainManagement> toolchainManagementConfiguration);
/**
* Returns the toolchain management configuration.
*
* @since 7.6
*/
@Incubating
ToolchainManagement getToolchainManagement();
/**
* Returns the configuration for caches stored in the user home directory.
*
* @since 8.0
*/
@Incubating
CacheConfigurations getCaches();
/**
* Configures the settings for caches stored in the user home directory.
*
* @param cachesConfiguration the configuration
*
* @since 8.0
*/
@Incubating
void caches(Action<? super CacheConfigurations> cachesConfiguration);
}