// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[settings_file_basics]]
= Settings File Basics

The settings file (`settings.gradle(.kts)`) is the *entry point* of every Gradle project.

image::gradle-basic-3.png[]

The primary purpose of the _settings file_ is to define the project structure, usually adding subprojects to your build.
Therefore in:

- *Single-project* builds, the settings file is *optional*.
- *Multi-project* builds, the settings file is *mandatory* and declares all subprojects.

[[sec:settings_file_script]]
== Settings script

*The settings file is a script.*
It is either a `settings.gradle` file written in Groovy or a `settings.gradle.kts` file in Kotlin.

The link:{groovyDslPath}/index.html[Groovy DSL^] and the link:{kotlinDslPath}/index.html[Kotlin DSL^] are the only accepted languages for Gradle scripts.

The settings file is typically located in the root directory of the project since it *defines the structure of the build*, such as which projects are included.
Without a settings file, Gradle treats the build as a single-project build by default.

Let's take a look at an example and break it down:

====
[.multi-language-sample]
=====
.settings.gradle.kts
[source,kotlin]
----
rootProject.name = "root-project"   // <1>

include("sub-project-a")            // <2>
include("sub-project-b")
include("sub-project-c")
----
<1> Define the project name.
<2> Add subprojects.
=====
[.multi-language-sample]
=====
.settings.gradle
[source,groovy]
----
rootProject.name = 'root-project'   // <1>

include('sub-project-a')            // <2>
include('sub-project-b')
include('sub-project-c')
----
<1> Define the project name.
<2> Add subprojects.
=====
====

[[sec:define_project_name]]
== 1. Define the project name

The settings file defines your project name:

[source,kotlin]
----
rootProject.name = "root-project"
----

There is only one root project per build.

[[sec:add_subprojects]]
== 2. Add subprojects

The settings file defines the structure of the project by including subprojects, if there are any:

[source,kotlin]
----
include("sub-project-a")
include("sub-project-b")
include("sub-project-c")
----

The settings script is evaluated before any build scripts, making it the right place to enable or configure **build-wide features** such as plugin management, included builds, version catalogs, and more.
We will explore these Gradle features in the advanced concepts section.

Based on the example settings file, Gradle expects the project to look as follows:

[source,text]
----
.
├── settings.gradle(.kts)   // <1>
├── sub-project-a
│   └── build.gradle(.kts)      // <2>
├── sub-project-b
│   └── build.gradle(.kts)      // <2>
└── sub-project-c
    └── build.gradle(.kts)      // <2>
----
<1> The `settings.gradle(.kts)` file.
<2> The three subprojects, each with their own `build.gradle(.kts)` file.

[.text-right]
**Next Step:** <<build_file_basics.adoc#build_file_basics,Learn about the Build scripts>> >>
