====

A typical project including `buildSrc` has the following layout.
Any code under `buildSrc` should use a package similar to application code.
Optionally, the `buildSrc` directory can host a build script if additional configuration is needed (e.g. to apply plugins or to declare dependencies).

====
[.multi-language-sample]
=====
[source,kotlin]
----
.
├── buildSrc
│   ├── build.gradle.kts

        buildFile << customTaskCode("root")
        file("buildSrc/build.gradle") << customTaskCode("buildSrc") << """
            jar.dependsOn customTask
        """
        file("i1/build.gradle") << customTaskCode("i1")
        file("i1/buildSrc/build.gradle") << customTaskCode("i1:buildSrc") << """
            jar.dependsOn customTask
        """
        file("i2/build.gradle") << customTaskCode("i2")

        then:
        output.contains('system_property_available in buildSrc:                 true')
        output.contains('system_property_available in buildSrc:                 true')
        output.contains("project_property_available in buildSrc:                ${projectPropertyAvailableInBuildSrc()}")
        output.contains('system_property_available in included buildSrc:        true')

====

[[sec:build_cache_composite]]
=== Build cache, composite builds and `buildSrc`

Gradle's <<composite_builds.adoc#composite_builds,composite build feature>> allows including other complete Gradle builds into another.
Such included builds will inherit the build cache configuration from the top level build, regardless of whether the included builds define build cache configuration themselves or not.

@TargetGradleVersion(">=3.1")
class PersistentCompositeDependencySubstitutionCrossVersionSpec extends ToolingApiSpecification implements WithOldConfigurationsSupport {
    TestFile buildA
    TestFile buildB
    TestFile buildC

    def setup() {

        buildA = singleProjectBuildInRootFolder("buildA") {
            buildFile << """
                apply plugin: 'java'
                dependencies {

        nestedBuild.buildIdentifier == buildIdentifier(":buildSrc")
        nestedBuild.identityPath == Path.path(":buildSrc")

        and:
        notifiedBuilds == [rootBuild, nestedBuild]

        and:
        registry.getBuild(nestedBuild.buildIdentifier).is(nestedBuild)
    }

    def "can add multiple buildSrc builds with different levels of nesting"() {
        given:

After startup, Gradle initializes your project. Usually, Gradle only processes your settings file.
If you have custom build logic in a `buildSrc` directory, Gradle also processes that logic.
After building `buildSrc` once, Gradle considers it up to date. The up-to-date checks take significantly less time than logic processing.
If your `buildSrc` phase takes too much time, consider breaking it out into a separate project.

+
If you are developing custom Gradle plugins for your project, `buildSrc` is a convenient place to house the plugin code.
This makes the plugins easily accessible within your project.

The `buildSrc` directory is treated as an <<composite_builds.adoc#composite_build_intro,included build>>.

For multi-project builds, there can be only one `buildSrc` directory, which must be in the root project directory.

        output.contains('system_property_available in buildSrc:                 true')
        output.contains('project_property_available in buildSrc:                false')
        output.contains('overridden_by_includedBuild in buildSrc:               null')
        output.contains('system_property_available in included buildSrc:        true')
        output.contains('project_property_available in included buildSrc:       false')

     */
    IncludedBuildState addImplicitIncludedBuild(BuildDefinition buildDefinition);

    /**
     * Locates the buildSrc build for the given build, if present. Returns null if the given build does not have an associated buildSrc build.
     */
    @Nullable
    StandAloneNestedBuild getBuildSrcNestedBuild(BuildState owner);

    /**
     * Creates a new standalone nested build tree.