bnd / bndtools for VS Code

A Visual Studio Code extension providing rich language support for bnd (.bnd) and bndrun (.bndrun) files used in OSGi development with the bnd/bndtools toolchain.

Features

Syntax Highlighting

Full TextMate grammar covering:

• Instructions – Lines starting with -keyword: (e.g., -buildpath:, -runbundles:, -privatepackage:) highlighted as control keywords.
• OSGi Headers – Standard manifest headers (Bundle-SymbolicName:, Export-Package:, Import-Package:, etc.) highlighted as storage types.
• Properties – Lowercase key-value properties highlighted as variables.
• Macros – ${macroname} expressions, with the macro name highlighted as a function. Nested macros are also handled.
• Version ranges – [1.0,2.0) and (1.0,2.0] highlighted as numeric constants.
• String literals – Single and double-quoted strings.
• Directives – key:=value attribute/directive syntax.
• Continuation lines – Trailing backslash \ line continuations.
• Comments – # line comments and // inline comments.

IntelliSense Completions

Trigger completions with Ctrl+Space (or automatically on -, $, {, :). All completion items are pre-filled with real examples from the bnd documentation.

• 153 bnd instructions – e.g.:
  • -buildpath: osgi;version=4.1
  • -runbundles: org.apache.felix.framework;version='[7,8)'
  • -dsannotations: *, -runee: JavaSE-17, -standalone: ...
• 138 bnd macros – triggered when the cursor is inside ${...}:
  • ${bsn}, ${version}, ${range;[==,+);${@}}, ${repo;bsns}
  • ${filter;<list>;<regex>}, ${replace;<list>;<regex>;<replacement>}
  • ${tstamp;yyyy-MM-dd}, ${githead}, ${system;git describe}
• 48 OSGi headers and bnd pseudo-headers – e.g.:
  • Bundle-SymbolicName: com.example.bundle
  • Export-Package: com.example.api;version=1.0
  • Require-Capability: osgi.identity; filter:='...'

Hover Documentation

Hover over any instruction keyword, OSGi header, or macro name to see:

• The full syntax signature (bold).
• A documentation summary from the bnd reference docs.
• An example from the official bnd documentation, shown in a bnd code block.

Language Server Protocol (LSP)

This extension implements the Language Server Protocol. The language server can be started in three modes:

• java mode: launches the bundled biz.aQute.bnd.lsp.jar with the configured Java executable
• node mode: runs the TypeScript LSP in a separate Node.js process
• socket mode: connects to an already running TCP-based language server on 127.0.0.1:<port>

This means:

• the server can run in the mode that best matches your environment
• the extension falls back cleanly if the bundled LSP JAR is missing
• the LSP remains available for editors that can speak the protocol

Architecture:

VS Code (Extension Host)                Language Server (runtime-selected)
─────────────────────────               ────────────────────────────────
src/extension.ts  ←── IPC ───►  Java JAR / Node / Socket server
  (starts and restarts the server,      (completion, hover,
   registers LSP commands)              diagnostics and command handlers)

Integrated bnd CLI Commands

All commands are available in the Command Palette (Ctrl+Shift+P) under the Bnd: prefix.

All commands run in VS Code's integrated terminal named "bnd".

The Java language server also provides these commands through bndlib. A compatible socket server may advertise them as well:

The extension checks server capabilities before invoking an LSP command. Node fallback mode supports completion and hover, but not these bndlib-backed operations.

Configuration

Set the bnd.cli.executable workspace or user setting to point to your bnd installation:

// settings.json
{
    // If bnd is on your PATH (e.g. brew install bnd):
    "bnd.cli.executable": "bnd",

    // Or run it as an executable JAR:
    "bnd.cli.executable": "java -jar /path/to/biz.aQute.bnd.jar"
}

For the embedded language server, configure the startup mode in bnd.server.mode:

{
  "bnd.server.mode": "java",
  "bnd.server.jar": "",
  "bnd.server.javaExecutable": "",
  "bnd.server.jvmArgs": [],
  "bnd.server.socketPort": 5007
}

• java starts the bundled server/biz.aQute.bnd.lsp.jar with the configured Java runtime and provides full bndlib-backed language features and commands.
• node starts the TypeScript language server directly.
• socket connects to an already running LSP on 127.0.0.1:5007.
• If no JAR is present, the extension warns and falls back to node mode. The fallback provides completion and hover support; bndlib-backed resolve, build, and macro commands require the Java server or a compatible socket server.

You can run Bnd: Download Latest bnd CLI JAR to download and configure the newest available release immediately. If you need an older version such as 7.2.3, run Bnd: Download bnd CLI JAR Version... and select one of the available versions or enter one explicitly. Both commands store the JAR in the extension's library/tool storage folder and update bnd.cli.executable to java -jar ... automatically.

To choose a specific Java runtime for java -jar, run Bnd: Select Java Runtime for bnd CLI. This reads from VS Code's java.configuration.runtimes and updates bnd.cli.javaExecutable.

If your Java runtime is not yet listed, run Bnd: Discover Java Runtimes from Folder.... The selected root folder is searched recursively, and discovered runtimes are appended to java.configuration.runtimes.

If you need to use a Central-compatible mirror instead of Maven Central, set bnd.cli.mavenRepository first, for example:

{
  "bnd.cli.mavenRepository": "https://repo1.maven.org/maven2",
  "bnd.cli.javaExecutable": "java"
}

CLI Reference Panel

Run Bnd: Show CLI Reference (Ctrl+Shift+P → Bnd: Show CLI Reference) to open a searchable panel showing all 77 bnd CLI sub-commands with their full option lists and examples from the official docs.

![CLI Reference panel showing searchable command list]

Installation

From VSIX

1. Download or build vscode-bnd-<version>.vsix.
2. In VS Code open the Extensions view (Ctrl+Shift+X).
3. Click the ... menu → Install from VSIX… and select the file.

See INSTALL.md for full instructions including command-line install.

Build from Source

cd vscode-bnd-plugin
npm install              # install client deps
npm install --prefix server  # install server deps
npm run compile:all      # compile client + server TypeScript
npm run compile:tests    # compile VS Code extension tests
npm test                 # run VS Code extension tests
npm run package          # downloads vsce on demand and builds the VSIX
# Produces vscode-bnd-<version>.vsix

Upstream Java Repo Parity Tests

Some tests validate CLI command parity against bnd Java source in biz.aQute.bnd/src/aQute/bnd/main/bnd.java.

Set one of these environment variables before running npm test:

• BND_SOURCE_REPO=<path-to-bnd-repo>
• BND_JAVA_REPO=<path-to-bnd-repo>

If neither is set, tests also try sibling folder ../bnd. If no source repo is found, parity checks are skipped.

Usage

The extension activates automatically for any file with the .bnd or .bndrun extension.

Example bnd.bnd

Bundle-SymbolicName: com.example.mybundle
Bundle-Version:      1.0.0

-buildpath: \
    osgi.core;version='[7,8)', \
    osgi.annotation;version='[8,9)'

Export-Package: com.example.api;version='${Bundle-Version}'
Private-Package: com.example.internal.*

-dsannotations: *

Example launch.bndrun

-standalone: \
    https://repo.maven.apache.org/maven2/,index;name=central

-runfw: org.apache.felix.framework;version='[7,8)'
-runee: JavaSE-17

-runrequires: \
    osgi.identity;filter:='(osgi.identity=com.example.mybundle)'

-runbundles: \
    com.example.mybundle;version='[1.0.0,1.0.1)'

About

This extension is part of the bnd/bndtools project.

• bnd documentation: https://bnd.bndtools.org
• Issue tracker: https://github.com/bndtools/bnd/issues

License

This project is licensed under the Eclipse Public License 2.0 (EPL-2.0). See LICENSE for the full text.