website·Indexed 30 days ago
https://build-server-protocol.github.io/A protocol for IDEs and build tools that defines a standard interface for build servers and clients. It complements the Language Server Protocol (LSP) and includes specifications for server lifetime, capabilities, and versioning, with language-specific extensions for Rust, Python, Scala, C++, Java, JVM, Maven, Cargo, and sbt.
A BuildTarget represents metadata about an artifact (e.g., a library, test, or binary). It is designed to contain information that is computationally cheap to retrieve.
BuildTarget object instead.export interface BuildTargetIdentifier {
/** The target's Uri */
uri: URI;
}
export interface BuildTarget {
/** The target's unique identifier */
id: BuildTargetIdentifier;
/** A human readable name for this target. */
displayName?: string;
/** The directory where this target belongs to. */
baseDirectory?: URI;
/** Free-form string tags to categorize or label this build target. */
tags: BuildTargetTag[];
/** The set of languages that this target contains. (LSP IDs) */
languageIds: LanguageId[];
/** The direct upstream build target dependencies of this build target */
dependencies: BuildTargetIdentifier[];
/** The capabilities of this build target. */
capabilities: BuildTargetCapabilities;
/** Kind of data to expect in the `data` field. */
dataKind?: BuildTargetDataKind;
/** Language-specific metadata about this target. */
data?: BuildTargetData;
}The Build Server Protocol (BSP) and Language Server Protocol (LSP) are complementary. LSP manages communication between an editor (client) and a language server. BSP manages communication between a language server (acting as a client) and a build server.
In a typical workflow, a language server may use BSP to query a build tool for metadata (such as a module's classpath) to fulfill an LSP request (such as textDocument/definition) sent by the editor.
RustPackage interface represents a Cargo package, which is a bundle of one or more crates (at most one library crate, but any number of binary crates). It contains metadata about the package's identity, version, edition, features, and the targets it produces.export interface RustPackage {
id: string;
rootUrl: URI;
name: string;
version: string;
origin: RustPackageOrigin;
edition: RustEdition;
source?: string;
resolvedTargets: RustTarget[];
allTargets: RustTarget[];
features: FeaturesDependencyGraph;
enabledFeatures: Set<Feature>;
cfgOptions?: RustCfgOptions;
env?: EnvironmentVariables;
outDirUrl?: URI;
procMacroArtifact?: URI;
}The argv field in the connection file specifies the command to start the BSP server.
Client Requirements:
argv is a relative path, the client must prepend the workspace base directory.Build Tool Requirements:
stdin for incoming messages and stdout for responses.stderr for reporting execution progress.The BSP lifecycle follows a pattern similar to LSP to ensure orderly startup and shutdown:
initialize request, the client sends the build/initialized notification. The server can use this to start intensive computations (e.g., dependency resolution). This is sent only once.build/shutdown request. The server should stop its operations but must not exit yet to ensure the response is delivered.build/exit notification. The server should exit with code 0 if build/shutdown was previously received, otherwise with code 1.ch.epfl.scala:bsp4j module is a Java library available from Maven Central. It depends on the eclipse/lsp4j library.// Gradle
compile group: 'ch.epfl.scala', name: 'bsp4j', version: '2.2.0-M4.TEST'<!-- Maven -->
<dependency>
<groupId>ch.epfl.scala</groupId>
<artifactId>bsp4j</artifactId>
<version>2.2.0-M4.TEST</version>
</dependency>// sbt
libraryDependencies += "ch.epfl.scala" % "bsp4j" % "2.2.0-M4.TEST"argv invocation as a system process. The client communicates by writing to the process's system input (stdin) and listening to its system output (stdout). If the argv invocation fails, the client must display the stderr output to the user.BuildTargetTag to define the nature of a build target. This helps IDEs determine how to treat the target (e.g., whether to include it in a global build or ignore it).export namespace BuildTargetTag {
export const Application = "application";
export const Benchmark = "benchmark";
export const IntegrationTest = "integration-test";
export const Library = "library";
export const Manual = "manual"; // Should only be invoked manually
export const NoIde = "no-ide"; // Should be ignored by IDEs
export const Test = "test";
}
BSP clients connect to servers by locating connection files. The discovery process must follow a specific priority: first search the 'bsp user location', and only if no suitable file is found, search the 'system location'.
If multiple connection files are found, clients should use the connection metadata to filter for the desired server. If ambiguity remains, the client may prompt the user to select a server or allow the user to select multiple connections to run separate BSP builds simultaneously.
If no connection file is found, the client may: