Base plugins for Gradle projects and plugins developed by FIDATA

Clone this repo:
  1. 996634f style: clean up comments in code by Basil Peace · 4 years, 1 month ago master
  2. d84fd5d style: remove unnecessary code nesting by Basil Peace · 4 years, 1 month ago
  3. 6bc83e4 chore: update IDEA files by Basil Peace · 4 years, 1 month ago
  4. a8b23d0 perf: configure more Gradle things lazily by Basil Peace · 4 years, 1 month ago
  5. f1a18c7 test: fix VersionUtilsTest not reporting failure by Basil Peace · 4 years, 1 month ago

gradle-base-plugins

Plugins to configure Gradle to build projects (including other Gradle pluging) developed by FIDATA. They provide reasonable defaults and sane environment for all our projects.

These plugins are highly opinionated and for internal use only. They are not to be published to Maven Central or Gradle Plugins portal. However, you are free to fork, modify or use it as an example according to Apache v2.0 license.

If you are contributing to other FIDATA plugins the best choice is to join FIDATA organization and use all available infrastructure including our Artifactory repository where these plugins live.

org.fidata.project plugin

General, language-agnostic project.

Lifecycle

Basic build lifecycle is assemblecheckrelease.

assemble, check and, also, clean tasks are provided by applied lifecycle-base plugin.

release task is provided by applied de.gliderpilot.semantic-release plugin.

Prerequisites Lifecycle

Dependency Resolution

  • Adds Maven repository hosted on FIDATA Artifactory

    For releases, it is always -release repository, so releases cannot have snapshot dependencies. Otherwise it is -snapshot repository, so snapshot versions could be used during development (but won't by default - see below).

  • Turns off changing modules caching, so that SNAPSHOT dependencies are updated on each run

  • Configures dependency resolution changing Ivy status from release to milestone for artifacts having pre-release labels in version

  • Adds property status to each ExternalModuleDependency instance. It should be used to configure desired status of dependency. By default all dependencies are resolved to releases, even if you use version ranges. If you want to get bleeding edge SNAPSHOT version you could use this property, like this:

    dependencies {
      compile('com.example:next-generation-library:[1, 2[').status = 'integration'
    }
    

    Of course, if there is more recent release with appropriate version then it will be used instead of old SNAPSHOT.

    Custom status schemes are not supported.

Documentation

Code Quality

  • Provides lint task

    check task depends on all Test tasks and new lint task.

  • Applies codenarc plugin

  • Provides codenarc and pmd tasks that run all PMD and CodeNarc tasks respectively.

    Includes these tasks in execution list for lint task.

  • Provides codenarcBuildSrc task for build.gradle itself and accompanying Groovy scripts

  • Sets default configuration for all codenarc tasks

    Adds disabledRules property to each task, so that specific rules could be disabled per task.

Artifacts Publishing

  • Applies signing plugin

    By default, Java-based implementation of PGP is used. Secret keyring should be placed at GnuPG home in secring.gpg file.

    If you want to use GnuPG for signing, properties for this are already set. Switch can be made with signing.useGpgCmd() .

  • Provides read-only isRelease and changeLog project properties for working with semantic release

  • Provides publicReleases project property used by other plugins

    Setting it to true turns on all public-release tasks: publishing artifacts to Maven Central, JCenter and so on.

    By default it is false.

Reports

  • Provides read-only project properties:

    • reportsDir
    • htmlReportsDir
    • xmlReportsDir
    • jsonReportsDir
    • txtReportsDir
  • Applies and configures reporting-base plugin

    Redirects all reports to build/reports/<format> directory.

    Known limitation: gradle --profile reports are not redirected. They stay in build/reports/profile directory for now. See https://github.com/FIDATA/gradle-base-plugins/issues/1

Build Diagnostics and Troubleshooting

  • Applies plugins:

  • Provides inputsOutputs task which generates reports about all task file inputs and outputs

All these tasks are put into Diagnostics group.

Other features

  • Applies and configures com.jfrog.artifactory plugin

    Allows us to publish artifacts and build info to FIDATA Artifactory .

  • Sets project's group to org.fidata if it hasn't been set already

  • Provides license property used by other plugins

    It should be set with SPDX license identifier .

  • Provides generateChangelog and generateChangelogTxt tasks that generate changelog in Markdown and text formats in build/changelog directory

    The main usage is to check generated changelog during release preparation to make sure that everything is correct.

  • Provides tags property used by other plugins

  • Applies nebula.contacts plugin

    Provides contacts extension.

buildSrc projects

Plugin can be applied to buildSrc projects. However, buildSrc projects can't have releases and documentation, so all related features are turned off. They also don't publish build info to Artifactory.

They could have code quality and diagnostic tasks, but usage of them is discouraged. Note that all buildSrc's Gradle and Groovy scripts are already covered by codenarcBuildSrc task.

Project gets isBuildSrc read-only property which will be set to true when buildSrc project is detected.

Supported tools versions:

  • Requires Gradle >= 4.10

  • Built and tested with JDK 8

  • Requires GnuPG >= 2.1

    gpg-agent should have allow-preset-passphrase option turned on if GPG key with passphrase is used. It is usually achieved by adding this string into gpg-agent.conf file in GPG home directory.

org.fidata.base.jvm plugin

Project which uses JVM-based language. This plugin should not be applied manually.

Applies org.fidata.project plugin, and also:

  • Applies java-base and java-library plugins

  • Provides jvm extension. This extension has one property javadocLinks.

    It contains links to external documentation used by javadoc and groovydoc. If a dependency is added automatically, its documentation is also added here automatically. Otherwise, you add link manually, like this:

    jvm.javadocLinks['com.example.super.cool.external.library'] = uri('https://example.com/javadoc/com/example/super.cool.external.library/1.0/')
    
  • Adds mavenJava publication (except when org.fidata.plugin is applied)

Testing

  • Adds JUnit dependency to testImplementation configuration

  • Adds and configures functionalTest source set and task which uses Spock framework

    Also adds Spock Reports.

    JUnit is also available whenever Spock is.

Artifact Publishing

  • Applies maven-publish plugin

    Configures Maven publication to Artifactory.

    Your settings.gradle should contain this row:

    enableFeaturePreview('STABLE_PUBLISHING')
    

    to prevent the following error:

    org.gradle.api.InvalidUserDataException: Cannot configure the 'publishing' extension after it has been accessed.
    

    If publicReleases is on — configures publication to Maven Central.

  • If publicReleases is on — applies com.jfrog.bintray plugin and configures publication to JCenter

Code Quality

  • Provides findbugs and jdepend tasks that run all FindBugs and JDepend tasks respectively.

    Includes these tasks in execution list for lint task.

Other features

  • Adds license file(s) into JAR META-INF directory

org.fidata.project.java plugin

Java language project.

Applies org.fidata.base.jvm plugin, and also:

  • Applies java plugin

  • Applies io.franzbecker.gradle-lombok plugin providing Lombok for Java sources

  • Configures javadoc to parse sources through Delombok first

  • Adds javadoc output to GitHub Pages publication

  • Provides checkstyle task that run all Checkstyle tasks.

    Includes this task in execution list for lint task.

org.fidata.base.groovy plugin

Project which uses Groovy language. This plugin should not be applied manually.

Applies org.fidata.base.jvm plugin, and also:

org.fidata.project.groovy plugin

Groovy language project.

Applies org.fidata.base.groovy plugin, and also:

  • Applies groovy plugin

  • Adds local Groovy to api configuration

  • Adds groovydoc output to GitHub Pages publication

org.fidata.plugin plugin

Gradle plugin project.

This plugin depends on at least one of JVM-based project plugins:

or others developed later.

They have to be applied manually depending on the language(s) used in the project.

Properties

Should be provided in standard Gradle ways .

All properties except gpgKeyPassphrase are required. The plugin won't work if they are not set.

Multi-project Builds (a.k.a Monorepo)

These plugins supports multi-project builds in the following configuration:

  1. All child projects have the same version as the root one. This is the limitation imposed by de.gliderpilot.semantic-release plugin.

  2. org.fidata.project should be applied to root. It applies itself to each subproject

  3. de.gliderpilot.semantic-release and org.ajoberstar.git-publish plugins are applied to root only.

  4. The following properties are available for root project only:

    • isBuildSrc
    • isRelease
    • changeLog
    • changeLogTxt
    • issuesUrl
    • vcsUrl

    Except these, all other is configurable per project.

    Note that subprojects can have different licenses, and license file(s) (being included in JARs) are per project.

  5. Reports for all subprojects are redirected to build/reports/<format>/<subproject> directory. This is made for convenient usage under CI (Jenkins)

Development

This is self-applying plugin. That means that build script requires the plugin itself (just compiled, not released to the repository). So, if there are any errors during compilation or plugin applying, Gradle build script just doesn't work. If it is a compilation error, you can run ../gradlew build in buildSrc directory to figure out what's going on.

Upgrading Gradle Version

Whenever new Gradle version is released, the way to upgrade is this:

  1. Read Release Notes and make necessary changes to the code
  2. Run ./gradlew stutterWriteLock
  3. Run ./gradlew compatTest<new Gradle version>
  4. Change Gradle version for wrapper task in plugin code
  5. Run ./gradlew wrapper && ./gradlew wrapper

If a new version of a plugin won't be compatible with previous Gradle versions:

  1. Update ProjectPlugin.GRADLE_MINIMUM_SUPPORTED_VERSION value
  2. Run ./gradlew stutterWriteLock
  3. Update required Gradle version in this README file

Copyright © 2017-2018 Basil Peace

This file is part of gradle-base-plugins.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.