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

README.md

@@ -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);
+
+        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);
 
@@ -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.
@@ -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

api.ts

@@ -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";
@@ -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.
@@ -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;
 }
 
 /**
@@ -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)

out/api.d.ts

@@ -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";
@@ -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.
@@ -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.
+     * @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.
@@ -189,7 +200,7 @@ export interface SourceFileConfigurationItem {
     };
 ```
      */
-    readonly uri: string | vscode.Uri;
+    readonly uri: string | vscode.Uri | (string | vscode.Uri)[];
     /**
      * The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri)
      */

out/api.js

@@ -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.