Gradle Goodness: Use Command Line Options With Custom Tasks

Suppose we have a custom task with some properties that can be configured. Normally, we would add the configuration in the build script. But we can also use command line options to configure a task. So when we run the task from the command line, we can provide a configuration value for the task on the command line. To see which command line options are available for a task, we can use Gradle's built-in task help followed by the option --task and the task name. To indicate a property as a command line option, we use the @Option annotation. We can specify the name of the command line option, a short description, and also the order that is used to display the options with the help task.

Let's create a sample custom task and use the @Option annotation. In the following build file, we create a custom task GenerateVersionFile. This task generates a file with a default name of version.txt in the build/ directory. The file contains the project version value. We make the property that defines the output filename as a command line option. This way, the name can be defined when we run Gradle (and still, of course, using the default configuration in a build file).

// Import Option annotation
import org.gradle.api.internal.tasks.options.Option

version = 'demo'

// Create a task of the custom task type GenerateVersionFile.
task generateVersionFile(type: GenerateVersionFile)

/**
 * Custom task to generate a version value in a file.
 */
class GenerateVersionFile extends DefaultTask {

    String version

    // Specify outputFile property as
    // command line option.
    // Use as --outputFile filename.
    @Option(option = "outputFile",
            description = "File to store the project version in",
            order = 1)
    Object outputFile

    GenerateVersionFile() {
        // Set default value for outputFile as version.txt.
        outputFile = 'version.txt'

        // Description for the task.
        description = 'Generate a file with the project version'
    }

    @TaskAction
    void generate() {
        // Create directory for the output file if
        // it doesn't exist.
        final File versionFileDestination = getOutputFile()
        project.mkdir(versionFileDestination.parentFile)

        // Save version in file.
        versionFileDestination.text = getVersion()
    }

    @Input
    String getVersion() {
        return project.version
    }

    @OutputFile
    File getOutputFile() {
        return new File(project.buildDir, outputFile)
    }

}

If we run the help task for the generateVersionFile task, we can see that our command line option is shown in the list of available options:

$ gradle help --task generationVersionFile
:help
Detailed task information for generateVersionFile

Path
     :generateVersionFile

Type
     GenerateVersionFile (GenerateVersionFile)

Options
     --outputFile     File where the project version is stored

Description
     Generate a file with the project version

Group
     -

BUILD SUCCESSFUL

Total time: 2.933 secs
$

Now we invoke the generateVersionFile task with a value for the command line option:

$ gradle generateVersionFile --outputFile version.saved
:generateVersionFile

BUILD SUCCESSFUL

Total time: 0.826 secs
$ more build/version.saved
demo
$

And just like that, you're all set.