// 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.
=====
====

== 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.

== 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.

To learn more about scripting the settings file, see <<writing_settings_files.adoc#writing_settings_files,Writing Settings Files>>.

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