skip to content

What is the Build Server Protocol (BSP) and how does it relate to Gradle's IDE integration?

level: middleimportance: should knowfreq 30%

answer

  1. JSON-RPC, LSP-inspired
  2. build/initialize handshake
  3. build targets = source sets
  4. decouples IDE x build-tool
  5. adapter over Tooling API

basics

~10 s

BSP is a standardized JSON-RPC protocol that lets IDEs ask a build tool about a project's modules, dependencies, and how to build/test it, instead of each IDE writing tool-specific integration code.

solid answer

~40 s

The **Build Server Protocol (BSP)** is a JSON-RPC 2.0 protocol — inspired by the Language Server Protocol — that decouples IDEs from build tools. An IDE (the *client*) connects to a *build server* and exchanges typed requests like `build/initialize`, `workspace/buildTargets`, and `buildTarget/sources` to learn a project's structure (its **build targets**, sources, dependencies, classpath) and to trigger compile/test/run. For Gradle, BSP gives editors a uniform way to import and sync a project: rather than every IDE re-implementing Gradle's model, they speak BSP to a Gradle-backed server. It complements — and increasingly supersedes — the older approach of generating IDE metadata files via the `eclipse`/`idea` plugins. IntelliJ's native Gradle support uses the Tooling API directly, but editors like those built on the BSP ecosystem (e.g. via the Gradle BSP server) use BSP for sync.

code

bash · 9 lines
bash
# A BSP discovery file the IDE reads to learn how to launch the server
# .bsp/gradle.json
{
  "name": "Gradle",
  "version": "1.0",
  "bspVersion": "2.1.0",
  "languages": ["java", "kotlin", "scala"],
  "argv": ["java", "-jar", "gradle-bsp-server.jar"]
}

go deeper

for a junior

Know BSP is a standard protocol that lets IDEs talk to build tools so the editor can understand and build a project.

for a middle

Explain the JSON-RPC nature, the LSP analogy, build targets, and that it decouples IDEs from build tools; contrast with file-generation plugins.

for a senior

Discuss how a Gradle BSP server adapts the Tooling API, the request lifecycle, and where BSP fits versus IntelliJ's native importer.

for a principal

Weigh adopting BSP as the org's IDE-integration strategy across many editors versus relying on each IDE's native importer; consider maintenance and protocol-version drift.

## What problem BSP solves Before BSP, every IDE that wanted to import a build had to write bespoke integration code per build tool: IntelliJ knew how to talk to Gradle, Eclipse had Buildship, VS Code had its own logic, and so on. That is an O(IDEs x build-tools) explosion. The **Build Server Protocol (BSP)** collapses this to O(IDEs + build-tools): each build tool implements a BSP *server* once, and each IDE implements a BSP *client* once. ## The shape of the protocol BSP is **JSON-RPC 2.0** over a transport (typically stdio or a socket), modeled directly on the **Language Server Protocol (LSP)**. The conversation is request/response plus notifications: - `build/initialize` — handshake: the client announces its capabilities and root URI; the server replies with what it supports. - `build/initialized` — notification confirming the client is ready. - `workspace/buildTargets` — list the **build targets** (the unit of granularity — roughly a compilation unit / module / source set). - `buildTarget/sources`, `buildTarget/dependencySources`, `buildTarget/resources` — describe inputs. - `buildTarget/compile`, `buildTarget/test`, `buildTarget/run` — trigger work. - `buildTarget/cleanCache` — invalidate. - `build/shutdown` + `build/exit` — teardown. ## Build targets The central abstraction is the **build target**: an addressable thing the IDE can build, identified by a URI. For a Gradle project a build target maps roughly to a **source set** of a subproject (e.g. `:app` main, `:app` test). The IDE asks for targets, then for each target's sources and classpath, and assembles its project model from that. ## How this relates to Gradle Gradle exposes its project model through the **Tooling API** (a programmatic API for embedding Gradle). A BSP server for Gradle is essentially an adapter: it answers BSP JSON-RPC calls by driving the Tooling API underneath. Historically, IDE integration relied on the `eclipse` and `idea` plugins, which **generate static metadata files** (`.classpath`, `.project`, `.iml`, `.ipr`) on disk. BSP replaces that file-generation model with a **live protocol**: the IDE queries the server on demand and reacts to incremental updates. ## IntelliJ / Buildship caveat Note that IntelliJ IDEA's *built-in* Gradle support does **not** use BSP — it talks to the Tooling API directly and delegates task execution to Gradle. Eclipse Buildship likewise uses the Tooling API. BSP matters most for editors that adopted the BSP ecosystem (sbt, Mill, Bloop, and Gradle's BSP server) so one client implementation works across many build tools. ``` IDE (BSP client) ── JSON-RPC ──> BSP server ── Tooling API ──> Gradle ```

  • Why is BSP described as 'inspired by LSP'?
    Both are JSON-RPC protocols that standardize an IDE-to-tool boundary so editors and tools integrate once each rather than per pair. LSP standardizes language tooling; BSP standardizes build tooling, reusing the same handshake/capabilities pattern.
  • Does IntelliJ use BSP to sync Gradle projects?
    No. IntelliJ's native Gradle integration uses the Tooling API directly. BSP is used by editors that adopted the BSP ecosystem; for Gradle this means a separate BSP server adapter rather than IntelliJ's built-in importer.

BSP is to build tools what LSP is to languages: write the integration once on each side instead of an N-by-M matrix of bespoke plugins.

saying these in an interview costs you the question

  • Claiming BSP is a Gradle-only protocol — it is build-tool-agnostic and shared with sbt, Mill, Bloop, etc.
  • Saying IntelliJ syncs Gradle over BSP by default (it uses the Tooling API).

context

resolving links…