gradle-build-constants

A Gradle plugin that generates a Java source file with constants describing the build (e.g. project name, version). The plugin adds the generated source file to the Java main source set. This compiles the generated source file, which provides access to the build information constants from within a Java library or application.

Sample Generated Source File

//
// DO NOT EDIT - File generated by the org.cthing.build-constants Gradle plugin.
//

package org.cthing.test;

@SuppressWarnings("all")
public final class Constants {

    public static final String PROJECT_NAME = "testProject";
    public static final String PROJECT_VERSION = "1.2.3";
    public static final String PROJECT_GROUP = "org.cthing";
    public static final long BUILD_TIME = 1718946725000L;
    public static final String BUILD_DATE = "2024-06-21T05:12:05Z";

    private Constants() { }
}

Generated Constants

Constant	Description	Task Property	Default Value
PROJECT_NAME	Name of the Gradle project	projectName	project.getName()
PROJECT_VERSION	Version of the Gradle project	projectVersion	project.getVersion()
PROJECT_GROUP	Group name of the Gradle project	projectGroup	project.getGroup()
BUILD_TIME	Time of the build in milliseconds since the Unix Epoch	buildTime	System.currentTimeMillis
BUILD_DATE	Time of the build in ISO 8601 format	buildTime	System.currentTimeMillis

Additional user-defined constants can be specified.

Usage

The plugin is available from the Gradle Plugin Portal and can be applied to a Gradle project using the plugins block.

The plugin must be applied to the project that builds the Java library or application which requires access to the build information. For example, if the library or application is built in the root project, the plugin should be applied in the root build file. If the library or application is built in a subproject, the plugin should be applied in that subproject's build file.

To generate the constants file called MyConstants,java, configure the generateBuildConstants task:

plugins {
    java
    id("org.cthing.build-constants") version "2.0.0"
}

tasks {
    generateBuildConstants {
        classname = "org.cthing.test.MyConstants"
    }
}

By default, the generated class and constants are given public access. The plugin can be configured to generate the class and constants with package private access.

import org.cthing.gradle.plugins.buildconstants.SourceAccess

plugins {
    java
    id("org.cthing.build-constants") version "2.0.0"
}

tasks {
    generateBuildConstants {
        classname = "org.cthing.test.MyConstants"
        sourceAccess = SourceAccess.PACKAGE
    }
}

User-Defined Constants

Additional user-defined constants can be specified:

tasks {
    generateBuildConstants {
        classname = "org.cthing.test.Constants"
        additionalConstants.put("xyz", 17)
        additionalConstants.put("tuv", 2300L)
        additionalConstants.put("CUSTOM3", true)
        additionalConstants.put("CUSTOM2", "World")
        additionalConstants.put("CUSTOM1", "Hello")
        additionalConstants.put("ABC", "def")
    }
}

which will result in the generated constants file:

//
// DO NOT EDIT - File generated by the org.cthing.build-constants Gradle plugin.
//

package org.cthing.test;

@SuppressWarnings("all")
public final class Constants {

    public static final String PROJECT_NAME = "testProject";
    public static final String PROJECT_VERSION = "1.2.3";
    public static final String PROJECT_GROUP = "org.cthing";
    public static final long BUILD_TIME = 1718946725000L;
    public static final String BUILD_DATE = "2024-06-21T05:12:05Z";
    public static final String ABC = "def";
    public static final String CUSTOM1 = "Hello";
    public static final String CUSTOM2 = "World";
    public static final boolean CUSTOM3 = true;
    public static final long tuv = 2300L;
    public static final int xyz = 17;

    private Constants() { }
}

The additional constants are listed in ascending alphabetic order by name (i.e. key) after the pre-defined constants. Integer, long and boolean values are written as their respective types. All other types are written using the value of their Object#toString() method. If a value is null, the constant will not be written. The pre-defined constant names must not be used as user-defined constant names.

Output Directory

The default location for the generated constants source file is:

${project.layout.buildDirectory}/generated-src/build-constants/main`

To change the location, configure the outputDirectory property on the generateBuildConstants task.

Detecting Changes to Build Information

The plugin regenerates the constants source file when changes are detected to the following files:

• The root build file (i.e. build.gradle or build.gradle.kts)
• The root gradle.properties, if it exists
• The root gradle/libs.versions.toml, if it exists

To detect changes in other build related files, add the location of those files when configuring the generateBuildConstants task. For example:

tasks {
    generateBuildConstants {
        classname = "org.cthing.test.MyConstants"
        source(file("gradle/myscript.kts"))
    }
}

Compatibility

The following Gradle and Java versions are supported:

Plugin Version	Gradle Version	Minimum Java Version
2.0.0+	8.2+	17

Building

The plugin is compiled for Java 17. If a Java 17 toolchain is not available, one will be downloaded.

Gradle is used to build the plugin:

./gradlew build

The Javadoc for the plugin can be generated by running:

./gradlew javadoc

Releasing

This project is released on the Gradle Plugin Portal. Perform the following steps to create a release.

• Commit all changes for the release
• In the build.gradle.kts file, edit the ProjectVersion object
  • Set the version for the release. The project follows semantic versioning.
  • Set the build type to BuildType.release
• Commit the changes
• Wait until CI successfully builds the release candidate
• Verify GitHub Actions build is successful
• In a browser go to the C Thing Software Jenkins CI page
• Run the "gradle-build-constants-validate" job
• Wait until that job successfully completes
• Run the "gradle-build-constants-release" job to release the plugin to the Gradle Plugin Portal
• Wait for the plugin to be reviewed and made available by the Gradle team
• In a browser, go to the project on GitHub
• Generate a release with the tag <version>
• In the build.gradle.kts file, edit the ProjectVersion object
  • Increment the version patch number
  • Set the build type to BuildType.snapshot
• Update the CHANGELOG.md with the changes in the release and prepare for next release changes
• Update the Usage and Compatibility sections in the README.md with the latest artifact release version
• Commit these changes