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 the Gradle built-in task help followed by the option --task and the task name. To indicate a property as command line option we use a @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 $
Written with Gradle 3.1.
