Why gradle jars are written in `build/libs`?

Question

According to the documentation of the Jar plugin, the output directory is controlled by the destinationDir property:

• File destinationDir

  The directory where the archive is generated into.

  Default with java plugin: project.distsDir

Looking at the documentation of the Project class the same property is mentioned:

Properties added by the java plugin

• distsDir: The directory to generate TAR and ZIP archives into.
• distsDirName: The name for the distributions directory. This in interpreted relative to the project' build directory.

And Googling a bit I find a document specifying their defaults:

• File distsDir (read-only)

  The directory to generate TAR and ZIP archives into.

  Default with java plugin: ${project.buildDir}/${project.distsDirName}

• String distsDirName

  The name for the distributions directory. This in interpreted relative to the project' build directory.

  Default with java plugin: 'distributions'

All these documents point to the same Gradle version, that matches the one I have installed.

I add this in my build.gradle to check the real values of these properties:

println("distsDirName = " + project.distsDirName)
println("distsDir = " + project.distsDir.toString())

jar {
    println("jar.destinationDir = " + destinationDir)
}

And finally, I run ./gradlew and check the output:

distsDirName = distributions
distsDir = /home/ntrrgc/myProject/build/distributions
jar.destinationDir = /home/ntrrgc/myProject/build/libs

Why does jar.destinationDir not respect its documented default?

Answer 1

I think, @Alicia is right in pointing out that currently the documentation of the Gradle Jar plugin is providing wrong information in the default value for the File destinationDir:

File destinationDir

The directory where the archive is generated into.

Default with java plugin:

project.distsDir

where default of distsDir is 'build/distributions' as can be here.

In my opinion, it should be

File destinationDir

The directory where the archive is generated into.

Default with java plugin:

project.libsDir

where default of libsDir is 'build/libs' as can be seen here again.

I have opened Gradle issue #1086 for this. Let us see, what they answer.