BuildSupportPlugin 0.7.2 API

This document is primarily aimed at build engineers (developers that create and modify the build scripts for a project). However, it contains useful material for any developer that builds a project that uses this plugin and it defines a set of nomenclature around versioning and project release processes that we should all understand. If you are new to gradle, please review the Welcome to Gradle confluence page.

The general semantics of this plugin are controlled by the presence of 2 files:

• raptorVersion.txt
• projectVersion.txt

The projectVersion.txt file, if present, controls the version of the project/plugin being built, and identifies the build as a "project/plugin build" which alters the way this plugin prepares the version information. There are two basic types of builds supported by this plugin: snapshot and release

If only the raptorVersion.txt file exists, then that is the controlling version file. If the projectVersion.txt file exists, then it is the controlling version file. The version used within the build is determined from the controlling version file. That version (along with any stage supplied by the snapshot or release build type, described more fully below) will be applied to any artifacts created by the build. The term root version refers to the tri-part numeric version without any stage. For example, given a version string of 2.17.2-RC2, the root version is 2.17.2.

There is one special case, used in the RaptorPlugins project, to ease the burden of managing these two files to always have the same version. In this case, the project defines the ext property raptorVersionTracksProjectVersion before applying thus plugin. Given that, only the projectVersion.txt file is processed and the raptorVersion.txt file doesn't even exists. Further, the raptorVersion ext property is set equal to projectVersion.

The BuildSupport plugin provides a class, RaptorVersion that offers easy access to the various parts of a version string (major, minor, patch, and stage components). An instance of this class is created on each version file found, and those instances are available in the root project's ext configuration as raptorVersion and projectVersion. Additional properties are created, see Project Properties Created for a complete list. If you're unfamiliar with gradle projects and the ext properties extension, try this search.

The code below shows some example uses of RaptorVersion and the values the various methods return.

    // Assume a plugin build (both raptorVersion.txt and projectVersion.txt exist) and those files have
    // been read by this plugin, yielding variables raptorVersion and projectVersion
    //
    // The content of raptorVersion.txt  was '2.17.1-RC2'
    // The content of projectVersion.txt was '1.2.3-API1'  (yes, the 'stage' can be any string we want)

    raptorVersion.toString() == '2.17.1-RC2'
    raptorVersion.major == 2   // Note these are integer values
    raptorVersion.minor == 17
    raptorVersion.patch == 1
    raptorVersion.stage == 'RC2'
    raptorVersion.rootVersion == '2.17.1'
    raptorVersion.majorMinor == '2.17'
    raptorVersion.asSnapshot() == '2.17.1-SNAPSHOT'

    projectVersion.toString() == '1.2.3-API1'
    projectVersion.major == 1
    projectVersion.minor == 2
    projectVersion.patch == 3
    projectVersion.stage == 'API1'
    projectVersion.rootVersion == '1.2.3'
    projectVersion.majorMinor == '1.2'
    projectVersion.asSnapshot() == '1.2.3-SNAPSHOT'

Snapshot build version handling

Release build version handling

Performing Release Builds

1. Verify that the work tree is 'clean' - i.e., git status will indicate no changes
2. The version string in the controlling version file must be updated and committed
3. The project must be built, and it must build successfully
4. The revision must be tagged (so this build revision can be easily identified in the future)
5. The artifacts must be published to Nexus (if appropriate)

    gradle build -Prelease -Prc=RC1

A release build automatically invokes the releaseClean and updateReleaseVersion tasks before 'build' and invokes tagRelease after the build, finally the artifacts are published to Nexus if configured. See the Command Line Flags section for complete details on all available flags to control the build further. See the Tasks Created section for additional details on the tasks added to the build.

One important aspect of the release build is the update to the controlling version file. Since the build will use the version string verbatim, the text in the controlling version file must be updated and committed prior to actually performing the build. This is accomplished by the updateReleaseVersion task. The major, minor, and patch version components are kept as is, but the stage is set according to the release type specified via -Pfinal or -Prc. For example, if the current version is 2.6.1-SNAPSHOT and -Prc=RC2 is specified, the version is updated to 2.6.1-RC2 (also note that this value is the build version). This change is automatically committed and pushed to the remote repo (you can control this behavior with the -Pnoexec and/or -Pnopush flags, but you should never use those unless you are performing tests on a build itself). If the version does not change, then the commit/push operations are skipped.

If the build completes successfully, The tagRelease task will invoke git to apply a tag to the current revision. The tag text will be tag-<build version>. The tag is automatically applied and pushed to the remote repo.

Finally, after all previous operations are completed successfully, any projects that are configured to publish to Nexus have the publish task invoked to perform that publication.

Restrictions on Release Builds against Raptor SNAPSHOT versions

    ==============================================================================
    ==============================================================================
    You are performing a release build against a SNAPSHOT version of Raptor!
    In general, you should NOT do this.

    If you didn't intend this, please update the 'raptorVersion.txt' file.
    You can override this warning using -PraptorSnapshot
    ==============================================================================
    ==============================================================================

If you are trying to perform a FINAL release (using -Pfinal), and the Raptor version is a SNAPSHOT version, then the build will fail with an error like this:

    You can not create a FINAL release based on a SNAPSHOT Raptor version: <version>-SNAPSHOT

How to Apply This Plugin

As of Gradle 5, the public gradle plugin portal is automatically searched for plugins, so no 'buildscript' configuration is required. Simply specify the plugin in the 'plugins' section, like this:

    plugins {
        id 'gov.raptor.gradle.plugins.build-support' version '0.6.3'
    }

    pluginManagement {
        repositories {
            gradlePluginPortal() // Include public Gradle plugin portal
            mavenLocal()
        }
    }

What if your repo doesn't use 'develop' as the root branch?

    ext.rootBranch = 'master'

How to Configure a Consuming Project

This plugin handles both single and multi-project builds, but it is up to the consuming plugin to configure the projects that are to participate in the build. For example, in a typical multi-project build, the sub-projects are the actual plugins and the root project is just a container to organize the build. So, in that case, the root project is responsible for configuring the sub-projects as needed.

To make access to the configuration methods in the plugin extension, a project property buildSupport is created and is a reference to the BuildSupportExtension , allowing for direct method invocations on it.

Configuring Repository Use

• jcenter()
• mavenLocal() *optional
• mavenCentral()

This repository configuration is automatically applied when any project or sub-project is configured as a 'java' project, which can be accomplished via buildSupport.configureStandardPlugin(Project p, boolean toNexus, boolean configureTestAgent = true) or buildSupport.setupJavaProject(Project p), see below for more details.

The repositories are hosted on 2 primary servers, DI2E and CTI, and on DI2E there are a number of repository groups in use. However, the URLs needed have standardized patterns which can be leveraged to make configuration simpler. The Build Support Extension offers a simple DSL for configuring the repositories required by a build. The style of the DSL is modeled along the lines of the existing repositories DSL. It's easiest to start with a simple example to show the salient points and then dive into the details.

    buildSupport {
        repoManagement {
            di2eCentral()
            di2eRaptorx publish: false
            di2ePrivate name: 'RP', publish: true
            di2ePrivate name: 'UNSAFE', publish: true, username: 'james', password: 'bond'
        }
    }

• DI2E Central - as a source of artifacts only (nothing ever publishes to DI2E Central)
• DI2E Raptorx - as a source of artifacts only ('publish: false' indicates not to configure publishing)
• DI2E repo named 'RP' - A private repo for artifact access and publishing
• DI2E repo named 'UNSAFE' - A private repo for artifact access and publishing, with specified credentials

    https://nexus.di2e.net/nexus/content/repositories/Private_<name>_Snaphots
    https://nexus.di2e.net/nexus/content/repositories/Private_<name>_Releases

The table below lists all the supported configuration (map) parameters for repo definitions. Note that not all repository types support all parameters (and this will be discussed below as all the definition methods are described).

The table below lists all the configuration methods available in this DSL with notes on each. Publishing is supported on all repository types unless noted otherwise.

Credentials Discovery

1. From the environment - Environment variables with specific name patterns will be used if present
2. From stored credentials - Credentials from the encrypted store with specific name patterns will be used if present
3. Script provided - Using parameters to the repo configuration methods, a build script can use any manner of credentials discovery

From the Environment

The environment is the initial location searched for credentials is the environment. This supports integration with CI servers where no access to the actual machine is permitted, and thus, the credentials encrypted store for a "user" can't be configured. The variables searched for are of the pattern:

    <name>_NEXUS_USERNAME
    <name>_NEXUS_PASSWORD

Using the configured repository name (converted to all upper case) as indicated. Since many of the repos on a given host (DI2E or CTI) will share a common set of credentials, a fallback name is also used if the primary name pattern isn't found. For DI2E, this fallback is, oddly enough, 'DI2E', and for CTI Public repos, it is 'CTI_PUBLIC'. For the Raptor repositories, the name used is always 'RAPTORX', with a fallback of 'STL'.

Expanding on the example above, if the variable RP_NEXUS_USERNAME isn't found, a fallback variable of DI2E_NEXUS_USERNAME will be used.

From the Encrypted Credentials Store

As discussed elsewhere, this plugin applies another plugin to provide encrypted storage of a users credentials on given machine. If no environment variables are found for a given repository, then the credentials store will be accessed to try and locate appropriate values. As with environment variables, standard patterns are used for the user name and password:

    <name>RepoUsername
    <name>RepoPassword

Using the configured repository name (converted to all lower case) as indicated. As with environment variables, fallback names are configured for DI2E, you guessed it, 'di2e', and CTI Public, 'public'. For di2eRaptorx, the name used is always 'di2eRaptorx', with a fallback of 'di2e'.

Script Provided

In the case where some other form of credentials management needs to be used, the script can configure the credentials for each repo using the optional username and password configuration parameters on a repository definition. For example, if environment variables are used, but they don't follow the pre-configured patterns described above, then the script could do something like the following:

    buildSupport {
        repoManagement {
            di2ePrivate name: 'Special', username: System.getenv('MY_CUSTOM_USERNAME'), password: System.getenv('MY_CUSTOM_PWD')
        }
    }

Accessing Resolved Configurations (credentials)

The repoManagement DSL also offers several methods for retrieving the repo configurations, which include the resolved credentials. This can be useful if a build script needs to access resources using those credentials, such as pushing up javadocs to Confluence.

Each of the finder methods described below return a RepoConfig object that has a method, getCredentials(), that provides properties username and password. All other methods and properties of the RepoConfig object are currently unpublished and are considered internals that may change at any time.

For example (assuming the configuration in the example above):

    def repoConfig = buildSupport.repoManagement.getDi2ePrivate('Special')
    def credentials = repoConfig.getCredentials()
    def username = credentials.username
    def password = credentials.password

Using the Build Support Extension Methods

To keep things simple, the plugin extension offers a single method that can handle the typical plugin project configuration: buildSupport.configureStandardPlugin(Project p, boolean toNexus, boolean configureTestAgent = true) And unless you have very specific, and unusual conditions in your plugin, you should use this method to configure your projects.

That method is typically applied to all sub-projects, like this:

    subprojects { subProject ->
        subProject.with {
            buildSupport.configureStandardPlugin(subProject, true) // Apply standard plugin project setup
        }
    }

    buildSupport.configurePublications(project) {
        artifact testJar
    }
            

These methods would be called from within a (sub-)project's build script as needed. For example, here's a complete sub-project build script that configures the use of java templates (which supports code generation using data available to the build, like the current version number).

    description = 'My Cool sub-project'

    ext {
        templateProperties = ['BuildDate': new Date().format('yyyy-MM-dd')]
    }

    buildSupport.configureJavaTemplates(project)

Tasks Created

Command Line Flags

Project Properties Created

The following variables are defined:

Release Notes

0.7.2 on 2020-01-21 : Add repoManagement finder methods

• Add getter methods to the RepoManagement DSL to retrieve configured repositories (to support access to resolved credentials)
• Add documentation and tests for new getter methods
• Remove long deprecated ext variables 'stlRepoUsername' and 'stlRepoPassword'
• Test failures will now fail the build when performing a release build on Jenkins
• Improve this change log with release dates

0.7.1 on 2019-12-01 : Improve support for use in Android projects

• Add `google()` as a method on `RepoManagement` to include the google repository
• Restore proper operation if no raptorVersion.txt file is present
• Add `BuildSupportExtension#publishArtifact` to configure publishing an arbitrary artifact (like an APK)

0.6.3 on 2019-11-01

• Disable the publishToMavenLocal tasks when running under jenkins or when -PnoMavenLocal is specified
• Set showStandardStreams = true in the test configuration by default
• Update docs (and bring them up to HTML5 compliance)
• add tests

0.6.2 on 2019-08-20

• Track test failures and skip publishing of artifacts if a failure occurred
• Add new ext variable, testFailureCount, to track test failures
• Don't configure mavenLocal() repo usage if running under jenkins

0.6.1 on 2019-07-17 : Update to Gradle 5; Support JDK 11/12; Fix publication handling

• Update wrapper to version 5.4.1 and update sources for Gradle 5 changes
• Update gradle-credentials-plugin to version 1.0.7
• Update gradle-jaxb-plugin to version 2.5.0
• Fix 'onlyIf' handling of publications to avoid altering custom publications created by consuming builds
• Gracefully handle publications where the target artifact is missing
• Add new configurePublications method to allow builds to easily add artifacts to the 2 managed publications

0.5.6 on 2019-06-26 : Rework creation of publications to avoid duplicate publications to the same GAV coordinates; code cleanup (future prep)

• Maintain 2 publications, one for maven local and one for all remote repos, instead of adding a separate publication for sources (resolves VOLTRON-1272)
• Cleanup code to remove all references to internal gradle classes
• Rework some test setup (which seems to break with Gradle 5)

0.5.5 on 2019-04-21

• Added support for "credential-less" access to internal CTI repos
• Added action to update the name of the document in Confluence based on version number

0.5.4 on 2019-04-17 : Added configureSourcePublication extension method

0.5.3 on 2019-02-20 : RAPTORX-452: Support '/' character in structure field names for facade generation

0.5.2 on 2018-10-19 : make 'safeTest' property check also include 'safetest'

0.5.1 on 2018-09-26

• Add new configureManifestForArchiveTask method to support configuring arbitrary Jar tasks
• Change default value for 'toNexus' on configurePublishing to be 'true'

Older