Generates VS Code configuration files for C/C++ projects using the GEA build system.
Configuration
First, run the Make Config File VS Code command (press ctrl/⌘ + shift + p) to generate a skeleton configuration in .vscode/gea_build_settings.json. This file should be committed to git. It will look something like this:
{
"defaultDefines": {
"RELEASE": "N",
"DEBUG": "Y"
},
"configurations": [
{
"name": "target (Release)",
"makefile": "target.mk",
"defines": {
"DEBUG": "N",
"RELEASE": "Y"
}
}
],
"version": 3,
"mode": "clangd",
"clangdAdditionalArguments": []
}
Makefiles and their associated settings using the GEA build system are listed under configurations. Each makefile will be used to (re-)generate configurations under .vscode/c_cpp_properties.json, .vscode/launch.json, and .vscode/tasks.json whenever a makefile changes. Since these files are machine-generated, it's best if these files are included in your .gitignore.
The name field is an optional field that allows you to override the name for the project as listed in the generated configuration. If name is not provided, the configuration name is taken from the makefile itself. This key is useful if you want to define separate release and debug configurations that need to have different names but are based on the same makefile.
The variables listed under defines are used when invoking the makefile to generate the configuration. Variables listed in defaultDefines are defined by default unless overridden by the defines for a specific target.
Configuration Versions
If version is specified as 1, the extension will generate configurations in place in .vscode/. This is compatible with older build tools, but can cause error messages in VS Code because the files are changed while being read and can cause selected configurations (debug and C/C++) to be reset when configurations are updated.
If version is specified as 2, the extension will generate configurations in a temporary folder and then copy them into .vscode/. This requires newer build tools, but avoids causing error messages or resetting selected configurations (debug and C/C++) when configurations are updated.
If version is specified as 3, clangd mode is supported in addition to cpptools (the Microsoft extension for C/C++ which was the only supported mode in previous versions). The clangd mode uses the clangd language server for code completion and diagnostics. This mode is recommended for new projects because it is significantly faster. Note that when clangd mode is used, a .clangd configuration file is generated that should be included in your .gitignore. When any version 3 mode is used, the .vscode/settings.json file is modified to ensures that the clangd and cpptools extensions safely coexist -- these changes should be committed to your project.
Including Non-Generated Configuration Items
Managed VS Code configuration files are removed before being generated. This means that any manually added contents will be removed. In order to include non-managed contents in the configuration files, you can create template files named .vscode/c_cpp_properties.gea-build-template.json, .vscode/launch.gea-build-template.json, or .vscode/tasks.gea-build-template.json. These templates will be used as the initial state of the corresponding VS Code configuration file before generation so they use the same schema as the corresponding configuration file.
When using the clangd backend, a .clangd configuration file is generated. To include non-managed contents in this file, you can create a template file named .clangd-template in the root of your workspace.
