Gradle SourceSets are a key concept for the Gradle Java Plugin which define the structure of Java Source Files. In this example will see how to use this concept, customize them through gradle properties, create a new sourceset, get documentation and assembling them in a JAR.
1. Introduction to Gradle SourceSets
1.1 What is a Gradle SourceSet ?
A SourceSet is a collection of java source files and additional resource files that are compiled and assembled together to be executed. The main idea of sourcesets is to group files with a common meaning for the project, with no need of separate them in another project.
2. What do We Need?
- As IDE: Eclipse Luna 4.4
- Eclipse Gradle Plugin
- JDK 1.7_75 or higher
- Gradle 2.3
But the main idea is to edit a build.gradle script and you can do this with only a plain text editor, also should have a java project ready to work on it.
3.Environment Configuration
Please set your Gradle environment variables and install the Gradle plugin on your IDE. To avoid to be boilerplate visit this previous posts that show how to configure your Gradle Environment. Gradle Hello World Tutorial & Gradle GWT Integration Example
4.Creating a Gradle Project
Go to the Eclipse Wizard and then use Gradle Project Wizard.
Then, please choose in sample project Java API and Implementation because is most useful for this example, but you can use any other.
5.Generated Build.Gradle (New SourceSet Definition)
If we go to the build.gradle file in project’s root, we find a script like this:
apply plugin: "java"
apply plugin: "maven"
group = "myorg"
version = 1.0
repositories {
mavenCentral()
}
dependencies {
apiCompile 'commons-codec:commons-codec:1.5'
implCompile sourceSets.api.output
implCompile 'commons-lang:commons-lang:2.6'
testCompile 'junit:junit:4.9'
testCompile sourceSets.api.output
testCompile sourceSets.impl.output
runtime configurations.apiRuntime
runtime configurations.implRuntime
}
sourceSets.all { set ->
def jarTask = task("${set.name}Jar", type: Jar) {
baseName = baseName + "-$set.name"
from set.output
}
artifacts {
archives jarTask
}
}
sourceSets {
api
impl
}
jar {
from sourceSets.api.output
from sourceSets.impl.output
}
uploadArchives {
repositories {
mavenDeployer {
repository(url: uri("${buildDir}/repo"))
addFilter("main") { artifact, file -> artifact.name == project.name }
["api", "impl"].each { type ->
addFilter(type) { artifact, file -> artifact.name.endsWith("-$type") }
// We now have to map our configurations to the correct maven scope for each pom
["compile", "runtime"].each { scope ->
configuration = configurations[type + scope.capitalize()]
["main", type].each { pomName ->
pom(pomName).scopeMappings.addMapping 1, configuration, scope
}
}
}
}
}
}
So, this script has a some tasks configurations, take a look to each:
- First we apply java and maven plugins to use the tasks defined in them. See
apply pluginreference. - The maven repository is referenced to download the libraries with which there are dependencies to compile and run. See
repositoriesanddependenciesreference. - Then, dynamically it’s defined for each SourceSet a
jarassemblytask. In the 25 line, we define 2 tasks, calledapiJarandimplJarthat both are Jar type and what they do is to assemble the jar with the classes contained for the SourceSets. - In the line 35 we define the new
SourceSets, api and impl, that are contained in the src folder, in next steps we see how to set a custom location. - The
Jarmethod in line 40 set the sources that are assembled in the Jar, in this case get all sources from api and impl SourceSets. If we take a look at line 27, for apiJar and implJar tasks, those only has api sources or impl sources but no both, so if them have dependency will occurs compilation or runtime errors using the Jar. - Last method
uploadArchiveswill deploy this jar file to a remote Maven repository. For this example we can delete this.
6. SourceSet’s Properties
Foremost we will add a task to see all the properties of SourceSets, please add it to the end of the script.
task sourceSetProperties << {
sourceSets {
main {
println "java.srcDirs = ${java.srcDirs}"
println "resources.srcDirs = ${resources.srcDirs}"
println "java.files = ${java.files.name}"
println "allJava.files = ${allJava.files.name}"
println "resources.files = ${resources.files.name}"
println "allSource.files = ${allSource.files.name}"
println "output.classesDir = ${output.classesDir}"
println "output.resourcesDir = ${output.resourcesDir}"
println "output.files = ${output.files}"
}
}
}
In this tasks we point to the main SourceSet that’s set by default. So, then run the task with the command gradle sSP (brief invocation) and will see this output:
C:\Users\Andres\workspaceLuna\GradleSourceSetProject>gradle sSP :sourceSetProperties java.srcDirs = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\main\ja va] resources.srcDirs = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\ma in\resources] java.files = [] allJava.files = [] resources.files = [] allSource.files = [] output.classesDir = C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\c lasses\main output.resourcesDir = C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build \resources\main output.files = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\class es\main, C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\resources\ma in] BUILD SUCCESSFUL Total time: 1.169 secs
The result is, all ‘files properties’ are empty because the directories point to the default values src/main/java. So to make this properties works we can set this task to impl or api SourceSets, or also we can set any as the main SourceSet. If we change main for impl in 3rd line and run again the task we will see this output.
C:\Users\Andres\workspaceLuna\GradleSourceSetProject>gradle sSP :sourceSetProperties java.srcDirs = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\impl\ja va] resources.srcDirs = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\im pl\resources] java.files = [DoublerImpl.java] allJava.files = [DoublerImpl.java] resources.files = [] allSource.files = [DoublerImpl.java] output.classesDir = C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\c lasses\impl output.resourcesDir = C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build \resources\impl output.files = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\class es\impl, C:\Users\Andres\workspaceLuna\GradleSourceSetProject\build\resources\im pl] BUILD SUCCESSFUL Total time: 1.265 secs
Gradle this time whether found java files.
Another strategy is to set the main SourceSet point to src’s root. adding this configuration to SourceSets task. So if we run again the gradle sSP command will see all Java sources without test clasess. This is how we customize the SourceSet directory.
sourceSets {
api
impl
main{
java {
srcDir 'src/api/java'
srcDir 'src/impl/java'
}
}
test {
java {
srcDir 'src/test/java'
}
}
}
java.srcDirs = [C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\main\ja va, C:\Users\Andres\workspaceLuna\GradleSourceSetProject\src\api\java, C:\Users\ Andres\workspaceLuna\GradleSourceSetProject\src\impl\java] java.files = [Doubler.java, DoublerImpl.java] allJava.files = [Doubler.java, DoublerImpl.java] resources.files = [] allSource.files = [Doubler.java, DoublerImpl.java]
We have 3 directories for the main SourceSet, and both classes are contained.
7. Assembling SourceSets in JAR Files
So if we want to package the output classes in a new JAR file, it’s simple we must define a task of Jar type and set a key sentence from sourceSet.output. In previous steps we already define them, look at 25 line or Jar configuration in line 40. So if we run the inital dinamic tasks gradle apiJar and gradle implJar, Gradle will generate a JAR with the output sources in the directories defined for the task.
C:\Users\Andres\workspaceLuna\GradleSourceSetProject>gradle apiJar :compileApiJava UP-TO-DATE :processApiResources UP-TO-DATE :apiClasses UP-TO-DATE :apiJar UP-TO-DATE BUILD SUCCESSFUL Total time: 0.997 secs
Gradle automatically will create 3 new tasks based on any new SourceSet added to the project, apiClasses, compileApiJava, and processApiResources for this case, but in other case change api for sourceset’s name. These tasks have a dependency between them, so what they do in 3 steps is to compile the java files, process resources and assemble the jar copying all the files to it, keeping the project structure.
Then, we assemble the three possible Jar files, so:
gradle apiJar, only contains api output sourcesgradle impJar, only contains api output sources.gradle Jar, contains all output project sources.
So refresh the project and take a look in the build/libs directory.
8. Creating SourceSet Documentation
So if we want to generate the Javadoc documentation, we must use the javadoc task. This tasks seeks by default the main SourceSet, but with the property sourceSets.<sourceSet>.allJava we can add another custom SourceSet. Next, add this task to the build script and we can run the command gradle javadoc; the generated documentation is allocated into build/docs/javadoc.
javadoc {
// but the main sourceset contains both api & impl sourceset, javadoc will generate all documentation
source sourceSets.api.allJava
}
C:\Users\Andres\workspaceLuna\GradleSourceSetProject>gradle javadoc :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :javadoc UP-TO-DATE BUILD SUCCESSFUL Total time: 1.321 secs
9. Testing
So for run the Unit test classes contained in the test SourceSet, we need to add this configuration to the test Task to view the result of execution.
test {
// Print in console the result of test
afterTest { test, result ->
println "Executing test ${test.name} [${test.className}] with result: ${result.resultType}"
}
}
We run the task, gradle test and get this output:
C:\Users\Andres\workspaceLuna\GradleSourceSetProject>gradle test :compileApiJava UP-TO-DATE :processApiResources UP-TO-DATE :apiClasses UP-TO-DATE :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :compileImplJava UP-TO-DATE :processImplResources UP-TO-DATE :implClasses UP-TO-DATE :compileTestJava UP-TO-DATE :processTestResources UP-TO-DATE :testClasses UP-TO-DATE :test Executing test testIt [doubler.impl.DoublerImplTest] with result: SUCCESS BUILD SUCCESSFUL Total time: 1.596 secs
10. Final Build.Gradle SourceSet Script
This is the final version of the script.
/*
* Author: Andres Cespedes
* Date: 01 May 2015
* Example: Gradle SourceSets Example
* Site: www.javacodegeeks.com
* */
apply plugin: "java"
//Script Version
version = 1.0
//Java version compatibility to use when compiling Java source.
sourceCompatibility = 1.7
//Java version to generate classes for.
targetCompatibility = 1.7
//repository where to fetch third party libraries and dependencies
repositories { mavenCentral() }
//Set a Jar task to all of SourceSets.
sourceSets.all { set ->
def jarTask = task("${set.name}Jar", type: Jar) {
baseName = baseName + "-$set.name"
from set.output
}
artifacts { archives jarTask }
}
//Print Main Sourceset Properties
task sourceSetProperties << {
sourceSets {
main {
println "java.srcDirs = ${java.srcDirs}"
println "resources.srcDirs = ${resources.srcDirs}"
println "java.files = ${java.files.name}"
println "allJava.files = ${allJava.files.name}"
println "resources.files = ${resources.files.name}"
println "allSource.files = ${allSource.files.name}"
println "output.classesDir = ${output.classesDir}"
println "output.resourcesDir = ${output.resourcesDir}"
println "output.files = ${output.files}"
}
}
}
// SourceSet's Configuration
sourceSets {
api
impl
main{
java {
srcDir 'src/api/java'
srcDir 'src/impl/java'
}
}
test {
java { srcDir 'src/test/java' }
}
}
// Compile, Test and Run dependencies
dependencies {
apiCompile 'commons-codec:commons-codec:1.5'
implCompile sourceSets.api.output
implCompile 'commons-lang:commons-lang:2.6'
testCompile 'junit:junit:4.9'
testCompile sourceSets.api.output
testCompile sourceSets.impl.output
runtime configurations.apiRuntime
runtime configurations.implRuntime
}
// JAR Task Configuration, define output the directories that make up the file.
jar {
from sourceSets.api.output
from sourceSets.impl.output
}
javadoc {
// but the main sourceset contains both api & impl sourceset, javadoc will generate all documentation
source sourceSets.api.allJava
}
test {
// Print in console the result of test
afterTest { test, result ->
println "Executing test ${test.name} [${test.className}] with result: ${result.resultType}"
}
}
11.Key Points
Tips
- The Gradle SourceSet’s Properties are made to access to the directories and files that make up the SourceSet.
- Java plugin give us a lot of basic funcionalities to improves the development process.
- Gradle have a lot of default values, you need to set the custom values that adjust to your project
- Every task have so many properties, that can be useful to your needs but to mantain the article more readable we don’t mention it here
- Gradle SourceSet concept, is an excellent tool to build a clean structure into your project and make software’s components, atomic pieces that you can manage and assemble.
12. Download the Eclipse Project
You can download the full source code of this example here Gradle SourceSet Project
