1 /*
2 * Copyright 2010 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.gradle.api;
18
19 import groovy.lang.Closure;
20 import groovy.lang.DelegatesTo;
21 import groovy.lang.MissingPropertyException;
22 import groovy.transform.stc.ClosureParams;
23 import groovy.transform.stc.SimpleType;
24 import org.gradle.api.artifacts.ConfigurationContainer;
25 import org.gradle.api.artifacts.dsl.ArtifactHandler;
26 import org.gradle.api.artifacts.dsl.DependencyHandler;
27 import org.gradle.api.artifacts.dsl.RepositoryHandler;
28 import org.gradle.api.component.SoftwareComponentContainer;
29 import org.gradle.api.file.ConfigurableFileCollection;
30 import org.gradle.api.file.ConfigurableFileTree;
31 import org.gradle.api.file.CopySpec;
32 import org.gradle.api.file.DeleteSpec;
33 import org.gradle.api.file.FileTree;
34 import org.gradle.api.initialization.dsl.ScriptHandler;
35 import org.gradle.api.internal.ReturnType;
36 import org.gradle.api.invocation.Gradle;
37 import org.gradle.api.logging.Logger;
38 import org.gradle.api.logging.LoggingManager;
39 import org.gradle.api.model.ObjectFactory;
40 import org.gradle.api.plugins.Convention;
41 import org.gradle.api.plugins.ExtensionAware;
42 import org.gradle.api.plugins.ExtensionContainer;
43 import org.gradle.api.plugins.PluginAware;
44 import org.gradle.api.provider.PropertyState;
45 import org.gradle.api.provider.Provider;
46 import org.gradle.api.provider.ProviderFactory;
47 import org.gradle.api.resources.ResourceHandler;
48 import org.gradle.api.tasks.TaskContainer;
49 import org.gradle.api.tasks.WorkResult;
50 import org.gradle.internal.HasInternalProtocol;
51 import org.gradle.normalization.InputNormalizationHandler;
52 import org.gradle.process.ExecResult;
53 import org.gradle.process.ExecSpec;
54 import org.gradle.process.JavaExecSpec;
55
56 import java.io.File;
57 import java.net.URI;
58 import java.util.List;
59 import java.util.Map;
60 import java.util.Set;
61 import java.util.concurrent.Callable;
62
63 /**
64 * <p>This interface is the main API you use to interact with Gradle from your build file. From a <code>Project</code>,
65 * you have programmatic access to all of Gradle's features.</p>
66 *
67 * <h3>Lifecycle</h3>
68 *
69 * <p>There is a one-to-one relationship between a <code>Project</code> and a <code>{@value #DEFAULT_BUILD_FILE}</code>
70 * file. During build initialisation, Gradle assembles a <code>Project</code> object for each project which is to
71 * participate in the build, as follows:</p>
72 *
73 * <ul>
74 *
75 * <li>Create a {@link org.gradle.api.initialization.Settings} instance for the build.</li>
76 *
77 * <li>Evaluate the <code>{@value org.gradle.api.initialization.Settings#DEFAULT_SETTINGS_FILE}</code> script, if
78 * present, against the {@link org.gradle.api.initialization.Settings} object to configure it.</li>
79 *
80 * <li>Use the configured {@link org.gradle.api.initialization.Settings} object to create the hierarchy of
81 * <code>Project</code> instances.</li>
82 *
83 * <li>Finally, evaluate each <code>Project</code> by executing its <code>{@value #DEFAULT_BUILD_FILE}</code> file, if
84 * present, against the project. The projects are evaluated in breadth-wise order, such that a project is evaluated
85 * before its child projects. This order can be overridden by calling <code>{@link #evaluationDependsOnChildren()}</code> or by adding an
86 * explicit evaluation dependency using <code>{@link #evaluationDependsOn(String)}</code>.</li>
87 *
88 * </ul>
89 *
90 * <h3>Tasks</h3>
91 *
92 * <p>A project is essentially a collection of {@link Task} objects. Each task performs some basic piece of work, such
93 * as compiling classes, or running unit tests, or zipping up a WAR file. You add tasks to a project using one of the
94 * {@code create()} methods on {@link TaskContainer}, such as {@link TaskContainer#create(String)}. You can locate existing
95 * tasks using one of the lookup methods on {@link TaskContainer}, such as {@link org.gradle.api.tasks.TaskCollection#getByName(String)}.</p>
96 *
97 * <h3>Dependencies</h3>
98 *
99 * <p>A project generally has a number of dependencies it needs in order to do its work. Also, a project generally
100 * produces a number of artifacts, which other projects can use. Those dependencies are grouped in configurations, and
101 * can be retrieved and uploaded from repositories. You use the {@link org.gradle.api.artifacts.ConfigurationContainer}
102 * returned by {@link #getConfigurations()} method to manage the configurations. The {@link
103 * org.gradle.api.artifacts.dsl.DependencyHandler} returned by {@link #getDependencies()} method to manage the
104 * dependencies. The {@link org.gradle.api.artifacts.dsl.ArtifactHandler} returned by {@link #getArtifacts()} method to
105 * manage the artifacts. The {@link org.gradle.api.artifacts.dsl.RepositoryHandler} returned by {@link
106 * #getRepositories()} method to manage the repositories.</p>
107 *
108 * <h3>Multi-project Builds</h3>
109 *
110 * <p>Projects are arranged into a hierarchy of projects. A project has a name, and a fully qualified path which
111 * uniquely identifies it in the hierarchy.</p>
112 *
113 * <h3>Plugins</h3>
114 *
115 * <p>
116 * Plugins can be used to modularise and reuse project configuration.
117 * Plugins can be applied using the {@link PluginAware#apply(java.util.Map)} method, or by using the {@link org.gradle.plugin.use.PluginDependenciesSpec plugins script block}.
118 * </p>
119 *
120 * <a name="properties"/> <h3>Properties</h3>
121 *
122 * <p>Gradle executes the project's build file against the <code>Project</code> instance to configure the project. Any
123 * property or method which your script uses is delegated through to the associated <code>Project</code> object. This
124 * means, that you can use any of the methods and properties on the <code>Project</code> interface directly in your script.
125 * </p><p>For example:
126 * <pre>
127 * defaultTasks('some-task') // Delegates to Project.defaultTasks()
128 * reportsDir = file('reports') // Delegates to Project.file() and the Java Plugin
129 * </pre>
130 * <p>You can also access the <code>Project</code> instance using the <code>project</code> property. This can make the
131 * script clearer in some cases. For example, you could use <code>project.name</code> rather than <code>name</code> to
132 * access the project's name.</p>
133 *
134 * <p>A project has 5 property 'scopes', which it searches for properties. You can access these properties by name in
135 * your build file, or by calling the project's {@link #property(String)} method. The scopes are:</p>
136 *
137 * <ul>
138 *
139 * <li>The <code>Project</code> object itself. This scope includes any property getters and setters declared by the
140 * <code>Project</code> implementation class. For example, {@link #getRootProject()} is accessible as the
141 * <code>rootProject</code> property. The properties of this scope are readable or writable depending on the presence
142 * of the corresponding getter or setter method.</li>
143 *
144 * <li>The <em>extra</em> properties of the project. Each project maintains a map of extra properties, which
145 * can contain any arbitrary name -> value pair. Once defined, the properties of this scope are readable and writable.
146 * See <a href="#extraproperties">extra properties</a> for more details.</li>
147 *
148 * <li>The <em>extensions</em> added to the project by the plugins. Each extension is available as a read-only property with the same name as the extension.</li>
149 *
150 * <li>The <em>convention</em> properties added to the project by the plugins. A plugin can add properties and methods
151 * to a project through the project's {@link Convention} object. The properties of this scope may be readable or writable, depending on the convention objects.</li>
152 *
153 * <li>The tasks of the project. A task is accessible by using its name as a property name. The properties of this
154 * scope are read-only. For example, a task called <code>compile</code> is accessible as the <code>compile</code>
155 * property.</li>
156 *
157 * <li>The extra properties and convention properties inherited from the project's parent, recursively up to the root
158 * project. The properties of this scope are read-only.</li>
159 *
160 * </ul>
161 *
162 * <p>When reading a property, the project searches the above scopes in order, and returns the value from the first
163 * scope it finds the property in. If not found, an exception is thrown. See {@link #property(String)} for more details.</p>
164 *
165 * <p>When writing a property, the project searches the above scopes in order, and sets the property in the first scope
166 * it finds the property in. If not found, an exception is thrown. See {@link #setProperty(String, Object)} for more details.</p>
167 *
168 * <a name="extraproperties"/> <h4>Extra Properties</h4>
169 *
170 * All extra properties must be defined through the "ext" namespace. Once an extra property has been defined,
171 * it is available directly on the owning object (in the below case the Project, Task, and sub-projects respectively) and can
172 * be read and updated. Only the initial declaration that needs to be done via the namespace.
173 *
174 * <pre>
175 * project.ext.prop1 = "foo"
176 * task doStuff {
177 * ext.prop2 = "bar"
178 * }
179 * subprojects { ext.${prop3} = false }
180 * </pre>
181 *
182 * Reading extra properties is done through the "ext" or through the owning object.
183 *
184 * <pre>
185 * ext.isSnapshot = version.endsWith("-SNAPSHOT")
186 * if (isSnapshot) {
187 * // do snapshot stuff
188 * }
189 * </pre>
190 *
191 * <h4>Dynamic Methods</h4>
192 *
193 * <p>A project has 5 method 'scopes', which it searches for methods:</p>
194 *
195 * <ul>
196 *
197 * <li>The <code>Project</code> object itself.</li>
198 *
199 * <li>The build file. The project searches for a matching method declared in the build file.</li>
200 *
201 * <li>The <em>extensions</em> added to the project by the plugins. Each extension is available as a method which takes
202 * a closure or {@link org.gradle.api.Action} as a parameter.</li>
203 *
204 * <li>The <em>convention</em> methods added to the project by the plugins. A plugin can add properties and method to
205 * a project through the project's {@link Convention} object.</li>
206 *
207 * <li>The tasks of the project. A method is added for each task, using the name of the task as the method name and
208 * taking a single closure or {@link org.gradle.api.Action} parameter. The method calls the {@link Task#configure(groovy.lang.Closure)} method for the
209 * associated task with the provided closure. For example, if the project has a task called <code>compile</code>, then a
210 * method is added with the following signature: <code>void compile(Closure configureClosure)</code>.</li>
211 *
212 * <li>The methods of the parent project, recursively up to the root project.</li>
213 *
214 * <li>A property of the project whose value is a closure. The closure is treated as a method and called with the provided parameters.
215 * The property is located as described above.</li>
216 *
217 * </ul>
218 */
219 @HasInternalProtocol
220 public interface Project extends Comparable<Project>, ExtensionAware, PluginAware {
221 /**
222 * The default project build file name.
223 */
224 String DEFAULT_BUILD_FILE = "build.gradle";
225
226 /**
227 * The hierarchy separator for project and task path names.
228 */
229 String PATH_SEPARATOR = ":";
230
231 /**
232 * The default build directory name.
233 */
234 String DEFAULT_BUILD_DIR_NAME = "build";
235
236 String GRADLE_PROPERTIES = "gradle.properties";
237
238 String SYSTEM_PROP_PREFIX = "systemProp";
239
240 String DEFAULT_VERSION = "unspecified";
241
242 String DEFAULT_STATUS = "release";
243
244 /**
245 * <p>Returns the root project for the hierarchy that this project belongs to. In the case of a single-project
246 * build, this method returns this project.</p>
247 *
248 * @return The root project. Never returns null.
249 */
250 Project getRootProject();
251
252 /**
253 * <p>Returns the root directory of this project. The root directory is the project directory of the root
254 * project.</p>
255 *
256 * @return The root directory. Never returns null.
257 */
258 File getRootDir();
259
260 /**
261 * <p>Returns the build directory of this project. The build directory is the directory which all artifacts are
262 * generated into. The default value for the build directory is <code><i>projectDir</i>/build</code></p>
263 *
264 * @return The build directory. Never returns null.
265 */
266 File getBuildDir();
267
268 /**
269 * <p>Sets the build directory of this project. The build directory is the directory which all artifacts are
270 * generated into.</p>
271 *
272 * @param path The build directory
273 * @since 4.0
274 */
275 void setBuildDir(File path);
276
277 /**
278 * <p>Sets the build directory of this project. The build directory is the directory which all artifacts are
279 * generated into. The path parameter is evaluated as described for {@link #file(Object)}. This mean you can use,
280 * amongst other things, a relative or absolute path or File object to specify the build directory.</p>
281 *
282 * @param path The build directory. This is evaluated as per {@link #file(Object)}
283 */
284 void setBuildDir(Object path);
285
286 /**
287 * <p>Returns the build file Gradle will evaluate against this project object. The default is <code> {@value
288 * #DEFAULT_BUILD_FILE}</code>. If an embedded script is provided the build file will be null. </p>
289 *
290 * @return Current build file. May return null.
291 */
292 File getBuildFile();
293
294 /**
295 * <p>Returns the parent project of this project, if any.</p>
296 *
297 * @return The parent project, or null if this is the root project.
298 */
299 Project getParent();
300
301 /**
302 * <p>Returns the name of this project. The project's name is not necessarily unique within a project hierarchy. You
303 * should use the {@link #getPath()} method for a unique identifier for the project.</p>
304 *
305 * @return The name of this project. Never return null.
306 */
307 String getName();
308
309 /**
310 * Returns a human-consumable display name for this project.
311 */
312 String getDisplayName();
313
314 /**
315 * Returns the description of this project, if any.
316 *
317 * @return the description. May return null.
318 */
319 String getDescription();
320
321 /**
322 * Sets a description for this project.
323 *
324 * @param description The description of the project. Might be null.
325 */
326 void setDescription(String description);
327
328 /**
329 * <p>Returns the group of this project. Gradle always uses the {@code toString()} value of the group. The group
330 * defaults to the path with dots as separators.</p>
331 *
332 * @return The group of this project. Never returns null.
333 */
334 Object getGroup();
335
336 /**
337 * <p>Sets the group of this project.</p>
338 *
339 * @param group The group of this project. Must not be null.
340 */
341 void setGroup(Object group);
342
343 /**
344 * <p>Returns the version of this project. Gradle always uses the {@code toString()} value of the version. The
345 * version defaults to {@value #DEFAULT_VERSION}.</p>
346 *
347 * @return The version of this project. Never returns null.
348 */
349 Object getVersion();
350
351 /**
352 * <p>Sets the version of this project.</p>
353 *
354 * @param version The version of this project. Must not be null.
355 */
356 void setVersion(Object version);
357
358 /**
359 * <p>Returns the status of this project. Gradle always uses the {@code toString()} value of the status. The status
360 * defaults to {@value #DEFAULT_STATUS}.</p>
361 *
362 * <p>The status of the project is only relevant, if you upload libraries together with a module descriptor. The
363 * status specified here, will be part of this module descriptor.</p>
364 *
365 * @return The status of this project. Never returns null.
366 */
367 Object getStatus();
368
369 /**
370 * Sets the status of this project.
371 *
372 * @param status The status. Must not be null.
373 */
374 void setStatus(Object status);
375
376 /**
377 * <p>Returns the direct children of this project.</p>
378 *
379 * @return A map from child project name to child project. Returns an empty map if this project does not have
380 * any children.
381 */
382 Map<String, Project> getChildProjects();
383
384 /**
385 * <p>Sets a property of this project. This method searches for a property with the given name in the following
386 * locations, and sets the property on the first location where it finds the property.</p>
387 *
388 * <ol>
389 *
390 * <li>The project object itself. For example, the <code>rootDir</code> project property.</li>
391 *
392 * <li>The project's {@link Convention} object. For example, the <code>srcRootName</code> java plugin
393 * property.</li>
394 *
395 * <li>The project's extra properties.</li>
396 *
397 * </ol>
398 *
399 * If the property is not found, a {@link groovy.lang.MissingPropertyException} is thrown.
400 *
401 * @param name The name of the property
402 * @param value The value of the property
403 */
404 void setProperty(String name, Object value) throws MissingPropertyException;
405
406 /**
407 * <p>Returns this project. This method is useful in build files to explicitly access project properties and
408 * methods. For example, using <code>project.name</code> can express your intent better than using
409 * <code>name</code>. This method also allows you to access project properties from a scope where the property may
410 * be hidden, such as, for example, from a method or closure. </p>
411 *
412 * @return This project. Never returns null.
413 */
414 Project getProject();
415
416 /**
417 * <p>Returns the set containing this project and its subprojects.</p>
418 *
419 * @return The set of projects.
420 */
421 Set<Project> getAllprojects();
422
423 /**
424 * <p>Returns the set containing the subprojects of this project.</p>
425 *
426 * @return The set of projects. Returns an empty set if this project has no subprojects.
427 */
428 Set<Project> getSubprojects();
429
430 /**
431 * <p>Creates a {@link Task} with the given name and adds it to this project. Calling this method is equivalent to
432 * calling {@link #task(java.util.Map, String)} with an empty options map.</p>
433 *
434 * <p>After the task is added to the project, it is made available as a property of the project, so that you can
435 * reference the task by name in your build file. See <a href="#properties">here</a> for more details</p>
436 *
437 * <p>If a task with the given name already exists in this project, an exception is thrown.</p>
438 *
439 * @param name The name of the task to be created
440 * @return The newly created task object
441 * @throws InvalidUserDataException If a task with the given name already exists in this project.
442 */
443 Task task(String name) throws InvalidUserDataException;
444
445 /**
446 * <p>Creates a {@link Task} with the given name and adds it to this project. A map of creation options can be
447 * passed to this method to control how the task is created. The following options are available:</p>
448 *
449 * <table>
450 *
451 * <tr><th>Option</th><th>Description</th><th>Default Value</th></tr>
452 *
453 * <tr><td><code>{@value org.gradle.api.Task#TASK_TYPE}</code></td><td>The class of the task to
454 * create.</td><td>{@link org.gradle.api.DefaultTask}</td></tr>
455 *
456 * <tr><td><code>{@value org.gradle.api.Task#TASK_OVERWRITE}</code></td><td>Replace an existing
457 * task?</td><td><code>false</code></td></tr>
458 *
459 *
460 * <tr><td><code>{@value org.gradle.api.Task#TASK_DEPENDS_ON}</code></td><td>A task name or set of task names which
461 * this task depends on</td><td><code>[]</code></td></tr>
462 *
463 * <tr><td><code>{@value org.gradle.api.Task#TASK_ACTION}</code></td><td>A closure or {@link Action} to add to the
464 * task.</td><td><code>null</code></td></tr>
465 *
466 * <tr><td><code>{@value org.gradle.api.Task#TASK_DESCRIPTION}</code></td><td>A description of the task.
467 * </td><td><code>null</code></td></tr>
468 *
469 * <tr><td><code>{@value org.gradle.api.Task#TASK_GROUP}</code></td><td>A task group which this task belongs to.
470 * </td><td><code>null</code></td></tr>
471 *
472 * </table>
473 *
474 * <p>After the task is added to the project, it is made available as a property of the project, so that you can
475 * reference the task by name in your build file. See <a href="#properties">here</a> for more details</p>
476 *
477 * <p>If a task with the given name already exists in this project and the <code>override</code> option is not set
478 * to true, an exception is thrown.</p>
479 *
480 * @param args The task creation options.
481 * @param name The name of the task to be created
482 * @return The newly created task object
483 * @throws InvalidUserDataException If a task with the given name already exists in this project.
484 */
485 Task task(Map<String, ?> args, String name) throws InvalidUserDataException;
486
487 /**
488 * <p>Creates a {@link Task} with the given name and adds it to this project. Before the task is returned, the given
489 * closure is executed to configure the task. A map of creation options can be passed to this method to control how
490 * the task is created. See {@link #task(java.util.Map, String)} for the available options.</p>
491 *
492 * <p>After the task is added to the project, it is made available as a property of the project, so that you can
493 * reference the task by name in your build file. See <a href="#properties">here</a> for more details</p>
494 *
495 * <p>If a task with the given name already exists in this project and the <code>override</code> option is not set
496 * to true, an exception is thrown.</p>
497 *
498 * @param args The task creation options.
499 * @param name The name of the task to be created
500 * @param configureClosure The closure to use to configure the created task.
501 * @return The newly created task object
502 * @throws InvalidUserDataException If a task with the given name already exists in this project.
503 */
504 Task task(Map<String, ?> args, String name, @DelegatesTo(value = Task.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
505
506 /**
507 * <p>Creates a {@link Task} with the given name and adds it to this project. Before the task is returned, the given
508 * closure is executed to configure the task.</p> <p/> <p>After the task is added to the project, it is made
509 * available as a property of the project, so that you can reference the task by name in your build file. See <a
510 * href="#properties">here</a> for more details</p>
511 *
512 * @param name The name of the task to be created
513 * @param configureClosure The closure to use to configure the created task.
514 * @return The newly created task object
515 * @throws InvalidUserDataException If a task with the given name already exists in this project.
516 */
517 Task task(String name, @DelegatesTo(value = Task.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
518
519 /**
520 * <p>Returns the path of this project. The path is the fully qualified name of the project.</p>
521 *
522 * @return The path. Never returns null.
523 */
524 String getPath();
525
526 /**
527 * <p>Returns the names of the default tasks of this project. These are used when no tasks names are provided when
528 * starting the build.</p>
529 *
530 * @return The default task names. Returns an empty list if this project has no default tasks.
531 */
532 List<String> getDefaultTasks();
533
534 /**
535 * <p>Sets the names of the default tasks of this project. These are used when no tasks names are provided when
536 * starting the build.</p>
537 *
538 * @param defaultTasks The default task names.
539 */
540 void setDefaultTasks(List<String> defaultTasks);
541
542 /**
543 * <p>Sets the names of the default tasks of this project. These are used when no tasks names are provided when
544 * starting the build.</p>
545 *
546 * @param defaultTasks The default task names.
547 */
548 void defaultTasks(String... defaultTasks);
549
550 /**
551 * <p>Declares that this project has an evaluation dependency on the project with the given path.</p>
552 *
553 * @param path The path of the project which this project depends on.
554 * @return The project which this project depends on.
555 * @throws UnknownProjectException If no project with the given path exists.
556 */
557 Project evaluationDependsOn(String path) throws UnknownProjectException;
558
559 /**
560 * <p>Declares that this project has an evaluation dependency on each of its child projects.</p>
561 *
562 */
563 void evaluationDependsOnChildren();
564
565 /**
566 * <p>Locates a project by path. If the path is relative, it is interpreted relative to this project.</p>
567 *
568 * @param path The path.
569 * @return The project with the given path. Returns null if no such project exists.
570 */
571 Project findProject(String path);
572
573 /**
574 * <p>Locates a project by path. If the path is relative, it is interpreted relative to this project.</p>
575 *
576 * @param path The path.
577 * @return The project with the given path. Never returns null.
578 * @throws UnknownProjectException If no project with the given path exists.
579 */
580 Project project(String path) throws UnknownProjectException;
581
582 /**
583 * <p>Locates a project by path and configures it using the given closure. If the path is relative, it is
584 * interpreted relative to this project. The target project is passed to the closure as the closure's delegate.</p>
585 *
586 * @param path The path.
587 * @param configureClosure The closure to use to configure the project.
588 * @return The project with the given path. Never returns null.
589 * @throws UnknownProjectException If no project with the given path exists.
590 */
591 Project project(String path, @DelegatesTo(value = Project.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
592
593 /**
594 * <p>Locates a project by path and configures it using the given action. If the path is relative, it is
595 * interpreted relative to this project.</p>
596 *
597 * @param path The path.
598 * @param configureAction The action to use to configure the project.
599 * @return The project with the given path. Never returns null.
600 * @throws UnknownProjectException If no project with the given path exists.
601 *
602 * @since 3.4
603 */
604 Project project(String path, Action<? super Project> configureAction);
605
606 /**
607 * <p>Returns a map of the tasks contained in this project, and optionally its subprojects.</p>
608 *
609 * @param recursive If true, returns the tasks of this project and its subprojects. If false, returns the tasks of
610 * just this project.
611 * @return A map from project to a set of tasks.
612 */
613 Map<Project, Set<Task>> getAllTasks(boolean recursive);
614
615 /**
616 * <p>Returns the set of tasks with the given name contained in this project, and optionally its subprojects.</p>
617 *
618 * @param name The name of the task to locate.
619 * @param recursive If true, returns the tasks of this project and its subprojects. If false, returns the tasks of
620 * just this project.
621 * @return The set of tasks. Returns an empty set if no such tasks exist in this project.
622 */
623 Set<Task> getTasksByName(String name, boolean recursive);
624
625 /**
626 * <p>The directory containing the project build file.</p>
627 *
628 * @return The project directory. Never returns null.
629 */
630 File getProjectDir();
631
632 /**
633 * <p>Resolves a file path relative to the project directory of this project. This method converts the supplied path
634 * based on its type:</p>
635 *
636 * <ul>
637 *
638 * <li>A {@link CharSequence}, including {@link String} or {@link groovy.lang.GString}. Interpreted relative to the project directory. A string
639 * that starts with {@code file:} is treated as a file URL.</li>
640 *
641 * <li>A {@link File}. If the file is an absolute file, it is returned as is. Otherwise, the file's path is
642 * interpreted relative to the project directory.</li>
643 *
644 * <li>A {@link java.nio.file.Path}. The path must be associated with the default provider and is treated the
645 * same way as an instance of {@code File}.</li>
646 *
647 * <li>A {@link java.net.URI} or {@link java.net.URL}. The URL's path is interpreted as the file path. Currently, only
648 * {@code file:} URLs are supported.</li>
649 *
650 * <li>A {@link Closure}. The closure's return value is resolved recursively.</li>
651 *
652 * <li>A {@link java.util.concurrent.Callable}. The callable's return value is resolved recursively.</li>
653 *
654 * </ul>
655 *
656 * @param path The object to resolve as a File.
657 * @return The resolved file. Never returns null.
658 */
659 File file(Object path);
660
661 /**
662 * <p>Resolves a file path relative to the project directory of this project and validates it using the given
663 * scheme. See {@link PathValidation} for the list of possible validations.</p>
664 *
665 * @param path An object which toString method value is interpreted as a relative path to the project directory.
666 * @param validation The validation to perform on the file.
667 * @return The resolved file. Never returns null.
668 * @throws InvalidUserDataException When the file does not meet the given validation constraint.
669 */
670 File file(Object path, PathValidation validation) throws InvalidUserDataException;
671
672 /**
673 * <p>Resolves a file path to a URI, relative to the project directory of this project. Evaluates the provided path
674 * object as described for {@link #file(Object)}, with the exception that any URI scheme is supported, not just
675 * 'file:' URIs.</p>
676 *
677 * @param path The object to resolve as a URI.
678 * @return The resolved URI. Never returns null.
679 */
680 URI uri(Object path);
681
682 /**
683 * <p>Returns the relative path from the project directory to the given path. The given path object is (logically)
684 * resolved as described for {@link #file(Object)}, from which a relative path is calculated.</p>
685 *
686 * @param path The path to convert to a relative path.
687 * @return The relative path. Never returns null.
688 */
689 String relativePath(Object path);
690
691 /**
692 * <p>Returns a {@link ConfigurableFileCollection} containing the given files. You can pass any of the following
693 * types to this method:</p>
694 *
695 * <ul> <li>A {@link CharSequence}, including {@link String} or {@link groovy.lang.GString}. Interpreted relative to the project directory, as per {@link #file(Object)}. A string
696 * that starts with {@code file:} is treated as a file URL.</li>
697 *
698 * <li>A {@link File}. Interpreted relative to the project directory, as per {@link #file(Object)}.</li>
699 *
700 * <li>A {@link java.nio.file.Path} as defined by {@link #file(Object)}.</li>
701 *
702 * <li>A {@link java.net.URI} or {@link java.net.URL}. The URL's path is interpreted as a file path. Currently, only
703 * {@code file:} URLs are supported.</li>
704 *
705 * <li>A {@link java.util.Collection}, {@link Iterable}, or an array. May contain any of the types listed here. The elements of the collection
706 * are recursively converted to files.</li>
707 *
708 * <li>A {@link org.gradle.api.file.FileCollection}. The contents of the collection are included in the returned
709 * collection.</li>
710 *
711 * <li>A {@link java.util.concurrent.Callable}. The {@code call()} method may return any of the types listed here.
712 * The return value of the {@code call()} method is recursively converted to files. A {@code null} return value is
713 * treated as an empty collection.</li>
714 *
715 * <li>A Closure. May return any of the types listed here. The return value of the closure is recursively converted
716 * to files. A {@code null} return value is treated as an empty collection.</li>
717 *
718 * <li>A {@link Task}. Converted to the task's output files.</li>
719 *
720 * <li>A {@link org.gradle.api.tasks.TaskOutputs}. Converted to the output files the related task.</li>
721 *
722 * <li>Anything else is treated as a failure.</li>
723 *
724 * </ul>
725 *
726 * <p>The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
727 * collection are queried. The file collection is also live, so that it evaluates the above each time the contents
728 * of the collection is queried.</p>
729 *
730 * <p>The returned file collection maintains the iteration order of the supplied paths.</p>
731 *
732 * @param paths The paths to the files. May be empty.
733 * @return The file collection. Never returns null.
734 */
735 ConfigurableFileCollection files(Object... paths);
736
737 /**
738 * <p>Creates a new {@code ConfigurableFileCollection} using the given paths. The paths are evaluated as per {@link
739 * #files(Object...)}. The file collection is configured using the given closure. The file collection is passed to
740 * the closure as its delegate. Example:</p>
741 * <pre>
742 * files "$buildDir/classes" {
743 * builtBy 'compile'
744 * }
745 * </pre>
746 * <p>The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
747 * collection are queried. The file collection is also live, so that it evaluates the above each time the contents
748 * of the collection is queried.</p>
749 *
750 * @param paths The contents of the file collection. Evaluated as per {@link #files(Object...)}.
751 * @param configureClosure The closure to use to configure the file collection.
752 * @return the configured file tree. Never returns null.
753 */
754 ConfigurableFileCollection files(Object paths, @DelegatesTo(value = ConfigurableFileCollection.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
755
756 /**
757 * <p>Creates a new {@code ConfigurableFileCollection} using the given paths. The paths are evaluated as per {@link
758 * #files(Object...)}. The file collection is configured using the given action. Example:</p>
759 * <pre>
760 * files "$buildDir/classes" {
761 * builtBy 'compile'
762 * }
763 * </pre>
764 * <p>The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
765 * collection are queried. The file collection is also live, so that it evaluates the above each time the contents
766 * of the collection is queried.</p>
767 *
768 * @param paths The contents of the file collection. Evaluated as per {@link #files(Object...)}.
769 * @param configureAction The action to use to configure the file collection.
770 * @return the configured file tree. Never returns null.
771 * @since 3.5
772 */
773 ConfigurableFileCollection files(Object paths, Action<? super ConfigurableFileCollection> configureAction);
774
775 /**
776 * <p>Creates a new {@code ConfigurableFileTree} using the given base directory. The given baseDir path is evaluated
777 * as per {@link #file(Object)}.</p>
778 *
779 * <p>The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
780 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
781 * queried.</p>
782 *
783 * <pre autoTested=''>
784 * def myTree = fileTree("src")
785 * myTree.include "**/*.java"
786 * myTree.builtBy "someTask"
787 *
788 * task copy(type: Copy) {
789 * from myTree
790 * }
791 * </pre>
792 *
793 * @param baseDir The base directory of the file tree. Evaluated as per {@link #file(Object)}.
794 * @return the file tree. Never returns null.
795 */
796 ConfigurableFileTree fileTree(Object baseDir);
797
798 /**
799 * <p>Creates a new {@code ConfigurableFileTree} using the given base directory. The given baseDir path is evaluated
800 * as per {@link #file(Object)}. The closure will be used to configure the new file tree.
801 * The file tree is passed to the closure as its delegate. Example:</p>
802 *
803 * <pre autoTested=''>
804 * def myTree = fileTree('src') {
805 * exclude '**/.data/**'
806 * builtBy 'someTask'
807 * }
808 *
809 * task copy(type: Copy) {
810 * from myTree
811 * }
812 * </pre>
813 *
814 * <p>The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
815 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
816 * queried.</p>
817 *
818 * @param baseDir The base directory of the file tree. Evaluated as per {@link #file(Object)}.
819 * @param configureClosure Closure to configure the {@code ConfigurableFileTree} object.
820 * @return the configured file tree. Never returns null.
821 */
822 ConfigurableFileTree fileTree(Object baseDir, @DelegatesTo(value = ConfigurableFileTree.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
823
824 /**
825 * <p>Creates a new {@code ConfigurableFileTree} using the given base directory. The given baseDir path is evaluated
826 * as per {@link #file(Object)}. The action will be used to configure the new file tree. Example:</p>
827 *
828 * <pre autoTested=''>
829 * def myTree = fileTree('src') {
830 * exclude '**/.data/**'
831 * builtBy 'someTask'
832 * }
833 *
834 * task copy(type: Copy) {
835 * from myTree
836 * }
837 * </pre>
838 *
839 * <p>The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
840 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
841 * queried.</p>
842 *
843 * @param baseDir The base directory of the file tree. Evaluated as per {@link #file(Object)}.
844 * @param configureAction Action to configure the {@code ConfigurableFileTree} object.
845 * @return the configured file tree. Never returns null.
846 * @since 3.5
847 */
848 ConfigurableFileTree fileTree(Object baseDir, Action<? super ConfigurableFileTree> configureAction);
849
850 /**
851 * <p>Creates a new {@code ConfigurableFileTree} using the provided map of arguments. The map will be applied as
852 * properties on the new file tree. Example:</p>
853 *
854 * <pre autoTested=''>
855 * def myTree = fileTree(dir:'src', excludes:['**/ignore/**', '**/.data/**'])
856 *
857 * task copy(type: Copy) {
858 * from myTree
859 * }
860 * </pre>
861 *
862 * <p>The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
863 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
864 * queried.</p>
865 *
866 * @param args map of property assignments to {@code ConfigurableFileTree} object
867 * @return the configured file tree. Never returns null.
868 */
869 ConfigurableFileTree fileTree(Map<String, ?> args);
870
871 /**
872 * <p>Creates a new {@code FileTree} which contains the contents of the given ZIP file. The given zipPath path is
873 * evaluated as per {@link #file(Object)}. You can combine this method with the {@link #copy(groovy.lang.Closure)}
874 * method to unzip a ZIP file.</p>
875 *
876 * <p>The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
877 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
878 * queried.</p>
879 *
880 * @param zipPath The ZIP file. Evaluated as per {@link #file(Object)}.
881 * @return the file tree. Never returns null.
882 */
883 FileTree zipTree(Object zipPath);
884
885 /**
886 * Creates a new {@code FileTree} which contains the contents of the given TAR file. The given tarPath path can be:
887 * <ul>
888 * <li>an instance of {@link org.gradle.api.resources.Resource}</li>
889 * <li>any other object is evaluated as per {@link #file(Object)}</li>
890 * </ul>
891 *
892 * The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
893 * queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
894 * queried.
895 * <p>
896 * Unless custom implementation of resources is passed, the tar tree attempts to guess the compression based on the file extension.
897 * <p>
898 * You can combine this method with the {@link #copy(groovy.lang.Closure)}
899 * method to untar a TAR file:
900 *
901 * <pre autoTested=''>
902 * task untar(type: Copy) {
903 * from tarTree('someCompressedTar.gzip')
904 *
905 * //tar tree attempts to guess the compression based on the file extension
906 * //however if you must specify the compression explicitly you can:
907 * from tarTree(resources.gzip('someTar.ext'))
908 *
909 * //in case you work with unconventionally compressed tars
910 * //you can provide your own implementation of a ReadableResource:
911 * //from tarTree(yourOwnResource as ReadableResource)
912 *
913 * into 'dest'
914 * }
915 * </pre>
916 *
917 * @param tarPath The TAR file or an instance of {@link org.gradle.api.resources.Resource}.
918 * @return the file tree. Never returns null.
919 */
920 FileTree tarTree(Object tarPath);
921
922 /**
923 * Creates a {@code Provider} implementation based on the provided value.
924 *
925 * @param value The {@code java.util.concurrent.Callable} use to calculate the value.
926 * @return The provider. Never returns null.
927 * @throws org.gradle.api.InvalidUserDataException If the provided value is null.
928 * @see org.gradle.api.provider.ProviderFactory#provider(Callable)
929 * @since 4.0
930 */
931 @Incubating
932 <T> Provider<T> provider(Callable<T> value);
933
934 /**
935 * Creates a {@code PropertyState} implementation based on the provided class.
936 *
937 * @param clazz The class to be used for property state.
938 * @return The property state. Never returns null.
939 * @throws org.gradle.api.InvalidUserDataException If the provided class is null.
940 * @see org.gradle.api.provider.ProviderFactory#property(Class)
941 * @since 4.0
942 */
943 @Incubating
944 <T> PropertyState<T> property(Class<T> clazz);
945
946 /**
947 * Provides access to methods to create various kinds of {@link Provider} instances.
948 *
949 * @since 4.0
950 */
951 @Incubating
952 ProviderFactory getProviders();
953
954 /**
955 * Provides access to methods to create various kinds of model objects.
956 *
957 * @since 4.0
958 */
959 @Incubating
960 ObjectFactory getObjects();
961
962 /**
963 * Creates a directory and returns a file pointing to it.
964 *
965 * @param path The path for the directory to be created. Evaluated as per {@link #file(Object)}.
966 * @return the created directory
967 * @throws org.gradle.api.InvalidUserDataException If the path points to an existing file.
968 */
969 File mkdir(Object path);
970
971 /**
972 * Deletes files and directories.
973 * <p>
974 * This will not follow symlinks. If you need to follow symlinks too use {@link #delete(Action)}.
975 *
976 * @param paths Any type of object accepted by {@link org.gradle.api.Project#files(Object...)}
977 * @return true if anything got deleted, false otherwise
978 */
979 boolean delete(Object... paths);
980
981 /**
982 * Deletes the specified files. The given action is used to configure a {@link DeleteSpec}, which is then used to
983 * delete the files.
984 * <p>Example:
985 * <pre>
986 * project.delete {
987 * delete 'somefile'
988 * followSymlinks = true
989 * }
990 * </pre>
991 *
992 * @param action Action to configure the DeleteSpec
993 * @return {@link WorkResult} that can be used to check if delete did any work.
994 */
995 WorkResult delete(Action<? super DeleteSpec> action);
996
997 /**
998 * Executes a Java main class. The closure configures a {@link org.gradle.process.JavaExecSpec}.
999 *
1000 * @param closure The closure for configuring the execution.
1001 * @return the result of the execution
1002 */
1003 ExecResult javaexec(@DelegatesTo(value = JavaExecSpec.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.process.JavaExecSpec"}) Closure closure);
1004
1005 /**
1006 * Executes an external Java process.
1007 * <p>
1008 * The given action configures a {@link org.gradle.process.JavaExecSpec}, which is used to launch the process.
1009 * This method blocks until the process terminates, with its result being returned.
1010 *
1011 * @param action The action for configuring the execution.
1012 * @return the result of the execution
1013 */
1014 ExecResult javaexec(Action<? super JavaExecSpec> action);
1015
1016 /**
1017 * Executes an external command. The closure configures a {@link org.gradle.process.ExecSpec}.
1018 *
1019 * @param closure The closure for configuring the execution.
1020 * @return the result of the execution
1021 */
1022 ExecResult exec(@DelegatesTo(value = ExecSpec.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.process.ExecSpec"}) Closure closure);
1023
1024 /**
1025 * Executes an external command.
1026 * <p>
1027 * The given action configures a {@link org.gradle.process.ExecSpec}, which is used to launch the process.
1028 * This method blocks until the process terminates, with its result being returned.
1029 *
1030 * @param action The action for configuring the execution.
1031 * @return the result of the execution
1032 */
1033 ExecResult exec(Action<? super ExecSpec> action);
1034
1035 /**
1036 * <p>Converts a name to an absolute project path, resolving names relative to this project.</p>
1037 *
1038 * @param path The path to convert.
1039 * @return The absolute path.
1040 */
1041 String absoluteProjectPath(String path);
1042
1043 /**
1044 * <p>Converts a name to a project path relative to this project.</p>
1045 *
1046 * @param path The path to convert.
1047 * @return The relative path.
1048 */
1049 String relativeProjectPath(String path);
1050
1051 /**
1052 * <p>Returns the <code>AntBuilder</code> for this project. You can use this in your build file to execute ant
1053 * tasks. See example below.</p>
1054 * <pre autoTested=''>
1055 * task printChecksum {
1056 * doLast {
1057 * ant {
1058 * //using ant checksum task to store the file checksum in the checksumOut ant property
1059 * checksum(property: 'checksumOut', file: 'someFile.txt')
1060 *
1061 * //we can refer to the ant property created by checksum task:
1062 * println "The checksum is: " + checksumOut
1063 * }
1064 *
1065 * //we can refer to the ant property later as well:
1066 * println "I just love to print checksums: " + ant.checksumOut
1067 * }
1068 * }
1069 * </pre>
1070 *
1071 * Consider following example of ant target:
1072 * <pre>
1073 * <target name='printChecksum'>
1074 * <checksum property='checksumOut'>
1075 * <fileset dir='.'>
1076 * <include name='agile.txt'/>
1077 * </fileset>
1078 * </checksum>
1079 * <echo>The checksum is: ${checksumOut}</echo>
1080 * </target>
1081 * </pre>
1082 *
1083 * Here's how it would look like in gradle. Observe how the ant XML is represented in groovy by the ant builder
1084 * <pre autoTested=''>
1085 * task printChecksum {
1086 * doLast {
1087 * ant {
1088 * checksum(property: 'checksumOut') {
1089 * fileset(dir: '.') {
1090 * include name: 'agile1.txt'
1091 * }
1092 * }
1093 * }
1094 * logger.lifecycle("The checksum is $ant.checksumOut")
1095 * }
1096 * }
1097 * </pre>
1098 *
1099 * @return The <code>AntBuilder</code> for this project. Never returns null.
1100 */
1101 AntBuilder getAnt();
1102
1103 /**
1104 * <p>Creates an additional <code>AntBuilder</code> for this project. You can use this in your build file to execute
1105 * ant tasks.</p>
1106 *
1107 * @return Creates an <code>AntBuilder</code> for this project. Never returns null.
1108 * @see #getAnt()
1109 */
1110 AntBuilder createAntBuilder();
1111
1112 /**
1113 * <p>Executes the given closure against the <code>AntBuilder</code> for this project. You can use this in your
1114 * build file to execute ant tasks. The <code>AntBuilder</code> is passed to the closure as the closure's
1115 * delegate. See example in javadoc for {@link #getAnt()}</p>
1116 *
1117 * @param configureClosure The closure to execute against the <code>AntBuilder</code>.
1118 * @return The <code>AntBuilder</code>. Never returns null.
1119 */
1120 AntBuilder ant(@DelegatesTo(value = AntBuilder.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(ReturnType.class) Closure configureClosure);
1121
1122 /**
1123 * <p>Executes the given action against the <code>AntBuilder</code> for this project. You can use this in your
1124 * build file to execute ant tasks. See example in javadoc for {@link #getAnt()}</p>
1125 *
1126 * @param configureAction The action to execute against the <code>AntBuilder</code>.
1127 * @return The <code>AntBuilder</code>. Never returns null.
1128 * @since 3.5
1129 */
1130 AntBuilder ant(Action<? super AntBuilder> configureAction);
1131
1132 /**
1133 * Returns the configurations of this project.
1134 *
1135 * <h3>Examples:</h3> See docs for {@link ConfigurationContainer}
1136 *
1137 * @return The configuration of this project.
1138 */
1139 ConfigurationContainer getConfigurations();
1140
1141 /**
1142 * <p>Configures the dependency configurations for this project.
1143 *
1144 * <p>This method executes the given closure against the {@link ConfigurationContainer}
1145 * for this project. The {@link ConfigurationContainer} is passed to the closure as the closure's delegate.
1146 *
1147 * <h3>Examples:</h3> See docs for {@link ConfigurationContainer}
1148 *
1149 * @param configureClosure the closure to use to configure the dependency configurations.
1150 */
1151 void configurations(@DelegatesTo(value = ConfigurationContainer.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.artifacts.ConfigurationContainer"}) Closure configureClosure);
1152
1153 /**
1154 * Returns a handler for assigning artifacts produced by the project to configurations.
1155 * <h3>Examples:</h3>See docs for {@link ArtifactHandler}
1156 */
1157 ArtifactHandler getArtifacts();
1158
1159 /**
1160 * <p>Configures the published artifacts for this project.
1161 *
1162 * <p>This method executes the given closure against the {@link ArtifactHandler} for this project. The {@link
1163 * ArtifactHandler} is passed to the closure as the closure's delegate.
1164 *
1165 * <p>Example:
1166 * <pre autoTested=''>
1167 * configurations {
1168 * //declaring new configuration that will be used to associate with artifacts
1169 * schema
1170 * }
1171 *
1172 * task schemaJar(type: Jar) {
1173 * //some imaginary task that creates a jar artifact with the schema
1174 * }
1175 *
1176 * //associating the task that produces the artifact with the configuration
1177 * artifacts {
1178 * //configuration name and the task:
1179 * schema schemaJar
1180 * }
1181 * </pre>
1182 *
1183 * @param configureClosure the closure to use to configure the published artifacts.
1184 */
1185 void artifacts(@DelegatesTo(value = ArtifactHandler.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.artifacts.dsl.ArtifactHandler"}) Closure configureClosure);
1186
1187 /**
1188 * <p>Configures the published artifacts for this project.
1189 *
1190 * <p>This method executes the given action against the {@link ArtifactHandler} for this project.
1191 *
1192 * <p>Example:
1193 * <pre autoTested=''>
1194 * configurations {
1195 * //declaring new configuration that will be used to associate with artifacts
1196 * schema
1197 * }
1198 *
1199 * task schemaJar(type: Jar) {
1200 * //some imaginary task that creates a jar artifact with the schema
1201 * }
1202 *
1203 * //associating the task that produces the artifact with the configuration
1204 * artifacts {
1205 * //configuration name and the task:
1206 * schema schemaJar
1207 * }
1208 * </pre>
1209 *
1210 * @param configureAction the action to use to configure the published artifacts.
1211 * @since 3.5
1212 */
1213 void artifacts(Action<? super ArtifactHandler> configureAction);
1214
1215 /**
1216 * <p>Returns the {@link Convention} for this project.</p> <p/> <p>You can access this property in your build file
1217 * using <code>convention</code>. You can also can also access the properties and methods of the convention object
1218 * as if they were properties and methods of this project. See <a href="#properties">here</a> for more details</p>
1219 *
1220 * @return The <code>Convention</code>. Never returns null.
1221 */
1222 Convention getConvention();
1223
1224 /**
1225 * <p>Compares the nesting level of this project with another project of the multi-project hierarchy.</p>
1226 *
1227 * @param otherProject The project to compare the nesting level with.
1228 * @return a negative integer, zero, or a positive integer as this project has a nesting level less than, equal to,
1229 * or greater than the specified object.
1230 * @see #getDepth()
1231 */
1232 int depthCompare(Project otherProject);
1233
1234 /**
1235 * <p>Returns the nesting level of a project in a multi-project hierarchy. For single project builds this is always
1236 * 0. In a multi-project hierarchy 0 is returned for the root project.</p>
1237 */
1238 int getDepth();
1239
1240 /**
1241 * <p>Returns the tasks of this project.</p>
1242 *
1243 * @return the tasks of this project.
1244 */
1245 TaskContainer getTasks();
1246
1247 /**
1248 * <p>Configures the sub-projects of this project</p>
1249 *
1250 * <p>This method executes the given {@link Action} against the sub-projects of this project.</p>
1251 *
1252 * @param action The action to execute.
1253 */
1254 void subprojects(Action<? super Project> action);
1255
1256 /**
1257 * <p>Configures the sub-projects of this project.</p>
1258 *
1259 * <p>This method executes the given closure against each of the sub-projects of this project. The target {@link
1260 * Project} is passed to the closure as the closure's delegate.</p>
1261 *
1262 * @param configureClosure The closure to execute.
1263 */
1264 void subprojects(@DelegatesTo(value = Project.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.Project"}) Closure configureClosure);
1265
1266 /**
1267 * <p>Configures this project and each of its sub-projects.</p>
1268 *
1269 * <p>This method executes the given {@link Action} against this project and each of its sub-projects.</p>
1270 *
1271 * @param action The action to execute.
1272 */
1273 void allprojects(Action<? super Project> action);
1274
1275 /**
1276 * <p>Configures this project and each of its sub-projects.</p>
1277 *
1278 * <p>This method executes the given closure against this project and its sub-projects. The target {@link Project}
1279 * is passed to the closure as the closure's delegate.</p>
1280 *
1281 * @param configureClosure The closure to execute.
1282 */
1283 void allprojects(@DelegatesTo(value = Project.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.Project"}) Closure configureClosure);
1284
1285 /**
1286 * Adds an action to execute immediately before this project is evaluated.
1287 *
1288 * @param action the action to execute.
1289 */
1290 void beforeEvaluate(Action<? super Project> action);
1291
1292 /**
1293 * Adds an action to execute immediately after this project is evaluated.
1294 *
1295 * @param action the action to execute.
1296 */
1297 void afterEvaluate(Action<? super Project> action);
1298
1299 /**
1300 * <p>Adds a closure to be called immediately before this project is evaluated. The project is passed to the closure
1301 * as a parameter.</p>
1302 *
1303 * @param closure The closure to call.
1304 */
1305 void beforeEvaluate(@ClosureParams(value = SimpleType.class, options = {"org.gradle.api.Project"}) Closure closure);
1306
1307 /**
1308 * <p>Adds a closure to be called immediately after this project has been evaluated. The project is passed to the
1309 * closure as a parameter. Such a listener gets notified when the build file belonging to this project has been
1310 * executed. A parent project may for example add such a listener to its child project. Such a listener can further
1311 * configure those child projects based on the state of the child projects after their build files have been
1312 * run.</p>
1313 *
1314 * @param closure The closure to call.
1315 */
1316 void afterEvaluate(@ClosureParams(value = SimpleType.class, options = {"org.gradle.api.Project"}) Closure closure);
1317
1318 /**
1319 * <p>Determines if this project has the given property. See <a href="#properties">here</a> for details of the
1320 * properties which are available for a project.</p>
1321 *
1322 * @param propertyName The name of the property to locate.
1323 * @return True if this project has the given property, false otherwise.
1324 */
1325 boolean hasProperty(String propertyName);
1326
1327 /**
1328 * <p>Returns the properties of this project. See <a href="#properties">here</a> for details of the properties which
1329 * are available for a project.</p>
1330 *
1331 * @return A map from property name to value.
1332 */
1333 Map<String, ?> getProperties();
1334
1335 /**
1336 * <p>Returns the value of the given property. This method locates a property as follows:</p>
1337 *
1338 * <ol>
1339 *
1340 * <li>If this project object has a property with the given name, return the value of the property.</li>
1341 *
1342 * <li>If this project has an extension with the given name, return the extension.</li>
1343 *
1344 * <li>If this project's convention object has a property with the given name, return the value of the
1345 * property.</li>
1346 *
1347 * <li>If this project has an extra property with the given name, return the value of the property.</li>
1348 *
1349 * <li>If this project has a task with the given name, return the task.</li>
1350 *
1351 * <li>Search up through this project's ancestor projects for a convention property or extra property with the
1352 * given name.</li>
1353 *
1354 * <li>If not found, a {@link MissingPropertyException} is thrown.</li>
1355 *
1356 * </ol>
1357 *
1358 * @param propertyName The name of the property.
1359 * @return The value of the property, possibly null.
1360 * @throws MissingPropertyException When the given property is unknown.
1361 * @see Project#findProperty(String)
1362 */
1363 Object property(String propertyName) throws MissingPropertyException;
1364
1365 /**
1366 * <p>Returns the value of the given property or null if not found.
1367 * This method locates a property as follows:</p>
1368 *
1369 * <ol>
1370 *
1371 * <li>If this project object has a property with the given name, return the value of the property.</li>
1372 *
1373 * <li>If this project has an extension with the given name, return the extension.</li>
1374 *
1375 * <li>If this project's convention object has a property with the given name, return the value of the
1376 * property.</li>
1377 *
1378 * <li>If this project has an extra property with the given name, return the value of the property.</li>
1379 *
1380 * <li>If this project has a task with the given name, return the task.</li>
1381 *
1382 * <li>Search up through this project's ancestor projects for a convention property or extra property with the
1383 * given name.</li>
1384 *
1385 * <li>If not found, null value is returned.</li>
1386 *
1387 * </ol>
1388 *
1389 * @param propertyName The name of the property.
1390 * @return The value of the property, possibly null or null if not found.
1391 * @see Project#property(String)
1392 */
1393 @Incubating @Nullable
1394 Object findProperty(String propertyName);
1395
1396 /**
1397 * <p>Returns the logger for this project. You can use this in your build file to write log messages.</p>
1398 *
1399 * @return The logger. Never returns null.
1400 */
1401 Logger getLogger();
1402
1403 /**
1404 * <p>Returns the {@link org.gradle.api.invocation.Gradle} invocation which this project belongs to.</p>
1405 *
1406 * @return The Gradle object. Never returns null.
1407 */
1408 Gradle getGradle();
1409
1410 /**
1411 * Returns the {@link org.gradle.api.logging.LoggingManager} which can be used to receive logging and to control the
1412 * standard output/error capture for this project's build script. By default, System.out is redirected to the Gradle
1413 * logging system at the QUIET log level, and System.err is redirected at the ERROR log level.
1414 *
1415 * @return the LoggingManager. Never returns null.
1416 */
1417 LoggingManager getLogging();
1418
1419 /**
1420 * <p>Configures an object via a closure, with the closure's delegate set to the supplied object. This way you don't
1421 * have to specify the context of a configuration statement multiple times. <p/> Instead of:</p>
1422 * <pre>
1423 * MyType myType = new MyType()
1424 * myType.doThis()
1425 * myType.doThat()
1426 * </pre>
1427 * <p/> you can do:
1428 * <pre>
1429 * MyType myType = configure(new MyType()) {
1430 * doThis()
1431 * doThat()
1432 * }
1433 * </pre>
1434 *
1435 * <p>The object being configured is also passed to the closure as a parameter, so you can access it explicitly if
1436 * required:</p>
1437 * <pre>
1438 * configure(someObj) { obj -> obj.doThis() }
1439 * </pre>
1440 *
1441 * @param object The object to configure
1442 * @param configureClosure The closure with configure statements
1443 * @return The configured object
1444 */
1445 Object configure(Object object, Closure configureClosure);
1446
1447 /**
1448 * Configures a collection of objects via a closure. This is equivalent to calling {@link #configure(Object,
1449 * groovy.lang.Closure)} for each of the given objects.
1450 *
1451 * @param objects The objects to configure
1452 * @param configureClosure The closure with configure statements
1453 * @return The configured objects.
1454 */
1455 Iterable<?> configure(Iterable<?> objects, Closure configureClosure);
1456
1457 /**
1458 * Configures a collection of objects via an action.
1459 *
1460 * @param objects The objects to configure
1461 * @param configureAction The action to apply to each object
1462 * @return The configured objects.
1463 */
1464 <T> Iterable<T> configure(Iterable<T> objects, Action<? super T> configureAction);
1465
1466 /**
1467 * Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts
1468 * produced by the project.
1469 *
1470 * @return the repository handler. Never returns null.
1471 */
1472 RepositoryHandler getRepositories();
1473
1474 /**
1475 * <p>Configures the repositories for this project.
1476 *
1477 * <p>This method executes the given closure against the {@link RepositoryHandler} for this project. The {@link
1478 * RepositoryHandler} is passed to the closure as the closure's delegate.
1479 *
1480 * @param configureClosure the closure to use to configure the repositories.
1481 */
1482 void repositories(@DelegatesTo(value = RepositoryHandler.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.artifacts.dsl.RepositoryHandler"}) Closure configureClosure);
1483
1484 /**
1485 * Returns the dependency handler of this project. The returned dependency handler instance can be used for adding
1486 * new dependencies. For accessing already declared dependencies, the configurations can be used.
1487 *
1488 * <h3>Examples:</h3>
1489 * See docs for {@link DependencyHandler}
1490 *
1491 * @return the dependency handler. Never returns null.
1492 * @see #getConfigurations()
1493 */
1494 DependencyHandler getDependencies();
1495
1496 /**
1497 * <p>Configures the dependencies for this project.
1498 *
1499 * <p>This method executes the given closure against the {@link DependencyHandler} for this project. The {@link
1500 * DependencyHandler} is passed to the closure as the closure's delegate.
1501 *
1502 * <h3>Examples:</h3>
1503 * See docs for {@link DependencyHandler}
1504 *
1505 * @param configureClosure the closure to use to configure the dependencies.
1506 */
1507 void dependencies(@DelegatesTo(value = DependencyHandler.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.artifacts.dsl.DependencyHandler"}) Closure configureClosure);
1508
1509 /**
1510 * Returns the build script handler for this project. You can use this handler to query details about the build
1511 * script for this project, and manage the classpath used to compile and execute the project's build script.
1512 *
1513 * @return the classpath handler. Never returns null.
1514 */
1515 ScriptHandler getBuildscript();
1516
1517 /**
1518 * <p>Configures the build script classpath for this project.
1519 *
1520 * <p>The given closure is executed against this project's {@link ScriptHandler}. The {@link ScriptHandler} is
1521 * passed to the closure as the closure's delegate.
1522 *
1523 * @param configureClosure the closure to use to configure the build script classpath.
1524 */
1525 void buildscript(@DelegatesTo(value = ScriptHandler.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.initialization.dsl.ScriptHandler"}) Closure configureClosure);
1526
1527 /**
1528 * Copies the specified files. The given closure is used to configure a {@link CopySpec}, which is then used to
1529 * copy the files. Example:
1530 * <pre>
1531 * copy {
1532 * from configurations.runtime
1533 * into 'build/deploy/lib'
1534 * }
1535 * </pre>
1536 * Note that CopySpecs can be nested:
1537 * <pre>
1538 * copy {
1539 * into 'build/webroot'
1540 * exclude '**/.svn/**'
1541 * from('src/main/webapp') {
1542 * include '**/*.jsp'
1543 * filter(ReplaceTokens, tokens:[copyright:'2009', version:'2.3.1'])
1544 * }
1545 * from('src/main/js') {
1546 * include '**/*.js'
1547 * }
1548 * }
1549 * </pre>
1550 *
1551 * @param closure Closure to configure the CopySpec
1552 * @return {@link WorkResult} that can be used to check if the copy did any work.
1553 */
1554 WorkResult copy(@DelegatesTo(value = CopySpec.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.file.CopySpec"}) Closure closure);
1555
1556 /**
1557 * Copies the specified files. The given action is used to configure a {@link CopySpec}, which is then used to
1558 * copy the files.
1559 * @see #copy(Closure)
1560 * @param action Action to configure the CopySpec
1561 * @return {@link WorkResult} that can be used to check if the copy did any work.
1562 */
1563 WorkResult copy(Action<? super CopySpec> action);
1564
1565 /**
1566 * Creates a {@link CopySpec} which can later be used to copy files or create an archive. The given closure is used
1567 * to configure the {@link CopySpec} before it is returned by this method.
1568 *
1569 * <pre autoTested=''>
1570 * def baseSpec = copySpec {
1571 * from "source"
1572 * include "**/*.java"
1573 * }
1574 *
1575 * task copy(type: Copy) {
1576 * into "target"
1577 * with baseSpec
1578 * }
1579 * </pre>
1580 *
1581 * @param closure Closure to configure the CopySpec
1582 * @return The CopySpec
1583 */
1584 CopySpec copySpec(@DelegatesTo(value = CopySpec.class, strategy = Closure.DELEGATE_FIRST) @ClosureParams(value = SimpleType.class, options = {"org.gradle.api.file.CopySpec"}) Closure closure);
1585
1586 /**
1587 * Creates a {@link CopySpec} which can later be used to copy files or create an archive. The given action is used
1588 * to configure the {@link CopySpec} before it is returned by this method.
1589 *
1590 * @see #copySpec(Closure)
1591 * @param action Action to configure the CopySpec
1592 * @return The CopySpec
1593 */
1594 CopySpec copySpec(Action<? super CopySpec> action);
1595
1596 /**
1597 * Creates a {@link CopySpec} which can later be used to copy files or create an archive.
1598 *
1599 * @return a newly created copy spec
1600 */
1601 CopySpec copySpec();
1602
1603 /**
1604 * Synchronizes the contents of a destination directory with some source directories and files.
1605 * The given action is used to configure a {@link CopySpec}, which is then used to synchronize the files.
1606 *
1607 * <p>
1608 * This method is like the {@link #copy(Action)} task, except the destination directory will only contain the files copied.
1609 * All files that exist in the destination directory will be deleted before copying files, unless a preserve option is specified.
1610 *
1611 * <p>
1612 * Example:
1613 *
1614 * <pre>
1615 * project.sync {
1616 * from 'my/shared/dependencyDir'
1617 * into 'build/deps/compile'
1618 * }
1619 * </pre>
1620 * Note that you can preserve output that already exists in the destination directory:
1621 * <pre>
1622 * project.sync {
1623 * from 'source'
1624 * into 'dest'
1625 * preserve {
1626 * include 'extraDir/**'
1627 * include 'dir1/**'
1628 * exclude 'dir1/extra.txt'
1629 * }
1630 * }
1631 * </pre>
1632 *
1633 * @param action Action to configure the CopySpec.
1634 * @since 4.0
1635 * @return {@link WorkResult} that can be used to check if the sync did any work.
1636 */
1637 WorkResult sync(Action<? super CopySpec> action);
1638
1639 /**
1640 * Returns the evaluation state of this project. You can use this to access information about the evaluation of this
1641 * project, such as whether it has failed.
1642 *
1643 * @return the project state. Never returns null.
1644 */
1645 ProjectState getState();
1646
1647 /**
1648 * <p>Creates a container for managing named objects of the specified type. The specified type must have a public constructor which takes the name as a String parameter.<p>
1649 *
1650 * <p>All objects <b>MUST</b> expose their name as a bean property named "name". The name must be constant for the life of the object.</p>
1651 *
1652 * @param type The type of objects for the container to contain.
1653 * @param <T> The type of objects for the container to contain.
1654 * @return The container.
1655 */
1656 <T> NamedDomainObjectContainer<T> container(Class<T> type);
1657
1658 /**
1659 * <p>Creates a container for managing named objects of the specified type. The given factory is used to create object instances.</p>
1660 *
1661 * <p>All objects <b>MUST</b> expose their name as a bean property named "name". The name must be constant for the life of the object.</p>
1662 *
1663 * @param type The type of objects for the container to contain.
1664 * @param factory The factory to use to create object instances.
1665 * @param <T> The type of objects for the container to contain.
1666 * @return The container.
1667 */
1668 <T> NamedDomainObjectContainer<T> container(Class<T> type, NamedDomainObjectFactory<T> factory);
1669
1670 /**
1671 * <p>Creates a container for managing named objects of the specified type. The given closure is used to create object instances. The name of the instance to be created is passed as a parameter to
1672 * the closure.</p>
1673 *
1674 * <p>All objects <b>MUST</b> expose their name as a bean property named "name". The name must be constant for the life of the object.</p>
1675 *
1676 * @param type The type of objects for the container to contain.
1677 * @param factoryClosure The closure to use to create object instances.
1678 * @param <T> The type of objects for the container to contain.
1679 * @return The container.
1680 */
1681 <T> NamedDomainObjectContainer<T> container(Class<T> type, @ClosureParams(value = SimpleType.class, options = {"java.lang.String"}) Closure factoryClosure);
1682
1683 /**
1684 * Allows adding DSL extensions to the project. Useful for plugin authors.
1685 *
1686 * @return Returned instance allows adding DSL extensions to the project
1687 */
1688 ExtensionContainer getExtensions();
1689
1690 /**
1691 * Provides access to resource-specific utility methods, for example factory methods that create various resources.
1692 *
1693 * @return Returned instance contains various resource-specific utility methods.
1694 */
1695 ResourceHandler getResources();
1696
1697 /**
1698 * Returns the software components produced by this project.
1699 *
1700 * @return The components for this project.
1701 */
1702 @Incubating
1703 SoftwareComponentContainer getComponents();
1704
1705 /**
1706 * Provides access to configuring input normalization.
1707 *
1708 * @since 4.0
1709 */
1710 @Incubating
1711 InputNormalizationHandler getNormalization();
1712
1713 /**
1714 * Configures input normalization.
1715 *
1716 * @since 4.0
1717 */
1718 @Incubating
1719 void normalization(Action<? super InputNormalizationHandler> configuration);
1720 }
