This plugin will scan and adapt your source files to include a provided header, e.g. a LICENSE file. By default it will scan every source set and report warnings. It will also create format tasks, which will properly format and apply the specified header. A bulk of the logic comes from the maven-license-plugin.
This plugin will also report on the licenses of your dependencies.
From v0.11.0 onwards the license-gradle-plugin will be published to http://bintray.com and will be available through the http://plugins.gradle.org/[Gradle plugin exchange]. This means that there are a few different usage scenarios listed below.
In your build.gradle file add:
plugins {
id "com.github.hierynomus.license" version "0.11.0"
}
In your build.gradle file add:
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'nl.javadude.gradle.plugins:license-gradle-plugin:0.11.0'
}
}
apply plugin: 'license'
In your build.gradle file add:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'nl.javadude.gradle.plugins:license-gradle-plugin:0.10.0'
}
}
apply plugin: 'license'
This will add two types of tasks for each source set (created by BasePlugin) in your project: one for checking for consistency and one to apply the header, e.g.
- licenseMain : checks for header consistency in the main source set
- licenseFormatMain : applies the license found in the header file in files missing the header
- licenseTest : checks for header consistency in the test source set
The check tasks are added to the standard Gradle check task.
This will also add a task to manage the downloading and reporting of licenses of your dependencies.
- downloadLicenses : generates reports on your runtime dependencies
The license task has a properties, most can be set in the extension:
- header -- Specify location of header to use in comparisons, default to project.file('LICENSE')
- headerURI -- Specify location of header as a URI, see section below on Header Locations for examples
- ignoreFailures -- Prevent tasks from stopping the build, defaults to false
- dryRun -- Show what would happen if the task was run, defaults to false but also inherits from --dryRun
- skipExistingHeaders -- Skip over files that have some header already, which might not be the one specified in the header parameter, defaults to false
- useDefaultMappings -- Use a long list of standard mapping, defaults to true. See http://code.mycila.com/license-maven-plugin/#supported-comment-types for the complete list
- strictCheck -- Be extra strict in the formatting of existing headers, defaults to false
- sourceSets -- List of sourceSets to create tasks for, will default to all sourceSets created by Java Plugin
- mapping(String ext, String style) -- Adds a mapping between a file extension and a style type
- mapping(Map<String,String> mappings) -- Adds mappings between file extensions and style types
- mapping(Closure) -- Adds mappings between file extensions and a style types, see example below
A license extension is added to the project, which can be used to configure all license tasks. E.g.
license {
header rootProject.file('codequality/HEADER')
strictCheck true
}
Here is a general overview of the options:
- header -- Specify location of header to use in comparisons, default to project.file('LICENSE')
- headerURI -- Specify location of header as a URI.
- ignoreFailures -- Prevent tasks from stopping the build, defaults to false
- dryRun -- Show what would happen if the task was run, defaults to false but also inherits from --dryRun
- skipExistingHeaders -- Skip over files that have some header already, which might not be the one specified in the header parameter, defaults to false
- useDefaultMappings -- Use a long list of standard mapping, defaults to true. See http://code.mycila.com/license-maven-plugin/#supported-comment-types for the complete list
- strictCheck -- Be extra strict in the formatting of existing headers, defaults to false
- sourceSets -- List of sourceSets to create tasks for, will default to all sourceSets created by Java Plugin
- mapping(String ext, String style) -- Adds a mapping between a file extension and a style type
- mapping(Map<String,String> mappings) -- Adds mappings between file extensions and style types
- mapping(Closure) -- Adds mappings between file extensions and a style types, see example below
- exclude(String pattern) -- Add an ANT style pattern to exclude files from license absence reporting and license application
- excludes(Collection patterns) -- Add ANT style patterns to exclude files from license absence reporting and license application
- include(String pattern) -- Add an ANT style pattern to include files into license absence reporting and license application
- includes(Collection patterns) -- Add ANT style patterns to include files into license absence reporting and license application
The plugin can load a reference license file from the local file system with the header property.
license { header = file('LGPL.txt') }
To load a license from a URI directly it can be headerURI property.
license { headerURI = new URI("https://www.gnu.org/licenses/lgpl.txt") }
The problem with that approach is that we're requiring a network call to run the task. Another option is to load the license from the classpath. This is most commonly seen from a plugin which is configuring this plugin. First you'd bundle a LICENSE.TXT file into the src/main/resources/META-INF directory. Then you'd configure this plugin like the below code.
license { headerURI = myPlugin.class.getResource("/META-INF/LICENSE.TXT").toURI() }
In regards to the header, tasks can be configured individually or in bulk also,
licenseFormatMain.header = file('APL.txt')
// or
tasks.withType(License) { header = file('LGPL.txt') }
Supported by default: java, groovy, js, css, xml, dtd, xsd, html, htm, xsl, fml, apt, properties, sh, txt, bat, cmd, sql, jsp, ftl, xhtml, vm, jspx, gsp, json. Complete list can be found in the parent project at http://code.mycila.com/license-maven-plugin/#supported-comment-types.
An extensive list of formats and mappings are available by default, see the SupportedFormats link above. Occasionally a project might need to add a mapping to a unknown file type to an existing comment style.
license {
mapping {
javascript='JAVADOC_STYLE'
}
}
// or
license.mapping 'javascript' 'JAVADOC_STYLE'
// or
license.mapping('javascript', 'JAVADOC_STYLE')
// or directly on the task
licenseMain.mapping 'javascript' 'JAVADOC_STYLE'
Defining new comment types is not currently supported, but file a bug and it can be added.
Variables in the format ${} format will be substituted, as long as they're values are provided in the extension or the task.
Copyright (C) ${year} ${name} <${email}>
Will be completed with this extension block, the key is adding them via extra properties:
license {
ext.year = Calendar.getInstance().get(Calendar.YEAR)
ext.name = 'Company'
ext.email = 'support@company.com'
}
// or
licenseMain.ext.year = 2012
By default all files in the sourceSets configured are required to carry a license. Just like with Gradle SourceSet you can use include/exclude patterns to control this behaviour.
The semantics are:
- no
includesorexcludes: All files in the sourceSets will be included excludesprovided: All files except those matching the exclude patterns are includedincludesprovided: Only the files matching the include patterns are included- both
includesandexcludesprovided: All files matching the include patterns, except those matching the exclude patterns are included.
For instance:
license {
exclude "**/*.properties"
excludes(["**/*.txt", "**/*.conf"])
}
This will exclude all *.properties, *.txt and *.conf files.
license {
include "**/*.groovy"
includes(["**/*.java", "**/*.properties"])
}
This will include only all *.groovy, *.java and *.properties files.
license {
include "**/*.java"
exclude "**/*Test.java"
}
This will include all *.java files, except the *Test.java files.
By default, applying the plugin will generate license tasks for all source sets defined by the java plugin. You can also run the license task on an arbitrary file tree, if you don't have the java plugin, or your files are outside a java source tree.
task licenseFormatSql (type:nl.javadude.gradle.plugins.license.License) {
source = fileTree(dir:"source").include ("**/*.sql")
}
licenseFormat.dependsOn licenseFormatSql
The downloadLicense task has a set of properties, most can be set in the extension:
- includeProjectDependencies -- true if you want to include the transitive dependencies of your project dependencies
- licenses -- a pre-defined mapping of a dependency to a license; useful if the external repositories do not have license information available
- aliases -- a mapping between licenses; useful to consolidate the various POM definitions of different spelled/named licenses
- excludeDependencies -- a List of dependencies that are to be excluded from reporting
- dependencyConfiguration -- Gradle dependency configuration to report on (defaults to "runtime").
A 'license()' method is made available by the License Extension that takes two Strings, the first is the license name, the second is the URL to the license.
downloadLicenses {
ext.apacheTwo = license('Apache License, Version 2.0', 'http://opensource.org/licenses/Apache-2.0')
ext.bsd = license('BSD License', 'http://www.opensource.org/licenses/bsd-license.php')
includeProjectDependencies = true
licenses = [
(group('com.myproject.foo')) : license('My Company License'),
'org.apache.james:apache-mime4j:0.6' : apacheTwo,
'org.some-bsd:project:1.0' : bsd
]
aliases = [
(apacheTwo) : ['The Apache Software License, Version 2.0', 'Apache 2', 'Apache License Version 2.0', 'Apache License, Version 2.0', 'Apache License 2.0', license('Apache License', 'http://www.apache.org/licenses/LICENSE-2.0')],
(bsd) : ['BSD', license('New BSD License', 'http://www.opensource.org/licenses/bsd-license.php')]
]
excludeDependencies = [
'com.some-other-project.bar:foobar:1.0'
]
dependencyConfiguration = 'compile'
}