BuildLauncher

A BuildLauncher allows you to configure and execute a Gradle build.

Instances of BuildLauncher are not thread-safe. You use a BuildLauncher as follows:

  • Create an instance of BuildLauncher by calling newBuild.
  • Configure the launcher as appropriate.
  • Call either run or run to execute the build.
  • Optionally, you can reuse the launcher to launch additional builds.
Example:
ProjectConnection connection = GradleConnector.newConnector()
   .forProjectDirectory(new File("some-folder"))
   .connect();

try {
   BuildLauncher build = connection.newBuild();

   //select tasks to run:
   build.forTasks("clean", "test");

   //include some build arguments:
   build.withArguments("-i", "--project-dir", "some-project-dir");

   //configure the standard input:
   build.setStandardInput(new ByteArrayInputStream("consume this!".getBytes()));

   //in case you want the build to use java different than default:
   build.setJavaHome(new File("/path/to/java"));

   //if your build needs crazy amounts of memory:
   build.setJvmArguments("-Xmx2048m", "-XX:MaxPermSize=512m");

   //if you want to listen to the progress events:
   ProgressListener listener = null; // use your implementation
   build.addProgressListener(listener);

   //kick the build off:
   build.run();
} finally {
   connection.close();
}

If the target Gradle version is >=6.8 then you can use BuildLauncher to execute tasks from included builds. You can target tasks from included builds by specifying the task identity path (i.e. ':included-build-name:subproject-name:taskName').

Since

1.0-milestone-3

Functions

Link copied to clipboard
abstract fun addArguments(arguments: Iterable<String>): T
abstract fun addArguments(arguments: Array<String>): T
abstract fun addArguments(arguments: Array<String>): LongRunningOperation
Appends new command line arguments to the existing list.
Link copied to clipboard
abstract fun addJvmArguments(jvmArguments: Iterable<String>): T
abstract fun addJvmArguments(jvmArguments: Array<String>): T
abstract fun addJvmArguments(jvmArguments: Iterable<String>): LongRunningOperation
abstract fun addJvmArguments(jvmArguments: Array<String>): LongRunningOperation
Appends Java VM arguments to the existing list.
Link copied to clipboard
abstract fun addProgressListener(listener: ProgressListener): T
Adds a progress listener which will receive progress events as the operation runs.
abstract fun addProgressListener(listener: ProgressListener): T
Adds a progress listener which will receive progress events of all types as the operation runs.
abstract fun addProgressListener(listener: ProgressListener, eventTypes: Set<OperationType>): T
abstract fun addProgressListener(listener: ProgressListener, operationTypes: Array<OperationType>): T
Adds a progress listener which will receive progress events as the operations of the requested type run.
Link copied to clipboard
abstract fun forLaunchables(launchables: Iterable<out Launchable>): BuildLauncher
abstract fun forLaunchables(launchables: Array<Launchable>): BuildLauncher
Sets the launchables to execute.
Link copied to clipboard
abstract fun forTasks(tasks: Iterable<out Task>): BuildLauncher
abstract fun forTasks(tasks: Array<String>): BuildLauncher
abstract fun forTasks(tasks: Array<Task>): BuildLauncher
Sets the tasks to be executed.
Link copied to clipboard
abstract fun run()
Executes the build, blocking until it is complete.
abstract fun run(handler: ResultHandler<in Void>)
Launches the build.
Link copied to clipboard
abstract fun setColorOutput(colorOutput: Boolean): T
abstract fun setColorOutput(colorOutput: Boolean): LongRunningOperation
Specifies whether to generate colored (ANSI encoded) output for logging.
Link copied to clipboard
abstract fun setEnvironmentVariables(envVariables: Map<String, String>): T
abstract fun setEnvironmentVariables(@Nullable envVariables: @Nullable Map<String, String>): LongRunningOperation
Specifies the environment variables to use for this operation.
Link copied to clipboard
abstract fun setJavaHome(javaHome: File): T
abstract fun setJavaHome(@Nullable javaHome: @Nullable File): LongRunningOperation
Specifies the Java home directory to use for this operation.
Link copied to clipboard
abstract fun setJvmArguments(jvmArguments: Iterable<String>): T
abstract fun setJvmArguments(jvmArguments: Array<String>): T
abstract fun setJvmArguments(@Nullable jvmArguments: @Nullable Iterable<String>): LongRunningOperation
abstract fun setJvmArguments(@Nullable jvmArguments: Array<@Nullable String>): LongRunningOperation
Specifies the Java VM arguments to use for this operation.
Link copied to clipboard
abstract fun setStandardError(outputStream: OutputStream): T
Sets the which should receive standard error logging generated while running the operation.
Sets the OutputStream which should receive standard error logging generated while running the operation.
Link copied to clipboard
abstract fun setStandardInput(inputStream: InputStream): T
Sets the that will be used as standard input for this operation.
Sets the java.io.InputStream that will be used as standard input for this operation.
Link copied to clipboard
abstract fun setStandardOutput(outputStream: OutputStream): T
Sets the which should receive standard output logging generated while running the operation.
Sets the java.io.OutputStream which should receive standard output logging generated while running the operation.
Link copied to clipboard
abstract fun withArguments(arguments: Iterable<String>): T
abstract fun withArguments(arguments: Array<String>): T
abstract fun withArguments(@Nullable arguments: @Nullable Iterable<String>): LongRunningOperation
abstract fun withArguments(@Nullable arguments: Array<@Nullable String>): LongRunningOperation
Specify the command line build arguments.
Link copied to clipboard
abstract fun withCancellationToken(cancellationToken: CancellationToken): T
Sets the cancellation token to use to cancel the operation if required.
Link copied to clipboard
abstract fun withDetailedFailure(): T
Adds more detailed information about the build failure to the that provides insights into the reasons for the failure, making it easier to diagnose and fix issues.
Adds more detailed information about the build failure to the GradleConnectionException that provides insights into the reasons for the failure, making it easier to diagnose and fix issues.
Link copied to clipboard
abstract fun withSystemProperties(systemProperties: Map<String, String>): T
Sets system properties to pass to the build.