Gradle Java-lib plugin

About

Plugin applies common configuration for java or groovy library:

• Configure jar with default manifest and put pom.xml and pom.properties inside jar (like maven do)
• Add sourcesJar task
• Add javadocJar or (and) groovydocJar tasks
• Configures maven publication named maven with all jars (jar, sources javadock or (and) groovydoc)
• Add install task as shortcut for publishToMavenLocal
• Applies pom plugin which:
  • Fix dependencies scopes in generated pom
  • Add pom configuration closure to simplify pom definition.
  • Add withPomXml configuration closure to use if you need manual xml configuration
  • Adds optional and provided configurations (affect only resulted pom)

If you need multiple publications from the same project, then you will have to perform additional configuration or, maybe (depends on case), use only pom plugin.

Confusion point: plugin named almost the same as gradle's own java-library plugin, but plugins do different things (gradle plugin only provides api and impl configurations) and could be used together.

Setup

Releases are published to bintray jcenter, maven central and gradle plugins portal.

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-java-lib-plugin:1.0.5'
    }
}
apply plugin: 'ru.vyarus.java-lib'

OR

plugins {
    id 'ru.vyarus.java-lib' version '1.0.5'
}

Plugin must be applied after java or groovy or java-library plugins. Otherwise it will do nothing.

Usage

General

You need to specify general info:

group = 'your.group'                    // maven group
version = '1.0.0'                       // project version
description = 'My project description'  // optional (affects jar manifest) 

You may use optional and provided dependencies (if java-library plugin not used):

dependencies {    
    provided 'com.foo:dep-provided:1.0'
    optional 'com.foo:dep-optional:1.0'        
}

Tasks

• sourcesJar task is always applied
• javadocJar if java sources directory present ('src/main/java')
• groovydocJar if groovy plugin available and groovy sources present ('src/main/groovy'). Last condition is important because groovy may be used only for tests.

IMPORTANT: if you have only groovy sources then groovydocJar will have javadoc` classifier! This is because maven central requires javadoc jar, so even if you write groovy project you have to name it javadoc.

In case of both groovy and java sources, groovydocJar will use groovydoc classifier, because javadocJar already use javadoc and have to produce separate artifacts.

Pom

Most likely, you will need to configure pom:

pom {
    name 'Project Name'
    description 'My awesome project'
    licenses {
        license {
            name "The MIT License"
            url "http://www.opensource.org/licenses/MIT"
            distribution 'repo'
        }
    }
    scm {
        url 'https://github.com/me/my-repo.git'
        connection 'scm:git@github.com:me/my-repo.git'
        developerConnection 'scm:git@github.com:me/my-repo.git'
    }
    developers {
        developer {
            id "dev1"
            name "Dev1 Name"
            email "dev1@email.com"
        }
    }
}

Read more about pom specifics in pom plugin description.

Main Jar

Plugin applies default manifest properties:

'Implementation-Title': project.description ?: project.name,
'Implementation-Version': project.version,
'Built-By': System.getProperty('user.name'),
'Built-Date': new Date(),
'Built-JDK': System.getProperty('java.version'),
'Built-Gradle': gradle.gradleVersion,
'Target-JDK': project.targetCompatibility

You can override it:

jar {
    manifest {
        attributes 'Implementation-Title': 'My Custom value',
            'Built-By': 'Me',
    }
}

For all not specified properties default values will be used.

Plugin will include additional files inside jar (like maven do) into META-INF/maven/group/artifact/

• pom.xml
• pom.properties

pom.properties contains:

• version
• groupId
• artifactId

Publication

maven-publish plugin is used for publication.

By default plugin configures maven publication with javadoc or (and) groovydoc and sources jars.

Use 'install' task to deploy jars into local maven repository.

$ gradlew install

If you dont want to publish everything (jar, sources, javadoc) then you can override list of publishing artifacts:

publishing.publications.maven.artifacts = [jar, javadocJar]

Here sources are excluded from publishing.

Publish to repository

For actual publication only repository must be configured:

publishing {
    repositories {
        maven {
            // change to point to your repo, e.g. http://my.org/repo
            url "$buildDir/repo"
        }
    }
}

Then publish task may be used to perform publish.

Publish to bintray

If you publish to bintray, then you need to reference maven publication in bintray plugin configuration:

bintray {    
    publications = ['maven']
    ...
}    

Complete usage example

plugins {
    id 'java'
    id 'ru.vyarus.java-lib' version '1.0.4'
    id 'com.jfrog.bintray' version '1.7.1'
}

group = 'com.sample' 
version = '1.0.0'
description = 'Sample project'

sourceCompatibility = 1.6

repositories { jcenter() }
dependencies {    
    provided 'com.foo:dep-provided:1.0'
    compile 'com.foo:dep-compile:1.0'        
}

pom {
    name 'Project Name'
    description 'My awesome project'
    licenses {
        license {
            name "The MIT License"
            url "http://www.opensource.org/licenses/MIT"
            distribution 'repo'
        }
    }
    scm {
        url 'https://github.com/me/my-repo.git'
        connection 'scm:git@github.com:me/my-repo.git'
        developerConnection 'scm:git@github.com:me/my-repo.git'
    }
    developers {
        developer {
            id "dev1"
            name "Dev1 Name"
            email "dev1@email.com"
        }
    }
}

bintray {    
    publications = ['maven']
    ...
}  

Boilerplate plugin removes

Just for reference, here is what plugin did for java project:

apply plugin: 'ru.vyarus.pom'

jar {    
    manifest {
        attributes 'Implementation-Title': project.description ?: project.name,
                'Implementation-Version': project.version,
                'Built-By': System.getProperty('user.name'),
                'Built-Date': new Date(),
                'Built-JDK': System.getProperty('java.version'),
                'Built-Gradle': gradle.gradleVersion,
                'Target-JDK': project.targetCompatibility
    }
}

task generatePomPropertiesFile {
    inputs.properties ([
            'version': "${ -> project.version }",
            'groupId': "${ -> project.group }",
            'artifactId': "${ -> project.name }"
    ])
    outputs.file "$project.buildDir/generatePomPropertiesFile/pom.properties"
    doLast {
        File file = outputs.files.singleFile
        file.parentFile.mkdirs()
        file << inputs.properties.collect{ key, value -> "$key: $value" }.join('\n')
    }
}

model {
    tasks.jar {
        into("META-INF/maven/$project.group/$project.name") {
            from generatePomFileForMavenPublication
            rename ".*.xml", "pom.xml"
            from generatePomPropertiesFile
        }
    }
}

task sourcesJar(type: Jar, dependsOn: classes, group: 'build') {
	from sourceSets.main.allSource
	classifier = 'sources'
}

task javadocJar(type: Jar, dependsOn: javadoc, group: 'build') {
	classifier 'javadoc'
    from javadoc.destinationDir
}

task groovydocJar(type: Jar, dependsOn: groovydoc, group: 'build') {
	classifier 'groovydoc'
    from groovydoc.destinationDir
}

publishing {
	publications {
	    maven(MavenPublication) {
	        from components.java
	        artifact sourcesJar	        
	        artifact javadocJar
	        artifact groovydocJar	 
	    }
	}
}

task install(dependsOn: publishToMavenLocal, group: 'publishing') << {
	logger.warn "INSTALLED $project.group:$project.name:$project.version"
}

Might also like

• quality-plugin - java and groovy source quality checks
• github-info-plugin - pre-configure common plugins with github related info
• animalsniffer-plugin - java compatibility checks
• java-library generator - java library project generator

---