How to determine what goes into settings.gradle vs. bulid.gradle?

Question

I am currently learning gradle by reading a bunch of gradle books and looking through the gradle build scripts for large java projects like the spring framework, hibernate and the gradle project itself with the goal of understanding best practices of using gradle.

I have noticed that in a gradle multiproject build there are two files settings.gradle and build.gradle my questions are.

• Is settings.gradle absolutely required for a multi project build? can it be rolled into the build.gradle file?
• In a few of the open source projects that I have looked at I have noticed that settings.gradle actually contains code and not just settings see examples of code I found in various settings.gradle files. What kind of code is supposed to put into settings.gradle? is there a best practice as to what goes into settings.grdale vs. build.gradle that should be followed? Are the linked open source projects breaking those best practices rules?

From Spring Security Project settings.gradle just a selected few lines of code from https://github.com/spring-projects/spring-security/blob/master/settings.gradle

include modules

modules.each {name ->
    def p = findProject(":${name}")
    p.name = "spring-security-${name}"
    p.buildFileName = "${name}.gradle"
}

include samples

samples.each {name ->
    def p = findProject(":${name}")
    def fullName = name.replaceAll('/','')
    p.name = "spring-security-samples-${fullName}"
    p.projectDir = new File(settingsDir, "samples/${name}");
    if(!p.buildFile.exists()) {
        def buildFile = fullName.replaceFirst("-xml","")
        p.buildFileName = "${buildFile}.gradle"
    }
}

And from the gradle project itself a small snippet from https://github.com/gradle/gradle/blob/master/settings.gradle

rootProject.children.each {project ->
    String fileBaseName = project.name.replaceAll("\\p{Upper}") { "-${it.toLowerCase()}" }
    String projectDirName = "subprojects/$fileBaseName"
    project.projectDir = new File(settingsDir, projectDirName)
    project.buildFileName = "${fileBaseName}.gradle"
    assert project.projectDir.isDirectory()
    assert project.buildFile.isFile()
}

Answer 1

settings.gradle corresponds to the following class and it's an executable script as well as build.gradle. It's not necessary in single module projects (but may be defined to e.g. declare project name) but it's required in multimodule projects because it configures such projects (see include for instance). It cannot be rolled into build.gradle because of different API.

Yes, settings.gradle contains code as stated above (normal script + corresponding class). Basically it should contain code associated with multimodule project configuration (modules inclusion, paths, names) exactly what You can see in the examples provided. There's no strictly defined set of good practices - you should rely on docs mainly. With time and after getting more experienced you'll know what should be put there.

Hope it helped. Feel free to ask for any clarification.