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 2 commits into
base: main
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9666d14
v8 - Add a way to push all available configurations (additively)
Colengms Aug 6, 2026
ed2fdae
Define scoped incremental provider updates
Colengms Oct 20, 2026
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);
Comment thread
Colengms marked this conversation as resolved.
Resolved

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.
Comment thread
Colengms marked this conversation as resolved.
Resolved
* @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
Contributor

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.

@Colengms Colen Garoutte-Carson (Colengms) Oct 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Keeping the shared item type lets a v8 provider return grouped configurations for a related project through the existing request callback when one file becomes relevant, as well as push them unsolicited. Existing providers can continue returning single-URI items; array-valued URIs require negotiated v8 support. Leaving this thread open for the type-shape discussion.

/**
* 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