Skip to content

v8 - Add a way to push all available configurations (additively) #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Colen Garoutte-Carson (Colengms) wants to merge 1 commit into
base: main
Choose a base branch
from
+68 −12
Draft

v8 - Add a way to push all available configurations (additively) #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 37 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,39 @@ of Microsoft's C/C++ extension for VS Code.

When your extension activates, you can use the following code to get access to the API:

### Version >= 8.0.0
```TypeScript
import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools';

const requestedVersion: Version = Version.v8;
let api: CppToolsApi|undefined = await getCppToolsApi(requestedVersion);
if (api) {
// Inform cpptools that a custom config provider will be able to service the current workspace.
api.registerCustomConfigurationProvider(provider);

// Do any required setup that the provider needs.

// Notify cpptools that the provider is ready to provide IntelliSense configurations.
api.notifyReady(provider);

@bobbrow Bob Brown (bobbrow) Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sample assumes that this API is available. Version checks should be done before any APIs are called to determine which initialization path to choose.


if (api.getVersion() === requestedVersion) {
// Use functions introduced in the requested API version.
api.provideConfigurations(provider, configurations);
} else {
// An older version of cpptools returned an earlier API version.
}
}
// Dispose of the 'api' in your extension's deactivate() method, or whenever you want to unregister the provider.
```

### Version >= 2.1.0
```TypeScript
import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools';

let api: CppToolsApi|undefined = await getCppToolsApi(Version.v2);

const requestedVersion: Version = Version.v2;
let api: CppToolsApi|undefined = await getCppToolsApi(requestedVersion);
if (api) {
if (api.notifyReady) {
if (api.getVersion && api.getVersion() === requestedVersion) {
// Inform cpptools that a custom config provider will be able to service the current workspace.
api.registerCustomConfigurationProvider(provider);

Expand All @@ -20,8 +46,8 @@ When your extension activates, you can use the following code to get access to t
// Notify cpptools that the provider is ready to provide IntelliSense configurations.
api.notifyReady(provider);
} else {
// Running on a version of cpptools that doesn't support v2 yet.
// An older version of cpptools returned an earlier API version.

// Do any required setup that the provider needs.

// Inform cpptools that a custom config provider will be able to service the current workspace.
Expand Down Expand Up @@ -64,6 +90,12 @@ In version 2, you will want to register the provider as soon as your extension a
providing configurations for the active workspace so that the C/C++ extension can disable standard handling of
`c_cpp_properties.json`, including indexing and parsing the files referenced by the active configuration.

In version 8, you will want to provide (push) all configurations as soon as they are available. This provides cpptools with
valid configuration for various features that require accurate include graphs and eager analysis. For configuration
providers that process all configurations as a single batch, that batch should be provided as soon as available. For
configuration providers that lazily/incrementally generate configurations, those can be pushed as they become available,
providing limited support for features that require accurate include graphs and eager analysis.

Prior to version 2, it is best practice to wait to register the provider until it is ready to begin serving configurations.
Once the provider is registered, it is recommended to call `didChangeCustomConfigurations` so that the C/C++ extension will
ask for configurations for files that might have been opened in the editor before the custom configuration provider was
Expand Down
18 changes: 15 additions & 3 deletions api.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ export enum Version {
v5 = 5, // 5.x.x
v6 = 6, // 6.x.x
v7 = 7, // 7.x.x
latest = v7
v8 = 8, // 8.x.x
latest = v8
}

export type CStandard = "c89" | "c99" | "c11" | "c17" | "c23";
Expand Down Expand Up @@ -57,7 +58,7 @@ export interface CppToolsApi extends vscode.Disposable {
notifyReady(provider: CustomConfigurationProvider): void;

/**
* Notify the C/C++ extension that the current configuration has changed. Upon receiving this
* Notify the C/C++ extension that the current set of configurations has changed. Upon receiving this
* notification, the C/C++ extension will request the new configurations.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
Expand All @@ -71,6 +72,17 @@ export interface CppToolsApi extends vscode.Disposable {
* instance representing the provider extension.
*/
didChangeCustomBrowseConfiguration(provider: CustomConfigurationProvider): void;

/**
* Push IntelliSense configurations for source files.
* A provider should push all custom configurations available, as soon as they are available,
* to support features such as whole codebase symbol indexing and for an accurate include graph.
* Configurations are additive. Call `didChangeCustomConfiguration` to clear all configurations.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
* @param items A list of [SourceFileConfigurationItem](#SourceFileConfigurationItem) representing the source files and their configurations.
*/
provideConfigurations(provider: CustomConfigurationProvider, items: SourceFileConfigurationItem[]): void;
}

/**
Expand Down Expand Up @@ -228,7 +240,7 @@ export interface SourceFileConfigurationItem {
};
```
*/
readonly uri: string | vscode.Uri;
readonly uri: string | vscode.Uri | (string | vscode.Uri)[];

/**
* The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri)
Expand Down
17 changes: 14 additions & 3 deletions out/api.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ export declare enum Version {
v5 = 5,
v6 = 6,
v7 = 7,
latest = 7
v8 = 8,
latest = 8
}
export type CStandard = "c89" | "c99" | "c11" | "c17" | "c23";
export type GnuCStandard = "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu23";
Expand Down Expand Up @@ -45,7 +46,7 @@ export interface CppToolsApi extends vscode.Disposable {
*/
notifyReady(provider: CustomConfigurationProvider): void;
/**
* Notify the C/C++ extension that the current configuration has changed. Upon receiving this
* Notify the C/C++ extension that the current set of configurations has changed. Upon receiving this
* notification, the C/C++ extension will request the new configurations.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
Expand All @@ -58,6 +59,16 @@ export interface CppToolsApi extends vscode.Disposable {
* instance representing the provider extension.
*/
didChangeCustomBrowseConfiguration(provider: CustomConfigurationProvider): void;
/**
* Push IntelliSense configurations for source files.
* A provider should push all custom configurations available, as soon as they are available,
* to support features such as whole codebase symbol indexing and for an accurate include graph.
* Configurations are additive. Call `didChangeCustomConfiguration` to clear all configurations.

@bobbrow Bob Brown (bobbrow) Aug 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling didChangeCustomConfiguration will cause cpptools to immediately re-request configurations for all tracked files. Maybe it would be better to have this API add a parameter that signals for cpptools to clear any previous configurations instead.

* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
* @param items A list of [SourceFileConfigurationItem](#SourceFileConfigurationItem) representing the source files and their configurations.
*/
provideConfigurations(provider: CustomConfigurationProvider, items: SourceFileConfigurationItem[]): void;
}
/**
* An interface to allow this extension to communicate with Custom Configuration Provider extensions.
Expand Down Expand Up @@ -189,7 +200,7 @@ export interface SourceFileConfigurationItem {
};
```
*/
readonly uri: string | vscode.Uri;
readonly uri: string | vscode.Uri | (string | vscode.Uri)[];

@bobbrow Bob Brown (bobbrow) Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the idea of having this accept an array. It would be better to have a separate object for configurations that apply to multiple files.

/**
* The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri)
*/
Expand Down
3 changes: 2 additions & 1 deletion out/api.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ var Version;
Version[Version["v5"] = 5] = "v5";
Version[Version["v6"] = 6] = "v6";
Version[Version["v7"] = 7] = "v7";
Version[Version["latest"] = 7] = "latest";
Version[Version["v8"] = 8] = "v8";
Version[Version["latest"] = 8] = "latest";
})(Version = exports.Version || (exports.Version = {}));
/**
* Check if an object satisfies the contract of the CppToolsExtension interface.
Expand Down
Loading