org.gradle.api.initialization.Settings Maven / Gradle / Ivy
Show all versions of gradle-api Show documentation
/*
* 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;
/**
* Declares the configuration required to instantiate and configure the hierarchy of {@link
* org.gradle.api.Project} instances which are to participate in a build.
*
* There is a one-to-one correspondence between a Settings instance and a {@value
* #DEFAULT_SETTINGS_FILE} settings file. Before Gradle assembles the projects for a build, it creates a
* Settings instance and executes the settings file against it.
*
* Assembling a Multi-Project Build
*
* One of the purposes of the Settings 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 Settings 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.
*
* 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.
*
* Using Settings in a Settings File
*
* Dynamic Properties
*
* 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:
*
*
*
* - Defined in the {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the settings directory of the
* build.
*
* - Defined the {@value org.gradle.api.Project#GRADLE_PROPERTIES} file located in the user's {@code .gradle}
* directory.
*
* - Provided on the command-line using the -P option.
*
*
*/
@HasInternalProtocol
public interface Settings extends PluginAware, ExtensionAware {
/**
* The default name for the settings file.
*/
String DEFAULT_SETTINGS_FILE = "settings.gradle";
/**
* 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 '/').
*
* 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)})
*
* 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.
*
* Some common examples of using the project path are:
*
*
* // 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
* }
*
*
* @param projectPaths the projects to add.
*/
default void include(String... projectPaths) {
include(Arrays.asList(projectPaths));
}
/**
* 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 '/').
*
* 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)})
*
* 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.
*
* Some common examples of using the project path are:
*
*
* // 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
* }
*
*
* @param projectPaths the projects to add.
*
* @since 7.4
*/
void include(Iterable projectPaths);
/**
* 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.
*
* The supplied name is converted to a project directory relative to the parent directory of the root
* project directory.
*
* As an example, the name {@code a} add a project with path {@code :a}, name {@code a} and project directory
* {@code $rootDir/../a}.
*
* @param projectNames the projects to add.
*/
default void includeFlat(String... projectNames) {
includeFlat(Arrays.asList(projectNames));
}
/**
* 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.
*
* The supplied name is converted to a project directory relative to the parent directory of the root
* project directory.
*
* As an example, the name {@code a} add a project with path {@code :a}, name {@code a} and project directory
* {@code $rootDir/../a}.
*
* @param projectNames the projects to add.
*
* @since 7.4
*/
void includeFlat(Iterable projectNames);
/**
* Returns this settings object.
*
* @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();
/**
* Returns the settings directory of the build. The settings directory is the directory containing the settings
* file.
*
* @return The settings directory. Never returns null.
*/
File getSettingsDir();
/**
* Returns the root directory of the build. The root directory is the project directory of the root project.
*
* @return The root directory. Never returns null.
*/
File getRootDir();
/**
* Returns the root project of the build.
*
* @return The root project. Never returns null.
*/
@Restricted
ProjectDescriptor getRootProject();
/**
* Returns the project with the given path.
*
* @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;
/**
* Returns the project with the given path.
*
* @param path The path
* @return The project with the given path. Returns null if no such project exists.
*/
@Nullable
ProjectDescriptor findProject(String path);
/**
* Returns the project with the given project directory.
*
* @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;
/**
* Returns the project with the given project directory.
*
* @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);
/**
* Returns the set of parameters used to invoke this instance of Gradle.
*
* @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 configuration);
/**
* Returns the build cache configuration.
*
* @since 3.5
*/
BuildCacheConfiguration getBuildCache();
/**
* Configures build cache.
*
* @since 3.5
*/
void buildCache(Action action);
/**
* Configures plugin management.
*
* @since 3.5
*/
@Configuring
void pluginManagement(Action pluginManagementSpec);
/**
* Returns the plugin management configuration.
*
* @since 3.5
*/
@Restricted
PluginManagementSpec getPluginManagement();
/**
* Configures source control.
*
* @since 4.4
*/
void sourceControl(Action 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 dependencyResolutionConfiguration);
/**
* Returns the dependency resolution management handler.
*
* @since 6.8
*/
@Restricted
DependencyResolutionManagement getDependencyResolutionManagement();
/**
* Configures toolchain management.
*
* @since 7.6
*/
@Incubating
void toolchainManagement(Action 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 cachesConfiguration);
/**
* Returns the model defaults object for this build.
*
* This is an experimental feature.
*
* @since 8.10
*/
@Incubating
SharedModelDefaults getDefaults();
/**
* Configures the model defaults for this build.
*
* This is an experimental feature.
*
* @param action the configuration to apply
*
* @since 8.10
*/
@Incubating
void defaults(Action action);
}