User Guide: Clarify "naming convention" used in flat layout

In Section 56.4, “Initialization”, there is the following sentence in the paragraph that describes the automatic search for the “settings.gradle” file: >The auto search for a settings file does only work for multi-project builds with a physical hierarchical or flat layout. For a flat layout you must additionally obey to the naming convention described above.

Just to be clear, the only thing that resembles a “naming convention” described above this is the reference to looking for a project named “master”. Is this the only thing this is referring to?

Assuming this is true, I would assume that “obey” is a little strong, as I believe it is also possible to simply put the “settings.gradle” in the parent directory, instead of having a “master” project as a peer of all the other projects in the multi-project build. On the other hand, would this now not be a “flat layout” and would confuse it, or what?

In a flat directory layout, the project directory for the root project and the project directories for all subprojects (no matter how deep their nesting level) are all siblings of each other. Naming the root project directory ‘master’ gives the additional benefit that subproject builds can be executed from their respective project directories (as known from builds with hierarchical directory layout).

So just to be clear, you can’t do something like this:

/rootProject /rootProject/settings.gradle (with “includeFlat ‘project1’,‘project2’”) /rootProject/project1/build.gradle /rootProject/project2/build.gradle

You would instead have to have the following?

/rootProject /rootProject/master/settings.gradle (with “includeFlat ‘project1’,‘project2’”) /rootProject/project1/build.gradle /rootProject/project2/build.gradle

‘includeFlat’ is a shortcut for doing ‘include’ and setting ‘ProjectDescriptor#projectDir’ to a sibling dir. Hence the first snippet won’t work. The second will work, even if the dir isn’t named “master”.