# BuildLauncher

interface BuildLauncher : ConfigurableLauncher<T>

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();
    }

Content copied to clipboard

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

addArguments
Link copied to clipboard
abstract fun addArguments(arguments: Array<String>): T
abstract fun addArguments(arguments: Array<String>): LongRunningOperation
addJvmArguments
Link copied to clipboard
abstract fun addJvmArguments(jvmArguments: Array<String>): T
abstract fun addJvmArguments(jvmArguments: Array<String>): LongRunningOperation
addProgressListener
Link copied to clipboard
abstract fun addProgressListener(listener: ProgressListener): T
abstract fun addProgressListener(listener: ProgressListener): LongRunningOperation
forLaunchables
Link copied to clipboard
abstract fun forLaunchables(launchables: Iterable<out Launchable>): BuildLauncher
abstract fun forLaunchables(launchables: Array<Launchable>): BuildLauncher
Sets the launchables to execute.
forTasks
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.
run
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.
setColorOutput
Link copied to clipboard
abstract fun setColorOutput(colorOutput: Boolean): T
abstract fun setColorOutput(colorOutput: Boolean): LongRunningOperation
setEnvironmentVariables
Link copied to clipboard
abstract fun setEnvironmentVariables(envVariables: Map<String, String>): T
abstract fun setEnvironmentVariables(envVariables: @Nullable Map<String, String>): LongRunningOperation
setJavaHome
Link copied to clipboard
abstract fun setJavaHome(javaHome: File): T
abstract fun setJavaHome(javaHome: @Nullable File): LongRunningOperation
setJvmArguments
Link copied to clipboard
abstract fun setJvmArguments(jvmArguments: Array<String>): T
abstract fun setJvmArguments(jvmArguments: Array<@Nullable String>): LongRunningOperation
setStandardError
Link copied to clipboard
abstract fun setStandardError(outputStream: OutputStream): T
abstract fun setStandardError(outputStream: OutputStream): LongRunningOperation
setStandardInput
Link copied to clipboard
abstract fun setStandardInput(inputStream: InputStream): T
abstract fun setStandardInput(inputStream: InputStream): LongRunningOperation
setStandardOutput
Link copied to clipboard
abstract fun setStandardOutput(outputStream: OutputStream): T
abstract fun setStandardOutput(outputStream: OutputStream): LongRunningOperation
withArguments
Link copied to clipboard
abstract fun withArguments(arguments: Array<String>): T
abstract fun withArguments(arguments: Array<@Nullable String>): LongRunningOperation
withCancellationToken
Link copied to clipboard
abstract fun withCancellationToken(cancellationToken: CancellationToken): T
abstract fun withCancellationToken(cancellationToken: CancellationToken): LongRunningOperation
withDetailedFailure
Link copied to clipboard
abstract fun withDetailedFailure(): T
abstract fun withDetailedFailure(): LongRunningOperation
withSystemProperties
Link copied to clipboard
abstract fun withSystemProperties(systemProperties: Map<String, String>): T
abstract fun withSystemProperties(systemProperties: Map<String, String>): LongRunningOperation