API.md

Extension API

interface ExtensionApi {
  runTask(opts: RunTaskOpts): Promise<void>;
  cancelRunTask(opts: CancelTaskOpts): Promise<void>;
}

Installation

npm install vscode-gradle --save

Usage

import * as util from "util";
import { ExtensionApi as GradleApi, RunTaskOpts, Output } from "vscode-gradle";

const extension = vscode.extensions.getExtension("vscjava.vscode-gradle");
const gradleApi = extension!.exports as GradleApi;
const runTaskOpts: RunTaskOpts = {
  projectFolder: "/absolute/path/to/project/root",
  taskName: "help",
  showOutputColors: false,
  onOutput: (output: Output): void => {
    const message = new util.TextDecoder("utf-8").decode(
      output.getOutputBytes_asU8()
    );
    console.log(output.getOutputType(), message);
  },
};
await gradleApi.runTask(runTaskOpts);

Refer to vscode-spotless-gradle for example API usage.

The gradle.runBuild command

The command runs a Gradle build in a task terminal. Without a command line (from the command palette) it asks for the root project and the command line. Other extensions can pass the arguments to run a build without any interaction:

await vscode.commands.executeCommand(
  "gradle.runBuild",
  "/absolute/path/to/project/build.gradle", // build file (or directory) of the project, may be of a subproject
  "classes aotClasses", // the Gradle command line: tasks and options
  { JAVA_HOME: "/path/to/jdk" } // optional environment variables for the build
);

• The root project is determined from the build file (or directory): it is the closest root project that contains it. The build runs in the directory of the build file, as cd subproject && gradle <tasks> would.
• JAVA_HOME of the environment is the Java home that Gradle runs with, it wins over the one of the extension settings (java.import.gradle.java.home). All other variables are added to the environment of the Gradle server process.
• When a command line is supplied, the task terminal is revealed without taking focus.
• The command completes when the build has finished. It does not tell how the build ended.
• A build that is already running (same resolved build directory and parsed arguments) is not started again. Whitespace or quoting differences that produce the same arguments reuse the running build. The command completes when that build has finished.