Gradle Settings Script and Settings Instance: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(47 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
=DEPLETE TO=
{{Internal|Gradle Settings|Gradle Settings}}


* https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html
=Overview=


=Internal=
The settings.gradle file describes the build's project hierarchy. In the simplest case, there is no settings.gradle, and the build consists in just a single project, the root project. In more complex cases, various sub-project hierarchies can be specified. The file can also be used to add libraries to the build script classpath. The configuration file is executed during the [[Gradle_Concepts#Build_Initialization_Phase|initialization phase]] and updates the state of the delegate [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html Settings] instance. For single-project builds, this file is optional. However, it is required for [[Gradle_Project_and_Build_Script#Multi-Project_Builds|multi-project builds]]: the root project of the multi-project build must declare this file.


* [[Gradle_Concepts#Settings_Script|Gradle Concepts]]
=Project Hierarchy=


=Overview=
<font color=darkgray>TODO: next time I am here, describe differences between 'include' and 'includeFlat'.</font>


The settings.gradle file describes the build's project hierarchy. In the simplest case, there is no settings.gradle, and the build consists in just a single project, the root project. In more complex cases, various sub-project hierarchies can be specified. The file can also be used to add libraries to the build script classpath. The configuration file is executed during the [[Gradle_Concepts#Build_Initialization_Phase|initialization phase]] and updates the state of the delegate [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html Settings] instance. For single-project builds, this file is optional. However, it is required for [[Gradle_Project#Multi-Project_Builds|multi-project builds]]: the root project of the multi-project build must declare this file.
The sub-projects of a [[Gradle_Multi-Project_Builds#Overview|multi-project build]] are declared in the settings.gradle file of the [[Gradle_Multi-Project_Builds#Root_Project|root project]] with the Settings [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String&#91;&#93;) include(...)] or [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeFlat(java.lang.String&#91;&#93;) includeFlat(...)] methods:
 
A bootstrap settings.gradle may be created automatically on project initialization with [[Gradle_Operations#Start_a_Project|gradle init]].  
 
The subprojects are declared in the [[Gradle_Concepts_ToDeplete#Multi-Project_Build|root project]] settings.gradle with the "include" or "includeFlat" methods:


<syntaxhighlight lang='groovy'>
<syntaxhighlight lang='groovy'>
include 'subproject1', 'subproject2:subsubproject3'
include 'subproject1', 'subproject2:child1'
</syntaxhighlight>
</syntaxhighlight>
<span id='include'></span>The [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String&#91;&#93;) include(...)] method specifies a multi-project build [[Gradle_Multi-Project_Builds#Hierarchical_Layout|hierarchical layout]]. It takes hierarchical project paths as arguments.


<syntaxhighlight lang='groovy'>
<syntaxhighlight lang='groovy'>
Line 23: Line 22:
</syntaxhighlight>
</syntaxhighlight>


The "include" method takes hierarchical project paths as arguments, while "includePath" expects a flat sibling structure. For more details about syntax, see [[Gradle_Concepts_ToDeplete#Hierarchical|Hierarchical Layout]] and [[Gradle_Concepts_ToDeplete#Flat|Flat Layout]].
<span id='includeFlat'></span>The [https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeFlat(java.lang.String&#91;&#93;) includeFlat(...)] method specifies a multi-project build [[Gradle_Multi-Project_Builds#Flat_Layout|flat layout]]. It expects a flat sibling structure.
 
The property access and method calls within the settings file is delegated to a [https://docs.gradle.org/4.7/dsl/org.gradle.api.initialization.Settings.html Settings] instance.


=Resolution=
=Resolution=
Line 34: Line 31:
* If found, Gradle checks if the current project is part of multi-project hierarchy defined in the found settings.gradle file. If not, the build is executed as a single project build. Otherwise, a multi project build executed.
* If found, Gradle checks if the current project is part of multi-project hierarchy defined in the found settings.gradle file. If not, the build is executed as a single project build. Otherwise, a multi project build executed.


=Properties=
=rootProject.name=
 
<syntaxhighlight lang='groovy'>
rootProject.name = 'some-name'
</syntaxhighlight>
 
More details:


* [[Gradle_Properties#rootProject.name|rootProject.name]]
{{Internal|Gradle_Project_Coordinates,_State_and_Configured_Properties#rootProject|rootProject}}

Latest revision as of 21:39, 11 October 2020

DEPLETE TO

Gradle Settings

Overview

The settings.gradle file describes the build's project hierarchy. In the simplest case, there is no settings.gradle, and the build consists in just a single project, the root project. In more complex cases, various sub-project hierarchies can be specified. The file can also be used to add libraries to the build script classpath. The configuration file is executed during the initialization phase and updates the state of the delegate Settings instance. For single-project builds, this file is optional. However, it is required for multi-project builds: the root project of the multi-project build must declare this file.

Project Hierarchy

TODO: next time I am here, describe differences between 'include' and 'includeFlat'.

The sub-projects of a multi-project build are declared in the settings.gradle file of the root project with the Settings include(...) or includeFlat(...) methods:

include 'subproject1', 'subproject2:child1'

The include(...) method specifies a multi-project build hierarchical layout. It takes hierarchical project paths as arguments.

includeFlat 'subproject1', 'subproject2'

The includeFlat(...) method specifies a multi-project build flat layout. It expects a flat sibling structure.

Resolution

  • Look at a directory called "master" on the same nesting level as the current directory.
  • If not found, search parent directories.
  • If not found, the build executes as a single project build.
  • If found, Gradle checks if the current project is part of multi-project hierarchy defined in the found settings.gradle file. If not, the build is executed as a single project build. Otherwise, a multi project build executed.

rootProject.name

rootProject.name = 'some-name'

More details:

rootProject