org.gradle.tooling

## Interface BuildLauncher

- All Superinterfaces:
    ConfigurableLauncher<BuildLauncher>, LongRunningOperation

      public interface BuildLauncher
      extends ConfigurableLauncher<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 `ProjectConnection.newBuild()`.
  - Configure the launcher as appropriate.
  - Call either `run()` or `run(ResultHandler)` to execute the build.
  - Optionally, you can reuse the launcher to launch additional builds.
  Example:

       ProjectConnection connection = GradleConnector.newConnector()
          .forProjectDirectory(new File("someFolder"))
          .connect();

       try {
          BuildLauncher build = connection.newBuild();

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

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

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

  Since:
    1.0-milestone-3

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `BuildLauncher` | `forLaunchables(Iterable<? extends Launchable> launchables)` Sets the launchables to execute.
    `BuildLauncher` | `forLaunchables(Launchable... launchables)` Sets the launchables to execute.
    `BuildLauncher` | `forTasks(Iterable<? extends Task> tasks)` Sets the tasks to be executed.
    `BuildLauncher` | `forTasks(String... tasks)` Sets the tasks to be executed.
    `BuildLauncher` | `forTasks(Task... tasks)` Sets the tasks to be executed.
    `void` | `run()` Executes the build, blocking until it is complete.
    `void` | `run(ResultHandler<? super Void> handler)` Launches the build.

    - ### Methods inherited from interface org.gradle.tooling.ConfigurableLauncher

      `addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken`

- - ### Method Detail

    - #### forTasks

          BuildLauncher forTasks(String... tasks)

      Sets the tasks to be executed. If no tasks are specified, the project's default tasks are executed.
      Parameters:
        `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### forTasks

          BuildLauncher forTasks(Task... tasks)

      Sets the tasks to be executed. If no tasks are specified, the project's default tasks are executed.

      Note that the supplied tasks do not necessarily need to belong to the project which this launcher was created for.

      Parameters:
        `tasks` - The tasks to be executed.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### forTasks

          BuildLauncher forTasks(Iterable<? extends Task> tasks)

      Sets the tasks to be executed. If no tasks are specified, the project's default tasks are executed.

      Note that the supplied tasks do not necessarily need to belong to the project which this launcher was created for.

      Parameters:
        `tasks` - The tasks to be executed.
      Returns:
        this
      Since:
        1.0-milestone-3

    - #### forLaunchables

          @Incubating
          BuildLauncher forLaunchables(Launchable... launchables)

      Sets the launchables to execute. If no entries are specified, the project's default tasks are executed.
      Parameters:
        `launchables` - The launchables for this build.
      Returns:
        this
      Since:
        1.12

    - #### forLaunchables

          @Incubating
          BuildLauncher forLaunchables(Iterable<? extends Launchable> launchables)

      Sets the launchables to execute. If no entries are specified, the project's default tasks are executed.
      Parameters:
        `launchables` - The launchables for this build.
      Returns:
        this
      Since:
        1.12

    - #### run

          void run()
                   throws GradleConnectionException,
                          IllegalStateException

      Executes the build, blocking until it is complete.
      Throws:
        `UnsupportedVersionException` - When the target Gradle version does not support build execution.
        `UnsupportedOperationConfigurationException` - When the target Gradle version does not support some requested configuration option such as `ConfigurableLauncher.withArguments(String...)`.
        `UnsupportedBuildArgumentException` - When there is a problem with build arguments provided by `ConfigurableLauncher.withArguments(String...)`.
        `BuildException` - On some failure executing the Gradle build.
        `BuildCancelledException` - When the operation was cancelled before it completed successfully.
        `GradleConnectionException` - On some other failure using the connection.
        `IllegalStateException` - When the connection has been closed or is closing.
      Since:
        1.0-milestone-3

    - #### run

          void run(ResultHandler<? super Void> handler)
                   throws IllegalStateException

      Launches the build. This method returns immediately, and the result is later passed to the given handler.

      If the operation fails, the handler's `ResultHandler.onFailure(GradleConnectionException)` method is called with the appropriate exception. See `run()` for a description of the various exceptions that the operation may fail with.

      Parameters:
        `handler` - The handler to supply the result to.
      Throws:
        `IllegalStateException` - When the connection has been closed or is closing.
      Since:
        1.0-milestone-3