├── .gitignore ├── .npmignore ├── .npmrc ├── CODEOWNERS ├── LICENSE ├── README.md ├── SECURITY.md ├── api.ts ├── jobs └── cg.yml ├── out ├── api.d.ts ├── api.js ├── testApi.d.ts └── testApi.js ├── package-lock.json ├── package.json ├── testApi.ts └── tsconfig.json /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | 8 | # Dependency directories 9 | node_modules/ 10 | 11 | # Optional npm cache directory 12 | .npm 13 | 14 | # Optional eslint cache 15 | .eslintcache 16 | 17 | # VS Code items 18 | .vscode/ -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | jobs/ 2 | node_modules/ 3 | .gitignore 4 | .npmrc 5 | CODEOWNERS 6 | package-lock.json 7 | SECURITY.md 8 | tsconfig.json 9 | *.ts -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | registry=https://pkgs.dev.azure.com/azure-public/VisualCpp/_packaging/cpp_PublicPackages/npm/registry/ 2 | always-auth=true -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Each line is a file pattern followed by one or more owners. 2 | 3 | # These owners will be the default owners for everything in 4 | # the repo. Unless a later match takes precedence, 5 | # @microsoft/cpptools-maintainers will be requested for 6 | # review when someone opens a pull request. 7 | 8 | * @microsoft/cpptools-maintainers 9 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | vscode-cpptools-api 2 | 3 | Copyright (c) Microsoft Corporation 4 | All rights reserved. 5 | 6 | MIT License 7 | 8 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 11 | 12 | THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 13 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Public API for the ms-vscode.cpptools VS Code extension 2 | 3 | The purpose of this API is to allow for build system extensions to provide IntelliSense configurations for consumers 4 | of Microsoft's C/C++ extension for VS Code. 5 | 6 | When your extension activates, you can use the following code to get access to the API: 7 | 8 | ### Version >= 2.1.0 9 | ```TypeScript 10 | import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools'; 11 | 12 | let api: CppToolsApi|undefined = await getCppToolsApi(Version.v2); 13 | if (api) { 14 | if (api.notifyReady) { 15 | // Inform cpptools that a custom config provider will be able to service the current workspace. 16 | api.registerCustomConfigurationProvider(provider); 17 | 18 | // Do any required setup that the provider needs. 19 | 20 | // Notify cpptools that the provider is ready to provide IntelliSense configurations. 21 | api.notifyReady(provider); 22 | } else { 23 | // Running on a version of cpptools that doesn't support v2 yet. 24 | 25 | // Do any required setup that the provider needs. 26 | 27 | // Inform cpptools that a custom config provider will be able to service the current workspace. 28 | api.registerCustomConfigurationProvider(provider); 29 | api.didChangeCustomConfiguration(provider); 30 | } 31 | } 32 | // Dispose of the 'api' in your extension's deactivate() method, or whenever you want to unregister the provider. 33 | ``` 34 | 35 | ### Version < 2.0.0 36 | 37 | ```TypeScript 38 | import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools'; 39 | 40 | let api: CppToolsApi|undefined = await getCppToolsApi(Version.v1); 41 | if (api) { 42 | api.registerCustomConfigurationProvider(provider); 43 | } 44 | // Dispose of the 'api' in your extension's deactivate() method, or whenever you want to unregister the provider. 45 | ``` 46 | 47 | ### Version 0.1.0 [deprecated] 48 | 49 | ```TypeScript 50 | let cpptools: vscode.Extension = vscode.extensions.getExtension("ms-vscode.cpptools"); 51 | let api: CppToolsApi; 52 | 53 | if (!cpptools.isActive) { 54 | api = await cpptools.activate(); 55 | } else { 56 | api = cpptools.exports; 57 | } 58 | ``` 59 | 60 | Upon registering the provider, the C/C++ extension will prompt the user if they would like to use the custom configuration 61 | provider to serve IntelliSense configurations for the workspace folder. 62 | 63 | In version 2, you will want to register the provider as soon as your extension activates and confirms that it is capable of 64 | providing configurations for the active workspace so that the C/C++ extension can disable standard handling of 65 | `c_cpp_properties.json`, including indexing and parsing the files referenced by the active configuration. 66 | 67 | Prior to version 2, it is best practice to wait to register the provider until it is ready to begin serving configurations. 68 | Once the provider is registered, it is recommended to call `didChangeCustomConfigurations` so that the C/C++ extension will 69 | ask for configurations for files that might have been opened in the editor before the custom configuration provider was 70 | registered. 71 | 72 | # Contributing 73 | 74 | This project welcomes contributions and suggestions. Most contributions require you to agree to a 75 | Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us 76 | the rights to use your contribution. For details, visit https://cla.microsoft.com. 77 | 78 | When you submit a pull request, a CLA-bot will automatically determine whether you need to provide 79 | a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions 80 | provided by the bot. You will only need to do this once across all repos using our CLA. 81 | 82 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 83 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or 84 | contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 85 | 86 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /api.ts: -------------------------------------------------------------------------------- 1 | /* -------------------------------------------------------------------------------------------- 2 | * Copyright (c) Microsoft Corporation. All rights reserved. 3 | * Licensed under the MIT license. 4 | * ------------------------------------------------------------------------------------------ */ 5 | 'use strict'; 6 | 7 | import * as vscode from 'vscode'; 8 | 9 | /** 10 | * API version information. 11 | */ 12 | export enum Version { 13 | v0 = 0, // 0.x.x 14 | v1 = 1, // 1.x.x 15 | v2 = 2, // 2.x.x 16 | v3 = 3, // 3.x.x 17 | v4 = 4, // 4.x.x 18 | v5 = 5, // 5.x.x 19 | v6 = 6, // 6.x.x 20 | latest = v6 21 | } 22 | 23 | /** 24 | * An interface to allow VS Code extensions to communicate with the C/C++ extension. 25 | * @see [CppToolsExtension](#CppToolsExtension) for a code example. 26 | */ 27 | export interface CppToolsApi extends vscode.Disposable { 28 | /** 29 | * The version of the API being used. 30 | */ 31 | getVersion(): Version; 32 | 33 | /** 34 | * Register a [CustomConfigurationProvider](#CustomConfigurationProvider). 35 | * This should be called as soon as the provider extension has been activated and determines that 36 | * it is capable of providing configurations for the workspace. The provider extension does not 37 | * need to be ready to provide configurations when this is called. The C/C++ extension will not 38 | * request configurations until the extension has signaled that it is ready to provide them. 39 | * @see [](#) 40 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 41 | * instance representing the provider extension. 42 | */ 43 | registerCustomConfigurationProvider(provider: CustomConfigurationProvider): void; 44 | 45 | /** 46 | * Notify the C/C++ extension that the [CustomConfigurationProvider](#CustomConfigurationProvider) 47 | * is ready to provide custom configurations. 48 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 49 | * instance representing the provider extension. 50 | */ 51 | notifyReady(provider: CustomConfigurationProvider): void; 52 | 53 | /** 54 | * Notify the C/C++ extension that the current configuration has changed. Upon receiving this 55 | * notification, the C/C++ extension will request the new configurations. 56 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 57 | * instance representing the provider extension. 58 | */ 59 | didChangeCustomConfiguration(provider: CustomConfigurationProvider): void; 60 | 61 | /** 62 | * Notify the C/C++ extension that the code browsing configuration has changed. Upon receiving this 63 | * notification, the C/C++ extension will request the new configuration. 64 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 65 | * instance representing the provider extension. 66 | */ 67 | didChangeCustomBrowseConfiguration(provider: CustomConfigurationProvider): void; 68 | } 69 | 70 | /** 71 | * An interface to allow this extension to communicate with Custom Configuration Provider extensions. 72 | */ 73 | export interface CustomConfigurationProvider extends vscode.Disposable { 74 | /** 75 | * The friendly name of the Custom Configuration Provider extension. 76 | */ 77 | readonly name: string; 78 | 79 | /** 80 | * The id of the extension providing custom configurations. (e.g. `ms-vscode.cpptools`) 81 | */ 82 | readonly extensionId: string; 83 | 84 | /** 85 | * A request to determine whether this provider can provide IntelliSense configurations for the given document. 86 | * @param uri The URI of the document. 87 | * @param token (optional) The cancellation token. 88 | * @returns 'true' if this provider can provide IntelliSense configurations for the given document. 89 | */ 90 | canProvideConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable; 91 | 92 | /** 93 | * A request to get Intellisense configurations for the given files. 94 | * @param uris A list of one of more URIs for the files to provide configurations for. 95 | * @param token (optional) The cancellation token. 96 | * @returns A list of [SourceFileConfigurationItem](#SourceFileConfigurationItem) for the documents that this provider 97 | * is able to provide IntelliSense configurations for. 98 | * Note: If this provider cannot provide configurations for any of the files in `uris`, the provider may omit the 99 | * configuration for that file in the return value. An empty array may be returned if the provider cannot provide 100 | * configurations for any of the files requested. 101 | */ 102 | provideConfigurations(uris: vscode.Uri[], token?: vscode.CancellationToken): Thenable; 103 | 104 | /** 105 | * A request to determine whether this provider can provide a code browsing configuration for the workspace folder. 106 | * @param token (optional) The cancellation token. 107 | * @returns 'true' if this provider can provide a code browsing configuration for the workspace folder. 108 | */ 109 | canProvideBrowseConfiguration(token?: vscode.CancellationToken): Thenable; 110 | 111 | /** 112 | * A request to get the code browsing configuration for the workspace folder. 113 | * @param token (optional) The cancellation token. 114 | * @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to 115 | * construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration to report, or 116 | * the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) 117 | * then `null` should be returned. 118 | */ 119 | provideBrowseConfiguration(token?: vscode.CancellationToken): Thenable; 120 | 121 | /** 122 | * A request to determine whether this provider can provide a code browsing configuration for each folder in a multi-root workspace. 123 | * @param token (optional) The cancellation token. 124 | * @returns 'true' if this provider can provide a code browsing configuration for each folder in a multi-root workspace. 125 | */ 126 | canProvideBrowseConfigurationsPerFolder(token?: vscode.CancellationToken): Thenable; 127 | 128 | /** 129 | * A request to get the code browsing configuration for the workspace folder. 130 | * @param uri The URI of the folder to provide a browse configuration for. 131 | * @param token (optional) The cancellation token. 132 | * @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to 133 | * construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration for this folder, or 134 | * the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) per folder 135 | * then `null` should be returned. 136 | */ 137 | provideFolderBrowseConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable; 138 | } 139 | 140 | /** 141 | * The model representing the custom IntelliSense configurations for a source file. 142 | */ 143 | export interface SourceFileConfiguration { 144 | /** 145 | * This must also include the system include path (compiler defaults) unless 146 | * [compilerPath](#SourceFileConfiguration.compilerPath) is specified. 147 | * Mac framework paths may also be added to this array. 148 | */ 149 | readonly includePath: string[]; 150 | 151 | /** 152 | * This must also include the compiler default defines (__cplusplus, etc) unless 153 | * [compilerPath](#SourceFileConfiguration.compilerPath) is specified. 154 | */ 155 | readonly defines: string[]; 156 | 157 | /** 158 | * The platform, compiler, and architecture variant to emulate. 159 | * IntelliSenseMode values without a platform variant will resolve to a value that matches 160 | * the host platform. For example, if the host platform is Windows and the IntelliSenseMode 161 | * is "clang-x64", then "clang-x64" will resolve to "windows-clang-x64". 162 | */ 163 | readonly intelliSenseMode?: "linux-clang-x86" | "linux-clang-x64" | "linux-clang-arm" | "linux-clang-arm64" | 164 | "linux-gcc-x86" | "linux-gcc-x64" | "linux-gcc-arm" | "linux-gcc-arm64" | 165 | "macos-clang-x86" | "macos-clang-x64" | "macos-clang-arm" | "macos-clang-arm64" | 166 | "macos-gcc-x86" | "macos-gcc-x64" | "macos-gcc-arm" | "macos-gcc-arm64" | 167 | "windows-clang-x86" | "windows-clang-x64" | "windows-clang-arm" | "windows-clang-arm64" | 168 | "windows-gcc-x86" | "windows-gcc-x64" | "windows-gcc-arm" | "windows-gcc-arm64" | 169 | "windows-msvc-x86" | "windows-msvc-x64" | "windows-msvc-arm" | "windows-msvc-arm64" | 170 | "msvc-x86" | "msvc-x64" | "msvc-arm" | "msvc-arm64" | 171 | "gcc-x86" | "gcc-x64" | "gcc-arm" | "gcc-arm64" | 172 | "clang-x86" | "clang-x64" | "clang-arm" | "clang-arm64"; 173 | 174 | /** 175 | * The C or C++ standard to emulate. 176 | */ 177 | readonly standard?: "c89" | "c99" | "c11" | "c17" | "c++98" | "c++03" | "c++11" | "c++14" | "c++17" | "c++20" | "c++23" | "c++26" | 178 | "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu++98" | "gnu++03" | "gnu++11" | "gnu++14" | "gnu++17" | "gnu++20" | "gnu++23" | "gnu++26"; 179 | /** 180 | * Any files that need to be included before the source file is parsed. 181 | */ 182 | readonly forcedInclude?: string[]; 183 | 184 | /** 185 | * The full path to the compiler. If specified, the extension will query it for system includes and defines and 186 | * add them to [includePath](#SourceFileConfiguration.includePath) and [defines](#SourceFileConfiguration.defines). 187 | */ 188 | readonly compilerPath?: string; 189 | 190 | /** 191 | * Arguments for the compiler. These arguments will not be processed by the shell and should not include any 192 | * shell variables, quoting or escaping. 193 | */ 194 | readonly compilerArgs?: string[]; 195 | 196 | /** 197 | * Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed 198 | * content such as shell quoting and escaping. 199 | */ 200 | readonly compilerFragments?: string[]; 201 | 202 | /** 203 | * The version of the Windows SDK that should be used. This field will only be used if 204 | * [compilerPath](#SourceFileConfiguration.compilerPath) is set and the compiler is capable of targeting Windows. 205 | */ 206 | readonly windowsSdkVersion?: string; 207 | } 208 | 209 | /** 210 | * The model representing a source file and its corresponding configuration. 211 | */ 212 | export interface SourceFileConfigurationItem { 213 | /** 214 | * The URI of the source file. It should follow the file URI scheme and represent an absolute path to the file. 215 | * @example 216 | ``` 217 | // When working with a file path, 218 | // convert it to a vscode.Uri first. 219 | let path: string = ...; 220 | let item: SourceFileConfigurationItem = { 221 | uri: vscode.Uri.file(path), 222 | configuration: ... 223 | }; 224 | ``` 225 | */ 226 | readonly uri: string | vscode.Uri; 227 | 228 | /** 229 | * The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri) 230 | */ 231 | readonly configuration: SourceFileConfiguration; 232 | } 233 | 234 | /** 235 | * The model representing the source browsing configuration for a workspace folder. 236 | */ 237 | export interface WorkspaceBrowseConfiguration { 238 | /** 239 | * This must also include the system include path (compiler defaults) unless 240 | * [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is specified. 241 | */ 242 | readonly browsePath: string[]; 243 | 244 | /** 245 | * The full path to the compiler. If specified, the extension will query it for system includes and 246 | * add them to [browsePath](#WorkspaceBrowseConfiguration.browsePath). 247 | */ 248 | readonly compilerPath?: string; 249 | 250 | /** 251 | * Arguments for the compiler. These arguments will not be processed by the shell and should not include any 252 | * shell variables, quoting or escaping. 253 | */ 254 | readonly compilerArgs?: string[]; 255 | 256 | /** 257 | * Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed 258 | * content such as shell quoting and escaping. 259 | */ 260 | readonly compilerFragments?: string[]; 261 | 262 | /** 263 | * The C or C++ standard to emulate. This field defaults to "c++17" and will only be used if 264 | * [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is set. 265 | */ 266 | readonly standard?: "c89" | "c99" | "c11" | "c17" | "c++98" | "c++03" | "c++11" | "c++14" | "c++17" | "c++20" | "c++23" | 267 | "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu++98" | "gnu++03" | "gnu++11" | "gnu++14" | "gnu++17" | "gnu++20" | "gnu++23"; 268 | /** 269 | * The version of the Windows SDK that should be used. This field defaults to the latest Windows SDK 270 | * installed on the PC and will only be used if [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) 271 | * is set and the compiler is capable of targeting Windows. 272 | */ 273 | readonly windowsSdkVersion?: string; 274 | } 275 | 276 | /** 277 | * The interface provided by the C/C++ extension during activation. 278 | * It is recommended to use the helper function [getCppToolsApi](#getCppToolsApi) instead 279 | * of querying the extension instance directly. 280 | */ 281 | export interface CppToolsExtension { 282 | /** 283 | * Get an API object. 284 | * @param version The desired version. 285 | */ 286 | getApi(version: Version): CppToolsApi; 287 | } 288 | 289 | /** 290 | * Check if an object satisfies the contract of the CppToolsExtension interface. 291 | */ 292 | function isCppToolsExtension(extension: any): extension is CppToolsExtension { 293 | return extension && extension.getApi; 294 | } 295 | 296 | /** 297 | * Check if an object satisfies the contract of the first version of the CppToolsApi. 298 | * (The first release of the API only had two functions) 299 | */ 300 | function isLegacyCppToolsApi(api: any): api is CppToolsApi { 301 | return api && api.registerCustomConfigurationProvider && api.didChangeCustomConfiguration 302 | } 303 | 304 | /** 305 | * Helper function to get the CppToolsApi from the cpptools extension. 306 | * @param version The desired API version 307 | * @example 308 | ``` 309 | import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools'; 310 | 311 | let api: CppToolsApi|undefined = await getCppToolsApi(Version.v1); 312 | if (api) { 313 | // Inform cpptools that a custom config provider 314 | // will be able to service the current workspace. 315 | api.registerCustomConfigurationProvider(provider); 316 | 317 | // Do any required setup that the provider needs. 318 | 319 | // Notify cpptools that the provider is ready to 320 | // provide IntelliSense configurations. 321 | api.notifyReady(provider); 322 | } 323 | // Dispose of the 'api' in your extension's 324 | // deactivate() method, or whenever you want to 325 | // unregister the provider. 326 | ``` 327 | */ 328 | export async function getCppToolsApi(version: Version): Promise { 329 | let cpptools: vscode.Extension | undefined = vscode.extensions.getExtension("ms-vscode.cpptools"); 330 | let extension: CppToolsApi | CppToolsExtension | undefined = undefined; 331 | let api: CppToolsApi | undefined = undefined; 332 | 333 | if (cpptools) { 334 | if (!cpptools.isActive) { 335 | try { 336 | // activate may throw if VS Code is shutting down. 337 | extension = await cpptools.activate(); 338 | } catch { 339 | } 340 | } else { 341 | extension = cpptools.exports; 342 | } 343 | 344 | if (isCppToolsExtension(extension)) { 345 | // ms-vscode.cpptools > 0.17.5 346 | try { 347 | api = extension.getApi(version); 348 | } catch (err) { 349 | // Unfortunately, ms-vscode.cpptools [0.17.6, 0.18.1] throws a RangeError if you specify a version greater than v1. 350 | // These versions of the extension will not be able to act on the newer interface and v2 is a superset of v1, so we can safely fall back to v1. 351 | let e: RangeError = err; 352 | if (e && e.message && e.message.startsWith("Invalid version")) { 353 | api = extension.getApi(Version.v1); 354 | } 355 | } 356 | 357 | if (version !== Version.v1) { 358 | if (!api.getVersion) { 359 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version 1 instead.`); 360 | } else if (version !== api.getVersion()) { 361 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version ${api.getVersion()} instead.`); 362 | } 363 | } 364 | } else if (isLegacyCppToolsApi(extension)) { 365 | // ms-vscode.cpptools version 0.17.5 366 | api = extension; 367 | if (version !== Version.v0) { 368 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in version 0.17.5 of the cpptools extension. Using version 0 instead.`); 369 | } 370 | } else { 371 | console.warn('[vscode-cpptools-api] No cpptools API was found.') 372 | } 373 | } else { 374 | console.warn('[vscode-cpptools-api] C/C++ extension is not installed'); 375 | } 376 | return api; 377 | } 378 | -------------------------------------------------------------------------------- /jobs/cg.yml: -------------------------------------------------------------------------------- 1 | name: $(date:yyyyMMdd)$(rev:.r) 2 | trigger: 3 | branches: 4 | include: 5 | - main 6 | 7 | schedules: 8 | - cron: 30 5 * * 0 9 | branches: 10 | include: 11 | - main 12 | always: true 13 | 14 | resources: 15 | repositories: 16 | - repository: MicroBuildTemplate 17 | type: git 18 | name: 1ESPipelineTemplates/MicroBuildTemplate 19 | ref: refs/tags/release 20 | 21 | extends: 22 | template: azure-pipelines/MicroBuild.1ES.Official.yml@MicroBuildTemplate 23 | parameters: 24 | pool: 25 | name: AzurePipelines-EO 26 | image: AzurePipelinesWindows2022compliantGPT 27 | os: windows 28 | sdl: 29 | sourceAnalysisPool: 30 | name: AzurePipelines-EO 31 | image: AzurePipelinesWindows2022compliantGPT 32 | os: windows 33 | policheck: 34 | enabled: true 35 | tsa: 36 | enabled: false 37 | featureFlags: 38 | autoBaseline: false 39 | 40 | stages: 41 | - stage: build 42 | jobs: 43 | - job: Phase_1 44 | displayName: Build 45 | timeoutInMinutes: 60 46 | cancelTimeoutInMinutes: 1 47 | templateContext: 48 | outputs: 49 | - output: pipelineArtifact 50 | displayName: 'output' 51 | condition: succeeded() 52 | targetPath: out 53 | artifactName: out 54 | 55 | steps: 56 | - checkout: self 57 | 58 | - task: UseNode@1 59 | displayName: Use Node 22.x 60 | inputs: 61 | version: 22.x 62 | 63 | - script: IF EXIST %SYSTEMDRIVE%\Users\%USERNAME%\.npmrc del %SYSTEMDRIVE%\Users\%USERNAME%\.npmrc 64 | displayName: Delete .npmrc if it exists 65 | 66 | - task: Npm@1 67 | displayName: 'npm install' 68 | 69 | - task: Npm@1 70 | displayName: 'npm run compile' 71 | inputs: 72 | command: custom 73 | customCommand: 'run compile' 74 | -------------------------------------------------------------------------------- /out/api.d.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | /** 3 | * API version information. 4 | */ 5 | export declare enum Version { 6 | v0 = 0, 7 | v1 = 1, 8 | v2 = 2, 9 | v3 = 3, 10 | v4 = 4, 11 | v5 = 5, 12 | v6 = 6, 13 | latest = 6 14 | } 15 | /** 16 | * An interface to allow VS Code extensions to communicate with the C/C++ extension. 17 | * @see [CppToolsExtension](#CppToolsExtension) for a code example. 18 | */ 19 | export interface CppToolsApi extends vscode.Disposable { 20 | /** 21 | * The version of the API being used. 22 | */ 23 | getVersion(): Version; 24 | /** 25 | * Register a [CustomConfigurationProvider](#CustomConfigurationProvider). 26 | * This should be called as soon as the provider extension has been activated and determines that 27 | * it is capable of providing configurations for the workspace. The provider extension does not 28 | * need to be ready to provide configurations when this is called. The C/C++ extension will not 29 | * request configurations until the extension has signaled that it is ready to provide them. 30 | * @see [](#) 31 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 32 | * instance representing the provider extension. 33 | */ 34 | registerCustomConfigurationProvider(provider: CustomConfigurationProvider): void; 35 | /** 36 | * Notify the C/C++ extension that the [CustomConfigurationProvider](#CustomConfigurationProvider) 37 | * is ready to provide custom configurations. 38 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 39 | * instance representing the provider extension. 40 | */ 41 | notifyReady(provider: CustomConfigurationProvider): void; 42 | /** 43 | * Notify the C/C++ extension that the current configuration has changed. Upon receiving this 44 | * notification, the C/C++ extension will request the new configurations. 45 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 46 | * instance representing the provider extension. 47 | */ 48 | didChangeCustomConfiguration(provider: CustomConfigurationProvider): void; 49 | /** 50 | * Notify the C/C++ extension that the code browsing configuration has changed. Upon receiving this 51 | * notification, the C/C++ extension will request the new configuration. 52 | * @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider) 53 | * instance representing the provider extension. 54 | */ 55 | didChangeCustomBrowseConfiguration(provider: CustomConfigurationProvider): void; 56 | } 57 | /** 58 | * An interface to allow this extension to communicate with Custom Configuration Provider extensions. 59 | */ 60 | export interface CustomConfigurationProvider extends vscode.Disposable { 61 | /** 62 | * The friendly name of the Custom Configuration Provider extension. 63 | */ 64 | readonly name: string; 65 | /** 66 | * The id of the extension providing custom configurations. (e.g. `ms-vscode.cpptools`) 67 | */ 68 | readonly extensionId: string; 69 | /** 70 | * A request to determine whether this provider can provide IntelliSense configurations for the given document. 71 | * @param uri The URI of the document. 72 | * @param token (optional) The cancellation token. 73 | * @returns 'true' if this provider can provide IntelliSense configurations for the given document. 74 | */ 75 | canProvideConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable; 76 | /** 77 | * A request to get Intellisense configurations for the given files. 78 | * @param uris A list of one of more URIs for the files to provide configurations for. 79 | * @param token (optional) The cancellation token. 80 | * @returns A list of [SourceFileConfigurationItem](#SourceFileConfigurationItem) for the documents that this provider 81 | * is able to provide IntelliSense configurations for. 82 | * Note: If this provider cannot provide configurations for any of the files in `uris`, the provider may omit the 83 | * configuration for that file in the return value. An empty array may be returned if the provider cannot provide 84 | * configurations for any of the files requested. 85 | */ 86 | provideConfigurations(uris: vscode.Uri[], token?: vscode.CancellationToken): Thenable; 87 | /** 88 | * A request to determine whether this provider can provide a code browsing configuration for the workspace folder. 89 | * @param token (optional) The cancellation token. 90 | * @returns 'true' if this provider can provide a code browsing configuration for the workspace folder. 91 | */ 92 | canProvideBrowseConfiguration(token?: vscode.CancellationToken): Thenable; 93 | /** 94 | * A request to get the code browsing configuration for the workspace folder. 95 | * @param token (optional) The cancellation token. 96 | * @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to 97 | * construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration to report, or 98 | * the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) 99 | * then `null` should be returned. 100 | */ 101 | provideBrowseConfiguration(token?: vscode.CancellationToken): Thenable; 102 | /** 103 | * A request to determine whether this provider can provide a code browsing configuration for each folder in a multi-root workspace. 104 | * @param token (optional) The cancellation token. 105 | * @returns 'true' if this provider can provide a code browsing configuration for each folder in a multi-root workspace. 106 | */ 107 | canProvideBrowseConfigurationsPerFolder(token?: vscode.CancellationToken): Thenable; 108 | /** 109 | * A request to get the code browsing configuration for the workspace folder. 110 | * @param uri The URI of the folder to provide a browse configuration for. 111 | * @param token (optional) The cancellation token. 112 | * @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to 113 | * construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration for this folder, or 114 | * the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) per folder 115 | * then `null` should be returned. 116 | */ 117 | provideFolderBrowseConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable; 118 | } 119 | /** 120 | * The model representing the custom IntelliSense configurations for a source file. 121 | */ 122 | export interface SourceFileConfiguration { 123 | /** 124 | * This must also include the system include path (compiler defaults) unless 125 | * [compilerPath](#SourceFileConfiguration.compilerPath) is specified. 126 | * Mac framework paths may also be added to this array. 127 | */ 128 | readonly includePath: string[]; 129 | /** 130 | * This must also include the compiler default defines (__cplusplus, etc) unless 131 | * [compilerPath](#SourceFileConfiguration.compilerPath) is specified. 132 | */ 133 | readonly defines: string[]; 134 | /** 135 | * The platform, compiler, and architecture variant to emulate. 136 | * IntelliSenseMode values without a platform variant will resolve to a value that matches 137 | * the host platform. For example, if the host platform is Windows and the IntelliSenseMode 138 | * is "clang-x64", then "clang-x64" will resolve to "windows-clang-x64". 139 | */ 140 | readonly intelliSenseMode?: "linux-clang-x86" | "linux-clang-x64" | "linux-clang-arm" | "linux-clang-arm64" | "linux-gcc-x86" | "linux-gcc-x64" | "linux-gcc-arm" | "linux-gcc-arm64" | "macos-clang-x86" | "macos-clang-x64" | "macos-clang-arm" | "macos-clang-arm64" | "macos-gcc-x86" | "macos-gcc-x64" | "macos-gcc-arm" | "macos-gcc-arm64" | "windows-clang-x86" | "windows-clang-x64" | "windows-clang-arm" | "windows-clang-arm64" | "windows-gcc-x86" | "windows-gcc-x64" | "windows-gcc-arm" | "windows-gcc-arm64" | "windows-msvc-x86" | "windows-msvc-x64" | "windows-msvc-arm" | "windows-msvc-arm64" | "msvc-x86" | "msvc-x64" | "msvc-arm" | "msvc-arm64" | "gcc-x86" | "gcc-x64" | "gcc-arm" | "gcc-arm64" | "clang-x86" | "clang-x64" | "clang-arm" | "clang-arm64"; 141 | /** 142 | * The C or C++ standard to emulate. 143 | */ 144 | readonly standard?: "c89" | "c99" | "c11" | "c17" | "c++98" | "c++03" | "c++11" | "c++14" | "c++17" | "c++20" | "c++23" | "c++26" | "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu++98" | "gnu++03" | "gnu++11" | "gnu++14" | "gnu++17" | "gnu++20" | "gnu++23" | "gnu++26"; 145 | /** 146 | * Any files that need to be included before the source file is parsed. 147 | */ 148 | readonly forcedInclude?: string[]; 149 | /** 150 | * The full path to the compiler. If specified, the extension will query it for system includes and defines and 151 | * add them to [includePath](#SourceFileConfiguration.includePath) and [defines](#SourceFileConfiguration.defines). 152 | */ 153 | readonly compilerPath?: string; 154 | /** 155 | * Arguments for the compiler. These arguments will not be processed by the shell and should not include any 156 | * shell variables, quoting or escaping. 157 | */ 158 | readonly compilerArgs?: string[]; 159 | /** 160 | * Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed 161 | * content such as shell quoting and escaping. 162 | */ 163 | readonly compilerFragments?: string[]; 164 | /** 165 | * The version of the Windows SDK that should be used. This field will only be used if 166 | * [compilerPath](#SourceFileConfiguration.compilerPath) is set and the compiler is capable of targeting Windows. 167 | */ 168 | readonly windowsSdkVersion?: string; 169 | } 170 | /** 171 | * The model representing a source file and its corresponding configuration. 172 | */ 173 | export interface SourceFileConfigurationItem { 174 | /** 175 | * The URI of the source file. It should follow the file URI scheme and represent an absolute path to the file. 176 | * @example 177 | ``` 178 | // When working with a file path, 179 | // convert it to a vscode.Uri first. 180 | let path: string = ...; 181 | let item: SourceFileConfigurationItem = { 182 | uri: vscode.Uri.file(path), 183 | configuration: ... 184 | }; 185 | ``` 186 | */ 187 | readonly uri: string | vscode.Uri; 188 | /** 189 | * The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri) 190 | */ 191 | readonly configuration: SourceFileConfiguration; 192 | } 193 | /** 194 | * The model representing the source browsing configuration for a workspace folder. 195 | */ 196 | export interface WorkspaceBrowseConfiguration { 197 | /** 198 | * This must also include the system include path (compiler defaults) unless 199 | * [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is specified. 200 | */ 201 | readonly browsePath: string[]; 202 | /** 203 | * The full path to the compiler. If specified, the extension will query it for system includes and 204 | * add them to [browsePath](#WorkspaceBrowseConfiguration.browsePath). 205 | */ 206 | readonly compilerPath?: string; 207 | /** 208 | * Arguments for the compiler. These arguments will not be processed by the shell and should not include any 209 | * shell variables, quoting or escaping. 210 | */ 211 | readonly compilerArgs?: string[]; 212 | /** 213 | * Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed 214 | * content such as shell quoting and escaping. 215 | */ 216 | readonly compilerFragments?: string[]; 217 | /** 218 | * The C or C++ standard to emulate. This field defaults to "c++17" and will only be used if 219 | * [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is set. 220 | */ 221 | readonly standard?: "c89" | "c99" | "c11" | "c17" | "c++98" | "c++03" | "c++11" | "c++14" | "c++17" | "c++20" | "c++23" | "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu++98" | "gnu++03" | "gnu++11" | "gnu++14" | "gnu++17" | "gnu++20" | "gnu++23"; 222 | /** 223 | * The version of the Windows SDK that should be used. This field defaults to the latest Windows SDK 224 | * installed on the PC and will only be used if [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) 225 | * is set and the compiler is capable of targeting Windows. 226 | */ 227 | readonly windowsSdkVersion?: string; 228 | } 229 | /** 230 | * The interface provided by the C/C++ extension during activation. 231 | * It is recommended to use the helper function [getCppToolsApi](#getCppToolsApi) instead 232 | * of querying the extension instance directly. 233 | */ 234 | export interface CppToolsExtension { 235 | /** 236 | * Get an API object. 237 | * @param version The desired version. 238 | */ 239 | getApi(version: Version): CppToolsApi; 240 | } 241 | /** 242 | * Helper function to get the CppToolsApi from the cpptools extension. 243 | * @param version The desired API version 244 | * @example 245 | ``` 246 | import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools'; 247 | 248 | let api: CppToolsApi|undefined = await getCppToolsApi(Version.v1); 249 | if (api) { 250 | // Inform cpptools that a custom config provider 251 | // will be able to service the current workspace. 252 | api.registerCustomConfigurationProvider(provider); 253 | 254 | // Do any required setup that the provider needs. 255 | 256 | // Notify cpptools that the provider is ready to 257 | // provide IntelliSense configurations. 258 | api.notifyReady(provider); 259 | } 260 | // Dispose of the 'api' in your extension's 261 | // deactivate() method, or whenever you want to 262 | // unregister the provider. 263 | ``` 264 | */ 265 | export declare function getCppToolsApi(version: Version): Promise; 266 | -------------------------------------------------------------------------------- /out/api.js: -------------------------------------------------------------------------------- 1 | /* -------------------------------------------------------------------------------------------- 2 | * Copyright (c) Microsoft Corporation. All rights reserved. 3 | * Licensed under the MIT license. 4 | * ------------------------------------------------------------------------------------------ */ 5 | 'use strict'; 6 | var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) { 7 | function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); } 8 | return new (P || (P = Promise))(function (resolve, reject) { 9 | function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } } 10 | function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } } 11 | function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); } 12 | step((generator = generator.apply(thisArg, _arguments || [])).next()); 13 | }); 14 | }; 15 | Object.defineProperty(exports, "__esModule", { value: true }); 16 | exports.getCppToolsApi = exports.Version = void 0; 17 | const vscode = require("vscode"); 18 | /** 19 | * API version information. 20 | */ 21 | var Version; 22 | (function (Version) { 23 | Version[Version["v0"] = 0] = "v0"; 24 | Version[Version["v1"] = 1] = "v1"; 25 | Version[Version["v2"] = 2] = "v2"; 26 | Version[Version["v3"] = 3] = "v3"; 27 | Version[Version["v4"] = 4] = "v4"; 28 | Version[Version["v5"] = 5] = "v5"; 29 | Version[Version["v6"] = 6] = "v6"; 30 | Version[Version["latest"] = 6] = "latest"; 31 | })(Version = exports.Version || (exports.Version = {})); 32 | /** 33 | * Check if an object satisfies the contract of the CppToolsExtension interface. 34 | */ 35 | function isCppToolsExtension(extension) { 36 | return extension && extension.getApi; 37 | } 38 | /** 39 | * Check if an object satisfies the contract of the first version of the CppToolsApi. 40 | * (The first release of the API only had two functions) 41 | */ 42 | function isLegacyCppToolsApi(api) { 43 | return api && api.registerCustomConfigurationProvider && api.didChangeCustomConfiguration; 44 | } 45 | /** 46 | * Helper function to get the CppToolsApi from the cpptools extension. 47 | * @param version The desired API version 48 | * @example 49 | ``` 50 | import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools'; 51 | 52 | let api: CppToolsApi|undefined = await getCppToolsApi(Version.v1); 53 | if (api) { 54 | // Inform cpptools that a custom config provider 55 | // will be able to service the current workspace. 56 | api.registerCustomConfigurationProvider(provider); 57 | 58 | // Do any required setup that the provider needs. 59 | 60 | // Notify cpptools that the provider is ready to 61 | // provide IntelliSense configurations. 62 | api.notifyReady(provider); 63 | } 64 | // Dispose of the 'api' in your extension's 65 | // deactivate() method, or whenever you want to 66 | // unregister the provider. 67 | ``` 68 | */ 69 | function getCppToolsApi(version) { 70 | return __awaiter(this, void 0, void 0, function* () { 71 | let cpptools = vscode.extensions.getExtension("ms-vscode.cpptools"); 72 | let extension = undefined; 73 | let api = undefined; 74 | if (cpptools) { 75 | if (!cpptools.isActive) { 76 | try { 77 | // activate may throw if VS Code is shutting down. 78 | extension = yield cpptools.activate(); 79 | } 80 | catch (_a) { 81 | } 82 | } 83 | else { 84 | extension = cpptools.exports; 85 | } 86 | if (isCppToolsExtension(extension)) { 87 | // ms-vscode.cpptools > 0.17.5 88 | try { 89 | api = extension.getApi(version); 90 | } 91 | catch (err) { 92 | // Unfortunately, ms-vscode.cpptools [0.17.6, 0.18.1] throws a RangeError if you specify a version greater than v1. 93 | // These versions of the extension will not be able to act on the newer interface and v2 is a superset of v1, so we can safely fall back to v1. 94 | let e = err; 95 | if (e && e.message && e.message.startsWith("Invalid version")) { 96 | api = extension.getApi(Version.v1); 97 | } 98 | } 99 | if (version !== Version.v1) { 100 | if (!api.getVersion) { 101 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version 1 instead.`); 102 | } 103 | else if (version !== api.getVersion()) { 104 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version ${api.getVersion()} instead.`); 105 | } 106 | } 107 | } 108 | else if (isLegacyCppToolsApi(extension)) { 109 | // ms-vscode.cpptools version 0.17.5 110 | api = extension; 111 | if (version !== Version.v0) { 112 | console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in version 0.17.5 of the cpptools extension. Using version 0 instead.`); 113 | } 114 | } 115 | else { 116 | console.warn('[vscode-cpptools-api] No cpptools API was found.'); 117 | } 118 | } 119 | else { 120 | console.warn('[vscode-cpptools-api] C/C++ extension is not installed'); 121 | } 122 | return api; 123 | }); 124 | } 125 | exports.getCppToolsApi = getCppToolsApi; 126 | -------------------------------------------------------------------------------- /out/testApi.d.ts: -------------------------------------------------------------------------------- 1 | import { CppToolsApi, CppToolsExtension, Version } from './api'; 2 | import * as vscode from 'vscode'; 3 | /** 4 | * The interface provided by the C/C++ extension during activation. [CppToolsExtension](#CppToolsExtension) 5 | * is also castable to [CppToolsTestExtension](#CppToolsTestExtension) 6 | */ 7 | export interface CppToolsTestExtension extends CppToolsExtension { 8 | /** 9 | * Get an API object. 10 | * @param version The desired version. 11 | */ 12 | getTestApi(version: Version): CppToolsTestApi; 13 | } 14 | /** 15 | * An interface to grant CustomConfigurationProvider extensions access to a test hook that 16 | * lets tests synchronize with the C/C++ extension. 17 | */ 18 | export interface CppToolsTestApi extends CppToolsApi { 19 | /** 20 | * Get the test hook that will allow the test to register for notifications from the C/C++ 21 | * extension. 22 | */ 23 | getTestHook(): CppToolsTestHook; 24 | } 25 | /** 26 | * An interface to allow tests to synchronize with the C/C++ extension 27 | */ 28 | export interface CppToolsTestHook extends vscode.Disposable { 29 | /** 30 | * [Deprecated] Fires when the Tag Parser or IntelliSense engine's status changes. 31 | */ 32 | readonly StatusChanged: vscode.Event; 33 | /** 34 | * Fires when the status of the Tag Parser or IntelliSense engine changes for an active document. 35 | */ 36 | readonly IntelliSenseStatusChanged: vscode.Event; 37 | } 38 | /** 39 | * Tag Parser or IntelliSense status codes. 40 | */ 41 | export declare enum Status { 42 | TagParsingBegun = 1, 43 | TagParsingDone = 2, 44 | IntelliSenseCompiling = 3, 45 | IntelliSenseReady = 4, 46 | Idle = 5 47 | } 48 | /** 49 | * Information about the status of Tag Parser or IntelliSense for an active document. 50 | */ 51 | export interface IntelliSenseStatus { 52 | status: Status; 53 | filename?: string; 54 | } 55 | export declare function getCppToolsTestApi(version: Version): Promise; 56 | -------------------------------------------------------------------------------- /out/testApi.js: -------------------------------------------------------------------------------- 1 | /* -------------------------------------------------------------------------------------------- 2 | * Copyright (c) Microsoft Corporation. All rights reserved. 3 | * Licensed under the MIT license. 4 | * ------------------------------------------------------------------------------------------ */ 5 | 'use strict'; 6 | var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) { 7 | function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); } 8 | return new (P || (P = Promise))(function (resolve, reject) { 9 | function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } } 10 | function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } } 11 | function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); } 12 | step((generator = generator.apply(thisArg, _arguments || [])).next()); 13 | }); 14 | }; 15 | Object.defineProperty(exports, "__esModule", { value: true }); 16 | exports.getCppToolsTestApi = exports.Status = void 0; 17 | const api_1 = require("./api"); 18 | const vscode = require("vscode"); 19 | /** 20 | * Tag Parser or IntelliSense status codes. 21 | */ 22 | var Status; 23 | (function (Status) { 24 | Status[Status["TagParsingBegun"] = 1] = "TagParsingBegun"; 25 | Status[Status["TagParsingDone"] = 2] = "TagParsingDone"; 26 | Status[Status["IntelliSenseCompiling"] = 3] = "IntelliSenseCompiling"; 27 | Status[Status["IntelliSenseReady"] = 4] = "IntelliSenseReady"; 28 | Status[Status["Idle"] = 5] = "Idle"; 29 | })(Status = exports.Status || (exports.Status = {})); 30 | function isCppToolsTestExtension(extension) { 31 | return extension.getTestApi !== undefined; 32 | } 33 | function getCppToolsTestApi(version) { 34 | return __awaiter(this, void 0, void 0, function* () { 35 | let cpptools = vscode.extensions.getExtension("ms-vscode.cpptools"); 36 | let extension; 37 | let api; 38 | if (cpptools) { 39 | if (!cpptools.isActive) { 40 | extension = yield cpptools.activate(); 41 | } 42 | else { 43 | extension = cpptools.exports; 44 | } 45 | if (isCppToolsTestExtension(extension)) { 46 | // ms-vscode.cpptools > 0.17.5 47 | try { 48 | api = extension.getTestApi(version); 49 | } 50 | catch (err) { 51 | // Unfortunately, ms-vscode.cpptools [0.17.6, 0.18.1] throws a RangeError if you specify a version greater than v1. 52 | // These versions of the extension will not be able to act on the newer interface and v2 is a superset of v1, so we can safely fall back to v1. 53 | let e = err; 54 | if (e.message && e.message.startsWith("Invalid version")) { 55 | api = extension.getTestApi(api_1.Version.v1); 56 | } 57 | } 58 | if (version !== api_1.Version.v1) { 59 | if (!api.getVersion) { 60 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in the current version of the cpptools extension. Using version 1 instead.`); 61 | } 62 | else if (version !== api.getVersion()) { 63 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in the current version of the cpptools extension. Using version ${api.getVersion()} instead.`); 64 | } 65 | } 66 | } 67 | else { 68 | // ms-vscode.cpptools version 0.17.5 69 | api = extension; 70 | if (version !== api_1.Version.v0) { 71 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in version 0.17.5 of the cpptools extension. Using version 0 instead.`); 72 | } 73 | } 74 | } 75 | else { 76 | console.warn("C/C++ extension is not installed"); 77 | } 78 | return api; 79 | }); 80 | } 81 | exports.getCppToolsTestApi = getCppToolsTestApi; 82 | -------------------------------------------------------------------------------- /package-lock.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "vscode-cpptools", 3 | "version": "6.3.0", 4 | "lockfileVersion": 3, 5 | "requires": true, 6 | "packages": { 7 | "": { 8 | "name": "vscode-cpptools", 9 | "version": "6.3.0", 10 | "license": "MIT", 11 | "devDependencies": { 12 | "@types/node": "^14.14.16", 13 | "@types/vscode": "1.52.0", 14 | "typescript": "^4.1.3" 15 | }, 16 | "engines": { 17 | "vscode": "^1.22.0" 18 | } 19 | }, 20 | "node_modules/@types/node": { 21 | "version": "14.18.63", 22 | "resolved": "https://pkgs.dev.azure.com/azure-public/VisualCpp/_packaging/cpp_PublicPackages/npm/registry/@types/node/-/node-14.18.63.tgz", 23 | "integrity": "sha1-F4j6jag427X56plLg0J4IF22yis=", 24 | "dev": true, 25 | "license": "MIT" 26 | }, 27 | "node_modules/@types/vscode": { 28 | "version": "1.52.0", 29 | "resolved": "https://pkgs.dev.azure.com/azure-public/VisualCpp/_packaging/cpp_PublicPackages/npm/registry/@types/vscode/-/vscode-1.52.0.tgz", 30 | "integrity": "sha1-YZF5aN1AOTISf8QASiH9jWnk9hw=", 31 | "dev": true, 32 | "license": "MIT" 33 | }, 34 | "node_modules/typescript": { 35 | "version": "4.9.5", 36 | "resolved": "https://pkgs.dev.azure.com/azure-public/VisualCpp/_packaging/cpp_PublicPackages/npm/registry/typescript/-/typescript-4.9.5.tgz", 37 | "integrity": "sha1-CVl5+bzA0J2jJNWNA86Pg3TL5lo=", 38 | "dev": true, 39 | "license": "Apache-2.0", 40 | "bin": { 41 | "tsc": "bin/tsc", 42 | "tsserver": "bin/tsserver" 43 | }, 44 | "engines": { 45 | "node": ">=4.2.0" 46 | } 47 | } 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "vscode-cpptools", 3 | "version": "6.3.0", 4 | "description": "Public API for vscode-cpptools", 5 | "typings": "./out/api.d.ts", 6 | "main": "./out/api.js", 7 | "engines": { 8 | "vscode": "^1.22.0" 9 | }, 10 | "devDependencies": { 11 | "@types/node": "^14.14.16", 12 | "@types/vscode": "1.52.0", 13 | "typescript": "^4.1.3" 14 | }, 15 | "scripts": { 16 | "compile": "tsc -p ./" 17 | }, 18 | "keywords": [ 19 | "vscode", 20 | "cpptools" 21 | ], 22 | "repository": { 23 | "type": "git", 24 | "url": "git+https://github.com/Microsoft/vscode-cpptools-api.git" 25 | }, 26 | "bugs": { 27 | "url": "https://github.com/Microsoft/vscode-cpptools-api/issues" 28 | }, 29 | "author": "Microsoft Corporation", 30 | "publisher": "ms-vscode", 31 | "license": "MIT" 32 | } 33 | -------------------------------------------------------------------------------- /testApi.ts: -------------------------------------------------------------------------------- 1 | /* -------------------------------------------------------------------------------------------- 2 | * Copyright (c) Microsoft Corporation. All rights reserved. 3 | * Licensed under the MIT license. 4 | * ------------------------------------------------------------------------------------------ */ 5 | 'use strict'; 6 | 7 | import { CppToolsApi, CppToolsExtension, Version } from './api'; 8 | import * as vscode from 'vscode'; 9 | 10 | /** 11 | * The interface provided by the C/C++ extension during activation. [CppToolsExtension](#CppToolsExtension) 12 | * is also castable to [CppToolsTestExtension](#CppToolsTestExtension) 13 | */ 14 | export interface CppToolsTestExtension extends CppToolsExtension { 15 | /** 16 | * Get an API object. 17 | * @param version The desired version. 18 | */ 19 | getTestApi(version: Version): CppToolsTestApi; 20 | } 21 | 22 | /** 23 | * An interface to grant CustomConfigurationProvider extensions access to a test hook that 24 | * lets tests synchronize with the C/C++ extension. 25 | */ 26 | export interface CppToolsTestApi extends CppToolsApi { 27 | /** 28 | * Get the test hook that will allow the test to register for notifications from the C/C++ 29 | * extension. 30 | */ 31 | getTestHook(): CppToolsTestHook; 32 | } 33 | 34 | /** 35 | * An interface to allow tests to synchronize with the C/C++ extension 36 | */ 37 | export interface CppToolsTestHook extends vscode.Disposable { 38 | /** 39 | * [Deprecated] Fires when the Tag Parser or IntelliSense engine's status changes. 40 | */ 41 | readonly StatusChanged: vscode.Event; 42 | 43 | /** 44 | * Fires when the status of the Tag Parser or IntelliSense engine changes for an active document. 45 | */ 46 | readonly IntelliSenseStatusChanged: vscode.Event; 47 | } 48 | 49 | /** 50 | * Tag Parser or IntelliSense status codes. 51 | */ 52 | export enum Status { 53 | TagParsingBegun = 1, 54 | TagParsingDone = 2, 55 | IntelliSenseCompiling = 3, 56 | IntelliSenseReady = 4, 57 | Idle = 5 58 | } 59 | 60 | /** 61 | * Information about the status of Tag Parser or IntelliSense for an active document. 62 | */ 63 | export interface IntelliSenseStatus { 64 | status: Status; 65 | filename?: string; 66 | } 67 | 68 | function isCppToolsTestExtension(extension: CppToolsTestApi | CppToolsTestExtension): extension is CppToolsTestExtension { 69 | return (extension).getTestApi !== undefined; 70 | } 71 | 72 | export async function getCppToolsTestApi(version: Version): Promise { 73 | let cpptools: vscode.Extension | undefined = vscode.extensions.getExtension("ms-vscode.cpptools"); 74 | let extension: CppToolsTestApi | CppToolsTestExtension; 75 | let api: CppToolsTestApi | undefined; 76 | 77 | if (cpptools) { 78 | if (!cpptools.isActive) { 79 | extension = await cpptools.activate(); 80 | } else { 81 | extension = cpptools.exports; 82 | } 83 | 84 | if (isCppToolsTestExtension(extension)) { 85 | // ms-vscode.cpptools > 0.17.5 86 | try { 87 | api = extension.getTestApi(version); 88 | } catch (err) { 89 | // Unfortunately, ms-vscode.cpptools [0.17.6, 0.18.1] throws a RangeError if you specify a version greater than v1. 90 | // These versions of the extension will not be able to act on the newer interface and v2 is a superset of v1, so we can safely fall back to v1. 91 | let e: RangeError = err; 92 | if (e.message && e.message.startsWith("Invalid version")) { 93 | api = extension.getTestApi(Version.v1); 94 | } 95 | } 96 | 97 | if (version !== Version.v1) { 98 | if (!api.getVersion) { 99 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in the current version of the cpptools extension. Using version 1 instead.`); 100 | } else if (version !== api.getVersion()) { 101 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in the current version of the cpptools extension. Using version ${api.getVersion()} instead.`); 102 | } 103 | } 104 | } else { 105 | // ms-vscode.cpptools version 0.17.5 106 | api = extension; 107 | if (version !== Version.v0) { 108 | console.warn(`vscode-cpptools-api version ${version} requested, but is not available in version 0.17.5 of the cpptools extension. Using version 0 instead.`); 109 | } 110 | } 111 | } else { 112 | console.warn("C/C++ extension is not installed"); 113 | } 114 | return api; 115 | } 116 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "module": "commonjs", 4 | "target": "es6", 5 | "noImplicitAny": false, 6 | "sourceMap": false, 7 | "outDir": "out", 8 | "declaration": true 9 | }, 10 | "exclude": [ 11 | "node_modules", 12 | "out" 13 | ] 14 | } --------------------------------------------------------------------------------