From dceedf5fd53fc5bdfa52c247a5ce7c7b97536d62 Mon Sep 17 00:00:00 2001 From: mikeblome Date: Tue, 2 Jul 2019 10:23:04 -0700 Subject: [PATCH] new files --- docs/cpp/c-cpp-properties-schema-reference.md | 126 ++ docs/cpp/colorization-cpp.md | 534 ++++++++ docs/cpp/configure-intellisense-cpp.md | 65 + docs/cpp/cpp-debug.md | 153 +++ docs/cpp/cpp-ide.md | 118 ++ docs/cpp/cpp.md | 54 + docs/cpp/customize-default-settings-cpp.md | 109 ++ docs/cpp/enable-logging-cpp.md | 27 + docs/cpp/faq-cpp.md | 79 ++ .../intellisense-configurations-mac-clang.png | 3 + docs/cpp/images/cpp/Lightbulb.png | 3 + docs/cpp/images/cpp/c-cpp-properties-file.png | 3 + docs/cpp/images/cpp/compile_commands.png | 3 + docs/cpp/images/cpp/condbreak.png | 3 + docs/cpp/images/cpp/configure-includepath.png | 3 + docs/cpp/images/cpp/cpp-lightbulb.png | 3 + docs/cpp/images/cpp/filesearch.png | 3 + docs/cpp/images/cpp/include-errors.png | 3 + docs/cpp/images/cpp/languages_cpp.png | 3 + docs/cpp/images/cpp/launchjson.png | 3 + docs/cpp/images/cpp/lightbulb-suggestion.png | 3 + docs/cpp/images/cpp/list-members-cpp.png | 3 + docs/cpp/images/cpp/log-filter-selector.png | 3 + docs/cpp/images/cpp/logging-level.png | 3 + docs/cpp/images/cpp/parsing.png | 3 + docs/cpp/images/cpp/peekdefn.png | 3 + docs/cpp/images/cpp/threads.png | 3 + docs/cpp/images/cpp/workspacesearch.png | 3 + .../intellisense-configurations-mingw.png | 3 + docs/cpp/images/mingw/quickinfo.png | 3 + .../msvc/msvc-intellisense-configurations.png | 3 + .../wsl/intellisense-configurations-wsl.png | 3 + docs/cpp/intellisense-engine-cpp.md | 56 + docs/cpp/launch-json-reference.md | 249 ++++ docs/cpp/natvis.md | 1160 +++++++++++++++++ docs/cpp/pipe-transport.md | 67 + 36 files changed, 2866 insertions(+) create mode 100644 docs/cpp/c-cpp-properties-schema-reference.md create mode 100644 docs/cpp/colorization-cpp.md create mode 100644 docs/cpp/configure-intellisense-cpp.md create mode 100644 docs/cpp/cpp-debug.md create mode 100644 docs/cpp/cpp-ide.md create mode 100644 docs/cpp/cpp.md create mode 100644 docs/cpp/customize-default-settings-cpp.md create mode 100644 docs/cpp/enable-logging-cpp.md create mode 100644 docs/cpp/faq-cpp.md create mode 100644 docs/cpp/images/clang-mac/intellisense-configurations-mac-clang.png create mode 100644 docs/cpp/images/cpp/Lightbulb.png create mode 100644 docs/cpp/images/cpp/c-cpp-properties-file.png create mode 100644 docs/cpp/images/cpp/compile_commands.png create mode 100644 docs/cpp/images/cpp/condbreak.png create mode 100644 docs/cpp/images/cpp/configure-includepath.png create mode 100644 docs/cpp/images/cpp/cpp-lightbulb.png create mode 100644 docs/cpp/images/cpp/filesearch.png create mode 100644 docs/cpp/images/cpp/include-errors.png create mode 100644 docs/cpp/images/cpp/languages_cpp.png create mode 100644 docs/cpp/images/cpp/launchjson.png create mode 100644 docs/cpp/images/cpp/lightbulb-suggestion.png create mode 100644 docs/cpp/images/cpp/list-members-cpp.png create mode 100644 docs/cpp/images/cpp/log-filter-selector.png create mode 100644 docs/cpp/images/cpp/logging-level.png create mode 100644 docs/cpp/images/cpp/parsing.png create mode 100644 docs/cpp/images/cpp/peekdefn.png create mode 100644 docs/cpp/images/cpp/threads.png create mode 100644 docs/cpp/images/cpp/workspacesearch.png create mode 100644 docs/cpp/images/mingw/intellisense-configurations-mingw.png create mode 100644 docs/cpp/images/mingw/quickinfo.png create mode 100644 docs/cpp/images/msvc/msvc-intellisense-configurations.png create mode 100644 docs/cpp/images/wsl/intellisense-configurations-wsl.png create mode 100644 docs/cpp/intellisense-engine-cpp.md create mode 100644 docs/cpp/launch-json-reference.md create mode 100644 docs/cpp/natvis.md create mode 100644 docs/cpp/pipe-transport.md diff --git a/docs/cpp/c-cpp-properties-schema-reference.md b/docs/cpp/c-cpp-properties-schema-reference.md new file mode 100644 index 000000000..07ca70da7 --- /dev/null +++ b/docs/cpp/c-cpp-properties-schema-reference.md @@ -0,0 +1,126 @@ +--- +Order: 11 +Area: cpp +TOCTitle: c_cpp_properties.json reference +ContentId: EC1BA944-09B5-41EA-AAED-779A02C90C98 +PageTitle: c_cpp_properties.json reference +DateApproved: 06/25/2019 +MetaDescription: Schema reference for C++ project settings in Visual Studio Code. +--- +# c_cpp_properties.json Reference Guide + +See also: [Customizing Default Settings](customize-default-settings.md) + +## Example + +```json +{ + "env" : { + "myDefaultIncludePath": [ + "${workspaceFolder}", + "${workspaceFolder}/include" + ], + "myCompilerPath": "/usr/local/bin/gcc-7" + }, + "configurations": [ + { + "name": "Mac", + "intelliSenseMode": "clang-x64", + "includePath": [ "${myDefaultIncludePath}", "/another/path" ], + "macFrameworkPath": [ "/System/Library/Frameworks" ], + "defines": [ "FOO", "BAR=100" ], + "forcedInclude": [ "${workspaceFolder}/include/config.h" ], + "compilerPath": "/usr/bin/clang", + "cStandard": "c11", + "cppStandard": "c++17", + "compileCommands": "/path/to/compile_commands.json", + "browse": { + "path": [ "${workspaceFolder}" ], + "limitSymbolsToIncludedHeaders": true, + "databaseFilename": "" + } + } + ], + "version": 4 +} +``` + +## Top-level properties + +### env + +An array of user-defined variables that will be available for substitution in the configurations via the standard environment variable syntax: `${}` or `${env:}`. Strings and arrays of strings are accepted. + +### configurations + +An array of configuration objects that provide the IntelliSense engine with information about your project and your preferences. By default, the extension creates a configuration for you based on your operating system. You may also add additional configurations. + +### version + +We recommend you don't edit this field. It tracks the current version of the `c_cpp_properties.json` file so that the extension knows what properties and settings should be present and how to upgrade this file to the latest version. + +## Configuration properties + +### name + +A friendly name for the configuration. "Linux", "Mac", and "Win32" are special names that instruct the extension to load that configuration by default on the associated operating system unless additional configurations have been created. The status bar in VS Code will show you which configuration is active. You can also click on the label in the status bar to change the active configuration. + +### intelliSenseMode + +If `C_Cpp.intelliSenseEngine` is set to "Default" in your settings file, this property determines which mode the IntelliSense engine will run in. `msvc-x64` maps to Visual Studio mode with 64-bit pointer sizes. `clang-x64` maps to CLang mode with 64-bit pointer sizes. `gcc-x64` maps to GCC mode with 64-bit pointer sizes. Windows uses `msvc-x64` by default, macOS uses `clang-x64` by default, and Linux uses `gcc-x64` by default. + +### includePath + +If `C_Cpp.intelliSenseEngine` is set to "Default" in your settings file, this list of paths will be used by IntelliSense to search for headers included by your source files. This is basically the same as the list of paths you pass to your compiler with the `-I` switch. If a path ends with `/**`, the IntelliSense engine will do a recursive search for includes starting from that directory. If on Windows with Visual Studio installed, or if a compiler is specified in the `compilerPath` setting, it is not necessary to list the system include paths in this list. + +### macFrameworkPath + +If `C_Cpp.intelliSenseEngine` is set to "Default" in your settings file, this list of paths will be used by IntelliSense to search for framework headers included by your source files. This is basically the same as the list of paths you pass to your compiler with the `-F` switch; the IntelliSense engine will not do a recursive search in these paths for includes. + +### defines + +If `C_Cpp.intelliSenseEngine` is set to "Default" in your settings file, this list of preprocessor symbols will be used by IntelliSense during the compilation of your source files. This list is basically the same as the list of symbols you pass to your compiler with the `-D` switch. If on Windows with Visual Studio installed, or if a compiler is specified in the `compilerPath` setting, it is not necessary to list the system include paths in this list. + +### forcedInclude (optional) + +A list of files that should be included before any other characters in the source file are processed. Files are included in the order listed. + +### compilerPath (optional) + +The absolute path to the compiler you use to build your project. The extension will query the compiler to determine the system include paths and default defines to use for IntelliSense. + +Args can be added to modify the includes/defines used, for example `-nostdinc++`, `-m32`, `-fno-ms-extensions`, etc., but paths with spaces must be surrounded by double quotes (") if args are used. + +To disable automatic querying of system include paths and defines, set this value to the empty string (""). This is generally not recommended, but there are some cases where automatic querying of system includes and defines is undesirable. + +### cStandard + +The C standard revision to use for IntelliSense in your project. + +### cppStandard + +The C++ standard revision to use for IntelliSense in your project. + +### compileCommands (optional) + +If `C_Cpp.intelliSenseEngine` is set to "Default" in your settings file, the includes and defines discovered in this file will be used instead of the values set for `includePath` and `defines`. If the compile commands database does not contain an entry for the translation unit that corresponds to the file you opened in the editor, then a warning message will appear and the extension will use the `includePath` and `defines` settings instead. + +For more information about the file format, see the [Clang documentation](https://clang.llvm.org/docs/JSONCompilationDatabase.html). Some build systems, such as CMake, [simplify generating this file](https://cmake.org/cmake/help/v3.5/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html). + +### browse + +The set of properties used when `C_Cpp.intelliSenseEngine` is set to `Tag Parser" (also referred to as "fuzzy" IntelliSense, or the "browse" engine). These properties are also used by the Go To Definition/Declaration features, or when the "Default" IntelliSense engine is unable to resolve the #includes in your source files. + +### Browse properties + +### path + +This list of paths will be used by the Tag Parser to search for headers included by your source files. If omitted, `includePath` will be used as the `path`. The Tag Parser will automatically search all subfolders in these paths unless the path ends with a `/*` or `\*`. For example, `/usr/include` directs the Tag Parser to search the `include` folder and its subfolders for headers while `/usr/include/*` directs the Tag Parser not to look in any subfolders of `/usr/include`. + +### limitSymbolsToIncludedHeaders + +When true, the Tag Parser will only parse code files that have been directly or indirectly included by a source file in `${workspaceFolder}`. When false, the Tag Parser will parse all code files found in the paths specified in the **path** list. + +### databaseFilename + +When set, this instructs the extension to save the Tag Parser's symbol database somewhere other than the workspace's default storage location. If a relative path is specified, it will be made relative to the workspace's default storage location, not the workspace folder itself. The `${workspaceFolder}` variable can be used to specify a path relative to the workspace folder (for example, `${workspaceFolder}/.vscode/browse.vc.db`). diff --git a/docs/cpp/colorization-cpp.md b/docs/cpp/colorization-cpp.md new file mode 100644 index 000000000..734465300 --- /dev/null +++ b/docs/cpp/colorization-cpp.md @@ -0,0 +1,534 @@ +--- +Order: 10 +Area: cpp +TOCTitle: Enhanced Colorization +ContentId: 2C406EA6-87DC-4A2D-AEC2-90BAA491697C +PageTitle: Enhanced Colorization in Visual Studio Code C++ projects +DateApproved: 06/25/2019 +MetaDescription: How to customize semantic colorization of C++ code in Visual Studio Code. +--- + +# Enhanced Colorization + +The Visual Studio Code C/C++ extension now supports semantic colorization, when IntelliSense is enabled. Enhanced colorization can be enabled using the enhancedColorization setting: + +```json +"C_Cpp.enhancedColorization": "Enabled" +``` + +## Themes + +Colors can be associated using the existing support for theming and color customization in VS Code. Documentation on Themes in VS Code can be found [here](https://code.visualstudio.com/docs/getstarted/themes) + +Colors are associated with [TextMate scopes](https://macromates.com/manual/en/language_grammars#naming_conventions). + +## IntelliSense Tokens and Scopes + +| Token | Scope | +| ------------- |:-------------:| +| Class Template | entity.name.class.template | +| Enumerator | variable.other.enummember | +| Event (C++/CLI) | variable.other.event | +| Function | entity.name.function | +| Function Template | entity.name.function.template | +| Generic Type (C++/CLI) | entity.name.class.generic | +| Global Variable | variable.other.global | +| Identifier | entity.name | +| Label | entity.name.label | +| Local Variable | variable.other.local | +| Macro | entity.name.function.preprocessor | +| Member Field | variable.other.member | +| Member Function | entity.name.function.member | +| Member Operator | keyword.operator.member | +| Namespace | entity.name.type.namespace | +| New / Delete | keyword.operator.new | +| Operator Function | entity.name.function.operator | +| Parameter | variable.parameter | +| Property (C++/CLI) | variable.other.property | +| Reference Type (C++/CLI) | entity.name.class.reference | +| Static Member Field | variable.other.member.static | +| Static Member Function | entity.name.function.member.static | +| Type | entity.name.type | +| User-Defined Literal - Number | entity.name.user-defined-literal.number | +| User-Defined Literal - Raw | entity.name.user-defined-literal | +| User-Defined Literal - String | entity.name.user-defined-literal.string | +| Value Type (C++/CLI) | entity.name.class.value | + +Many of the tokens recognized by IntelliSense do not directly map to existing scopes in the VS Code's default C/C++ TextMate grammar, so are likely not colored by existing VS Code themes. + +## Customizing Colors in Settings + +Colors can also be overridden globally, in settings: + +```json + "editor.tokenColorCustomizations": { + "textMateRules": [ + { + "scope": "entity.name.type", + "settings": { + "foreground": "#FF0000", + "fontStyle": "italic bold underline" + } + } + ] + } +``` + +Or, overridden on a per-theme basis: + +```json + "editor.tokenColorCustomizations": { + "[Visual Studio Dark]": { + "textMateRules": [ + { + "scope": "entity.name.type", + "settings": { + "foreground": "#FF0000", + "fontStyle": "italic bold underline" + } + } + ] + } +``` + +Use the following to augment the Visual Studio Dark theme to match what Visual Studio would display for C++ files. + +```json + "editor.tokenColorCustomizations": { + "[Visual Studio Dark]": { + "textMateRules": [ + { + "scope": "entity.name", + "settings": { + "foreground": "#FFFFFF" + } + }, + { + "scope": "comment", + "settings": { + "foreground": "#57A64A" + } + }, + { + "scope": "keyword.control", + "settings": { + "foreground": "#569CD6" + } + }, + { + "scope": "keyword.control.directive", + "settings": { + "foreground": "#9B9B9B" + } + }, + { + "scope": "keyword.operator", + "settings": { + "foreground": "#B4B4B4" + } + }, + { + "scope": "variable", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "constant.numeric", + "settings": { + "foreground": "#B5CEA8" + } + }, + { + "scope": "string.quoted", + "settings": { + "foreground": "#D69D85" + } + }, + { + "scope": "comment.xml.doc", + "settings": { + "foreground": "#57A64A" + } + }, + { + "scope": "comment.xml.doc.tag", + "settings": { + "foreground": "#57A64A" + } + }, + { + "scope": "entity.name.function.preprocessor", + "settings": { + "foreground": "#BD63C5" + } + }, + { + "scope": "variable.other.enummember", + "settings": { + "foreground": "#B8D7A3" + } + }, + { + "scope": "variable.other.global", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "variable.other.local", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "variable.parameter", + "settings": { + "foreground": "#7F7F7F" + } + }, + { + "scope": "entity.name.type", + "settings": { + "foreground": "#4EC9B0" + } + }, + { + "scope": "entity.name.class.reference", + "settings": { + "foreground": "#4EC9B0" + } + }, + { + "scope": "entity.name.class.value", + "settings": { + "foreground": "#4EC9B0" + } + }, + { + "scope": "entity.name.function", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "entity.name.function.member", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "variable.other.member", + "settings": { + "foreground": "#DADADA" + } + }, + { + "scope": "entity.name.function.member.static", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "variable.other.member.static", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "variable.other.event", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "entity.name.class.template", + "settings": { + "foreground": "#4EC9B0" + } + }, + { + "scope": "entity.name.class.generic", + "settings": { + "foreground": "#4EC9B0" + } + }, + { + "scope": "entity.name.function.template", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "entity.name.type.namespace", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "entity.name.label", + "settings": { + "foreground": "#C8C8C8" + } + }, + { + "scope": "entity.name.user-defined-literal", + "settings": { + "foreground": "#DADADA" + } + }, + { + "scope": "entity.name.user-defined-literal.string", + "settings": { + "foreground": "#D69D85" + } + }, + { + "scope": "entity.name.user-defined-literal.number", + "settings": { + "foreground": "#B5CEA8" + } + }, + { + "scope": "entity.name.function.operator", + "settings": { + "foreground": "#B4B4B4" + } + }, + { + "scope": "keyword.operator.member", + "settings": { + "foreground": "#B4B4B4" + } + }, + { + "scope": "keyword.operator.new", + "settings": { + "foreground": "#569CD6" + } + }, + ] + } + } +``` + +Use the following to augment the Visual Studio Light theme to match what Visual Studio would display for C++ files. + +```json + "editor.tokenColorCustomizations": { + "[Visual Studio Light]": { + "textMateRules": [ + { + "scope": "entity.name", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "comment", + "settings": { + "foreground": "#008000" + } + }, + { + "scope": "keyword.control", + "settings": { + "foreground": "#0000FF" + } + }, + { + "scope": "keyword.control.directive", + "settings": { + "foreground": "#808080" + } + }, + { + "scope": "keyword.operator", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "constant.numeric", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "string.quoted", + "settings": { + "foreground": "#A31515" + } + }, + { + "scope": "comment.xml.doc", + "settings": { + "foreground": "#006400" + } + }, + { + "scope": "comment.xml.doc.tag", + "settings": { + "foreground": "#A9A9A9" + } + }, + { + "scope": "entity.name.function.preprocessor", + "settings": { + "foreground": "#6F0026" + } + }, + { + "scope": "variable.other.enummember", + "settings": { + "foreground": "#2F4F4F" + } + }, + { + "scope": "variable.other.global", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable.other.local", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable.parameter", + "settings": { + "foreground": "#808080" + } + }, + { + "scope": "entity.name.type", + "settings": { + "foreground": "#2B91AF" + } + }, + { + "scope": "entity.name.class.reference", + "settings": { + "foreground": "#2B91AF" + } + }, + { + "scope": "entity.name.class.value", + "settings": { + "foreground": "#2B91AF" + } + }, + { + "scope": "entity.name.function", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.function.member", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable.other.member", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.function.member.static", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable.other.member.static", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "variable.other.event", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.class.template", + "settings": { + "foreground": "#2B91AF" + } + }, + { + "scope": "entity.name.class.generic", + "settings": { + "foreground": "#2B91AF" + } + }, + { + "scope": "entity.name.function.template", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.type.namespace", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.label", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.user-defined-literal", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.user-defined-literal.string", + "settings": { + "foreground": "#A31515" + } + }, + { + "scope": "entity.name.user-defined-literal.number", + "settings": { + "foreground": "#000000" + } + }, + { + "scope": "entity.name.function.operator", + "settings": { + "foreground": "#008080" + } + }, + { + "scope": "keyword.operator.member", + "settings": { + "foreground": "#008080" + } + }, + { + "scope": "keyword.operator.new", + "settings": { + "foreground": "#0000FF" + } + }, + ] + } + } +``` diff --git a/docs/cpp/configure-intellisense-cpp.md b/docs/cpp/configure-intellisense-cpp.md new file mode 100644 index 000000000..c824720f8 --- /dev/null +++ b/docs/cpp/configure-intellisense-cpp.md @@ -0,0 +1,65 @@ +--- +Order: 8 +Area: cpp +TOCTitle: Configure includePath for better IntelliSense results +ContentId: 9CCD167C-0A19-4025-A06A-3A25D5601097 +PageTitle: Configure includePath for better IntelliSense results +DateApproved: 06/25/2019 +MetaDescription: Configure includePath for better IntelliSense results in C/C++ Visual Studio Code projects +--- + +# Configuring includePath for better IntelliSense results + +This page describes how to configure include paths for folders containing C or C++ files to get the full IntelliSense experience. If you're seeing the following message when opening a folder in VS Code, it means the C++ IntelliSense engine needs additional information about the paths in which your include files are located. + +![Configure includePath for better IntelliSense](images/cpp/configure-includepath.png) + +## Where are the include paths defined? + +The include paths are defined in the `includePath` setting in a file called `c_cpp_properties.json` located in the **.vscode** directory in the opened folder. + +You can create or open this file by either using the `C/Cpp: Edit Configurations` command in the command palette or by selecting `Edit "includePath" setting` in the light bulb menu (see the screenshot below). The quickest way to locate a light bulb is to scroll to the top of the source file and click on any green squiggle that shows up under a #include statement. + +![light bulb menu "Edit "includePath" setting"](images/cpp/light bulb.png) + + When a folder is opened, the extension attempts to locate your system headers based on your operating system, but it does not know about any other libraries that your project depends on. You can hover over the green squiggles or open the Problems window to understand which headers the IntelliSense engine is unable to open - sometimes it's the dependent headers that can't be located. + +![include error message](images/cpp/include-errors.png) + +## How to specify the include paths? + +You can specify the remaining paths using one of the techniques described below. + +### Use `compile_commands.json` file to supply includePaths and defines information + +The extension can get the information for `includePath` and `defines` from a **compile_commands.json** file, which can be autogenerated by many build systems such as CMake and Ninja. Look for the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac"), and set the `compileCommands` property in `c_cpp_properties.json` to the full path to your **compile_commands.json** file and the extension will use that instead of the `includes` and `defines` properties for IntelliSense. + +![use compileCommands setting](images/cpp/compile-commands.png) + +### Use the light bulb suggestions to autoresolve includePath + +The first thing to try is to leverage the light bulb path suggestions to autoresolve the include paths. When you open a folder, the extension will recursively search for potential include paths that match the header files your code is using based on the paths set by the `browse.path` setting in `c_cpp_properties.json`. Click on the green squiggles under #include statements and you'll see a light bulb offering suggestions of paths that will allow IntelliSense to resolve the included file. + +![light bulb suggestions](images/cpp/light bulb-suggestion.png) + +If you don't see path suggestions in the light bulb, try adding the root folder where the headers are likely located in to the `browse.path` setting in `c_cpp_properties.json`. This allows the extension to **recursively** search in these folders and offer more suggestions in the light bulb as the search process goes on. + +### Manually add include paths + +If none of the above fully resolves the paths, you could manually specify the paths to the headers that your project depends on in the `c_cpp_properties.json` file. Look for the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac"), and add your paths in the `includePath` setting and defines in the `defines` setting. For example, the following screenshot shows a snippet of the file specifying path for the Mac configuration. + +![c_cpp_properties file snippet](images/cpp/c-cpp-properties-file.png) + +## Verify the include paths are correctly resolved + +There are two ways to verify that the include paths are correctly resolved: + +1. The green squiggles in the source file are no longer showing +2. Error messages are cleared in the Problems window + +This indicates that the IntelliSense engine has got the include paths resolved so you can start enjoying the full IntelliSense for your C or C++ code for the current translation unit. You may still see errors on other files if they belong to a different translation unit that requires additional include paths to be configured. + +## See Also + +[IntelliSense engines](intellisense-engine-cpp.md) +[c_cpp_properties.json reference guide](c-cpp-properties-schema-reference.md) \ No newline at end of file diff --git a/docs/cpp/cpp-debug.md b/docs/cpp/cpp-debug.md new file mode 100644 index 000000000..7448536fd --- /dev/null +++ b/docs/cpp/cpp-debug.md @@ -0,0 +1,153 @@ +--- +Order: 5 +Area: languages +TOCTitle: C++ +ContentId: 9150091A-6F3A-46B9-881B-B8FD788FA705 +PageTitle: Debug C++ code in Visual Studio Code +DateApproved: 06/20/2019 +MetaDescription: How to debug C++ programs in Visual Studio Code. +--- + +## Debug C++ code in Visual Studio Code + +After you have set up the basics of your debugging environment as specified in the configuration tutorials for each target compiler/platform, you can learn more details about debugging C/C++ in this section. + +VS Code supports the following debuggers for C/C++ depending on the operating system you are using: + +* **Linux**: GDB +* **macOS**: LLDB or GDB +* **Windows**: the Visual Studio Windows Debugger or GDB (using Cygwin or MinGW) + +### Windows Debugging with GDB + +You can debug Windows applications created using Cygwin or MinGW by using VS Code. To use Cygwin or MinGW debugging features, the debugger path must be set manually in the launch configuration (`launch.json`). To debug your Cygwin or MinGW application, add the `miDebuggerPath` property and set its value to the location of the corresponding gdb.exe for your Cygwin or MinGW environment. + +For example: + +```json + "miDebuggerPath": "c:\\mingw\\bin\\gdb.exe" +``` + +Cygwin/MinGW debugging on Windows supports both attach and launch debugging scenarios. + +To learn more, see [Configuring launch.json for C/C++ debugging](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md). + +If you are debugging with GDB on Windows, see [Windows Debugging with MinGW64](/docs/cpp/config-mingw.md). + +### Conditional Breakpoints + +Conditional breakpoints enable you to break execution on a particular line of code only when the value of the condition is true. To set a conditional breakpoint, right-click on an existing breakpoint and select **Edit Breakpoint**. This opens a small peek window where you can enter the condition that must evaluate to true in order for the breakpoint to be hit during debugging. + +![A conditional break](images/cpp/condbreak.png) + +In the editor, conditional breakpoints are indicated by a breakpoint symbol that has a black equals sign inside of it. You can place the cursor over a conditional breakpoint to show its condition. + +### Function Breakpoints + +Function breakpoints enable you to break execution at the beginning of a function instead of on a particular line of code. To set a function breakpoint, on the **Debug** pane right-click inside the **Breakpoints** section, then choose **Add Function Breakpoint** and enter the name of the function on which you want to break execution. + +### Expression Evaluation + +VS Code supports expression evaluation in several contexts: + +* You can type an expression into the **Watch** section of the **Debug** panel and it will be evaluated each time a breakpoint is hit. +* You can type an expression into the **Debug Console** and it will be evaluated only once. +* You can evaluate any expression that appears in your code while you're stopped at a breakpoint. + +Expressions in the **Watch** section take effect in the application being debugged; an expression that modifies the value of a variable will modify that variable for the duration of the program. + +### Multi-threaded Debugging + +The C/C++ extension for VS Code has the ability to debug multi-threaded programs. All threads and their call stacks appear in the **Call Stack** section: + +![Multi-threaded process](images/cpp/threads.png) + +### Memory Dump Debugging + +The C/C++ extension for VS Code also has the ability to debug memory dumps. To debug a memory dump, open your `launch.json` file and add the `coreDumpPath` (for GDB or LLDB) or `dumpPath` (for the Visual Studio Windows Debugger) property to the **C++ Launch** configuration, set its value to be a string containing the path to the memory dump. This will even work for x86 programs being debugged on an x64 machine. + +### Additional Symbols + +If there are additional directories where the debugger can find symbol files (for example, `.pdb` files for the Visual Studio Windows Debugger), they can be specified by adding the `additionalSOLibSearchPath` (for GDB or LLDB) or `symbolSearchPath` (for the Visual Studio Windows Debugger). + +For example: + +```json + "additionalSOLibSearchPath": "/path/to/symbols;/another/path/to/symbols" +``` + +or + +```json + "symbolSearchPath": "C:\\path\\to\\symbols;C:\\another\\path\\to\\symbols" +``` + +### Locate source files + +The source file location can be changed if the source files are not located in the compilation location. This is done by simple replacement pairs added in the `sourceFileMap` section. The first match in this list will be used. + +For example: + +```json +"sourceFileMap": { + "/build/gcc-4.8-fNUjSI/gcc-4.8-4.8.4/build/i686-linux-gnu/libstdc++-v3/include/i686-linux-gnu": "/usr/include/i686-linux-gnu/c++/4.8", + "/build/gcc-4.8-fNUjSI/gcc-4.8-4.8.4/build/i686-linux-gnu/libstdc++-v3/include": "/usr/include/c++/4.8" +} +``` + +### GDB, LLDB, and MI Commands (GDB/LLDB) + +For the `C++ (GDB/LLDB)` debugging environment, you can execute GDB, LLDB and MI commands directly through the debug console with the `-exec` command, but be careful, executing commands directly in the debug console is untested and might crash VS Code in some cases. + +### Other Debugging Features + +* Unconditional breakpoints +* Watch window +* Call stack +* Stepping + + For more information on debugging with VS Code, see this introduction to [debugging in VS Code](/docs/editor/debugging.md). + +## Known Limitations + +### Symbols and Code Navigation + +All platforms: + +* Because the extension doesn't parse function bodies, **Peek Definition** and **Go to Definition** don't work for symbols defined inside the body of a function. + +### Debugging + +Windows: + +* GDB on Cygwin and MinGW cannot break a running process. To set a breakpoint when the application is running (not stopped under the debugger), or to pause the application being debugged, press `kbstyle(Ctrl-C)` in the application's terminal. +* GDB on Cygwin cannot open core dumps. + +Linux: + +* GDB needs elevated permissions to attach to a process. When using *attach to process*, you need to provide your password before the debugging session can begin. + +macOS: + +* LLDB: + * When debugging with LLDB, if the Terminal window is closed while in break mode, debugging does not stop. Debugging can be stopped by pressing the **Stop** button. + * When debugging is stopped the Terminal window is not closed. +* GDB: + * Additional manual install steps are required to use GDB on macOS. See _Manual Installation of GDB for OS X_ in the [README](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + * When attaching to a process with GDB, the application being debugged cannot be interrupted. GDB will only bind breakpoints set while the application is not running (either before attaching to the application, or while the application is in a stopped state). This is due to [a bug in GDB](https://sourceware.org/bugzilla/show_bug.cgi?id=20035). + * Core dumps cannot be loaded when debugging with GDB because GDB [does not support the core dump format used in macOS](https://www.sourceware.org/ml/gdb/2014-01/msg00036.html). + * When attached to a process with GDB, break-all will end the process. + +## Next steps + +Read on to find out about: + +* [Configure VS Code for Windows Subsystem for Linux](/docs/cpp/config-wsl.md) +* [Configure VS Code for Mingw-w64 and GCC](/docs/cpp/config-mingw.md) +* [Configure VS Code for macOS](/docs/cpp/config-clang-mac.md) +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful Visual Studio Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Tasks](/docs/editor/tasks.md) - use tasks to build your project and more +* [Debugging](/docs/editor/debugging.md) - find out about the Visual Studio Code debugger + +If you have any other questions or run into any issues, please file an issue on [GitHub](https://github.com/Microsoft/vscode-cpptools/issues). diff --git a/docs/cpp/cpp-ide.md b/docs/cpp/cpp-ide.md new file mode 100644 index 000000000..5de9b70be --- /dev/null +++ b/docs/cpp/cpp-ide.md @@ -0,0 +1,118 @@ +--- +Order: 6 +Area: cpp +TOCTitle: C++ +ContentId: 61D63E54-67E2-4743-B5CB-C6E7F582982A +PageTitle: Edit and navigate C++ code in Visual Studio Code +DateApproved: 06/25/2019 +MetaDescription: How to edit and navigate C++ source files in Visual Studio Code. +--- +# Edit and navigate C++ code in Visual Studio Code + +This topic provides a quick overview of general C/C++ editor features, as well as some that are specific to C/C++. For more information about editing in VS Code, see [Basic Editing](/docs/editor/codebasics.md) and [Code Navigation](../editor/editingevolved.md). + +The C/C++ extension supports [Remote Development](../remote/remote-overview.md). + +## Editing features + +The C/C++ extension for VS Code has many features that help you write code, understand it, and navigate around in your source files. To provide the best experience, the extension needs to know where it can find each header file referenced in your code. By default, the extension searches the current source directory, its sub-directories, and some platform-specific locations. If a referenced header file can't be found, VS Code displays a green squiggle underneath each #include directive that references it. + +To specify additional include directories to be searched, place your cursor over any #include directive that displays a green squiggle, then click the lightbulb action when it appears. This opens the file `c_cpp_properties.json` for editing; here you can specify additional include directories for each platform configuration individually by adding more directories to the 'browse.path' property. + +## List members + +When you type a member access symbol (`.` or `->`) the editor will display a list of members. As you type additional letters, the list is filtered in real time: + +![List members](images/cpp/list-members-cpp.png) + +### Code Formatting + +The C/C++ extension for Visual Studio Code supports source code formatting using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) which is included with the extension. + +You can format an entire file with **Format Document** (`kb(editor.action.formatDocument)`) or just the current selection with **Format Selection** (`kb(editor.action.formatSelection)`) in right-click context menu. You can also configure auto-formatting with the following [settings](/docs/getstarted/settings.md): + +* `editor.formatOnSave` - to format when you save your file. +* `editor.formatOnType` - to format as you type (triggered on the `kbstyle(;)` character). + +By default, the clang-format style is set to "file" which means it looks for a `.clang-format` file inside your workspace. If the `.clang-format` file is found, formatting is applied according to the settings specified in the file. If no `.clang-format` file is found in your workspace, formatting is applied based on a default style specified in the `C_Cpp.clang_format_fallbackStyle` [setting](/docs/getstarted/settings.md) instead. Currently, the default formatting style is "Visual Studio" which is an approximation of the default code formatter in Visual Studio. + +The Visual Studio clang-format style is not yet an official clang-format style but it implies the following clang-format settings: + +```json +UseTab: (VS Code current setting) +IndentWidth: (VS Code current setting) +BreakBeforeBraces: AllMan +AllowShortIfStatementsOnASingleLine: false +IndentCaseLabels: false +ColumnLimit: 0 +``` + +To use a different version of clang-format than the one that ships with the extension, change the `C_Cpp.clang_format_path` [setting](/docs/getstarted/settings.md) to the path where the clang-format binary is installed. + +For example, on the Windows platform: + +```json + "C_Cpp.clang_format_path": "C:\\Program Files (x86)\\LLVM\\bin\\clang-format.exe" +``` + +### Quick Info + +You can hover over a symbol to see an inline view of its definition: + +![Quick info](images/mingw/quickinfo.png) + +### Peek Definition + +The **Peek Definition** feature displays a few lines of code near the definition inside a *peek window*, so that you don't have to navigate away from your current location. + +To peek at a symbol's definition, place your cursor on the symbol anywhere it's used in your source code and then press `kb(editor.action.peekDefinition)`. Alternatively, you can choose **Peek Definition** from the context menu (right-click, then choose **Peek Definition**). + +![Peek definition](images/cpp/peekdefn.png) + +Currently, the C/C++ extension doesn't parse code in a way that helps it distinguish between competing definitions based on how the symbol is used. These competing definitions arise when the symbol defines different things in different contexts, such as occurs with overloaded functions, classes and their constructors, and other situations. When this happens, each of the competing definitions is listed in the right-hand side of the peek window with the source code of the current selection displayed on the left. + +With the peek window open, you browse the list of competing definitions to find the one you're interested in. If you want to navigate to the location of one of the definitions just double-click the definition you're interested in, or by double-clicking anywhere in the source code displayed on the left-hand side of the peek window. + +## Navigate Code + +The source code navigation features provided by the C/C++ extension are powerful tools for understanding and getting around in your codebase. These features are powered by tags stored in a local database of symbol information. With the C/C++ extension installed, this database is generated whenever a folder containing C++ source code files is loaded into VS Code. The database icon appears next to the active configuration name ("Win32" in the image below) while the tag-parser is generating this information. + +![The platform indicator during tag parsing](images/cpp/parsing.png) + +The icon disappears when all the symbols have been tagged. + +### Search for symbols + +You can search for symbols in the current file or workspace to navigate your code more quickly. + +To search for a symbol in the current file, press `kb(workbench.action.gotoSymbol)`, then enter the name of the symbol you're looking for. A list of potential matches will appear; it is filtered as you type. Choose from the list of matches to navigate to its location. + +![Searching the current file](images/cpp/filesearch.png) + +To search for a symbol in the current workspace, press `kb(workbench.action.showAllSymbols)`, then enter the name of the symbol. A list of potential matches will appear as before. If you choose a match that was found in a file that's not already open, the file will be opened before navigating to the match's location. + +![Searching in your workspace](images/cpp/workspacesearch.png) + +You can also search for symbols by accessing these commands through the **Command Palette**. Use **Quick Open** (`kb(workbench.action.quickOpen)`) then enter the '@' command to search the current file, or the '#' command to search the current workspace. `kb(workbench.action.gotoSymbol)` and `kb(workbench.action.showAllSymbols)` are just shortcuts for the '@' and '#' commands, so everything works the same. + +### Go to Definition + +You can also quickly navigate to where a symbol is defined by using the **Go to Definition** feature. + +To go to a symbol's definition, place your cursor on the symbol anywhere it is used in your source code and then press `kb(editor.action.revealDefinition)`. Or, choose **Go to Definition** from the context menu (right-click, then choose **Go to Definition**). When there's only one definition of the symbol, you'll navigate directly to its location, otherwise the competing definitions are displayed in a peek window as described in the previous section and you have to choose the definition that you want to go to. + +## Next steps + +Read on to find out about: + +* [Configure VS Code for Windows Subsystem for Linux](config-wsl.md) +* [Configure VS Code for MSVC](config-mingw.md) +* [Configure VS Code for Mingw-w64 and GCC](config-mingw.md) +* [Configure VS Code for macOS](config-clang-mac.md) +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](../editor/editingevolved.md) - Move quickly through your source code. +* [Tasks](../editor/tasks.md) - use tasks to build your project and more +* [Debugging](../editor/debugging.md) - find out how to use the debugger with your project + + +If you have any other questions or run into any issues, please file an issue on [GitHub](https://github.com/Microsoft/vscode-cpptools/issues). diff --git a/docs/cpp/cpp.md b/docs/cpp/cpp.md new file mode 100644 index 000000000..0edc7082a --- /dev/null +++ b/docs/cpp/cpp.md @@ -0,0 +1,54 @@ +--- +Order: 8 +Area: languages +TOCTitle: C++ +ContentId: D06C8C5C-2D3A-4B2E-B31F-12F1907E6402 +PageTitle: C++ programming with Visual Studio Code +DateApproved: 06/24/2019 +MetaDescription: Find out how to get the best out of Visual Studio Code and C++. +MetaSocialImage: images/cpp/languages_cpp.png +--- +# C/C++ for Visual Studio Code (Preview) + +C/C++ support for Visual Studio Code is provided by a [Microsoft C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) to enable cross-platform C and C++ development on Windows, Linux, and macOS. The extension is still in preview and our focus is code editing, navigation, and debugging support for C and C++ code everywhere that VS Code runs. The extension also supports [Remote Development](../remote/remote-overview.md) in the [Visual Studio Code Insiders build](https://code.visualstudio.com/insiders/). + +![cpp hero](images/cpp/cpp-hero.png) + +If you just want a lightweight tool to edit your C++ files, Visual Studio Code is a great choice. But if you want the best possible experience for editing, testing and debugging your existing Visual C++ projects or debugging on Windows, we recommend Visual Studio. [Visual Studio Community](https://visualstudio.microsoft.com/vs/community) is a free edition. It includes: + +- support for CMake or any other build system +- support for Clang and GCC as well as the Microsoft C++ compiler +- support for CTest, Google Test and Boost.Test as well as the Microsoft Native Test Framework +- C++ code analysis tools including C++ Core Guidelines checkers +- the state-of-the-art Visual Studio debugger +- and much more. + +If you run into any issues or have suggestions for the Microsoft C/C++ extension, please file [issues and suggestions on GitHub](https://github.com/Microsoft/vscode-cpptools/issues). If you haven't already provided feedback, please take this [quick survey](https://www.research.net/r/VBVV6C6) to help shape this extension for your needs. + +## Getting Started + +**To install the Microsoft C/C++ extension:** + +1. Open VS Code. +1. Click the Extensions View icon on the Sidebar. +1. Search for `c++`. +1. Click **Install**, then click **Reload**. + +![cpp extension](images/cpp/cpp-extension.png) + +To install support for [Remote Development](../remote/remote-overview.md): + +1. Install the [Visual Studio Code Insiders build](https://code.visualstudio.com/insiders/). You can install this side by side with the stable build. +1. Install the [Visual Studio Code Remote Development Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack). +1. If the remote source files are hosted in WSL, download the **Remote - WSL** extension. +1. If you are connecting to a remote machine with SSH, download the **Remote - SSH** extension. +1. If the remote source files are hosted in a container (i.e. Docker), download the **Remote - Containers** extension. + +**Note**: The C/C++ extension does not include a C++ compiler or debugger. You will need to install these tools or use those already installed on your computer. Popular C++ compilers are [GCC](https://gcc.gnu.org/) on Linux or in a [Mingw-w64](http://www.mingw-w64.org/) environment on Windows, Clang for [XCode](https://developer.apple.com/xcode/) on macOS, and the [Microsoft C++ compiler](https://docs.microsoft.com/cpp/build/building-on-the-command-line?view=vs-2019) on Windows. Make sure your compiler executable is in your platform path so the extension can find it. The extension also supports the [Windows Subsystem for Linux](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/Windows%20Subsystem%20for%20Linux.md). + +For instructions on configuring VS Code for specific environments, see: + +- [Get Started with C++ and WSL](/docs/cpp/config-wsl.md) +- [Get Started with C++ and Mingw-w64](/docs/cpp/config-mingw.md) +- [Get Started with C++ and Clang/LLVM on macOS](/docs/cpp/config-clang-mac.md) +- [Get Started with C++ MSVC](/docs/cpp/config-msvc.md) diff --git a/docs/cpp/customize-default-settings-cpp.md b/docs/cpp/customize-default-settings-cpp.md new file mode 100644 index 000000000..00d69da4c --- /dev/null +++ b/docs/cpp/customize-default-settings-cpp.md @@ -0,0 +1,109 @@ +--- +Order: 7 +Area: cpp +TOCTitle: Customize default settings +ContentId: 4E34F6AF-BFC6-4BBB-8464-2E50C85AE826 +PageTitle: Customize default settings in Visual Studio Code C++ projects +DateApproved: 06/25/2019 +MetaDescription: How to customize semantic colorization of C++ code in Visual Studio Code. +--- + +# Customizing Default Settings + +You can override the default values for properties set in `c_cpp_properties.json`. + +## New VS Code settings + +The following `C_Cpp.default.*` settings map to each of the properties in a configuration block of `c_cpp_properties.json`. Namely: + +```json +C_Cpp.default.includePath : string[] +C_Cpp.default.defines : string[] +C_Cpp.default.compileCommands : string +C_Cpp.default.macFrameworkPath : string[] +C_Cpp.default.forcedIncludes : string[] +C_Cpp.default.intelliSenseMode : string +C_Cpp.default.compilerPath : string +C_Cpp.default.cStandard : c89 | c99 | c11 +C_Cpp.default.cppStandard : c++98 | c++03 | c++11 | c++14 | c++17 +C_Cpp.default.browse.path : string[] +C_Cpp.default.browse.databaseFilename : string +C_Cpp.default.browse.limitSymbolsToIncludedHeaders : boolean +``` + +These settings have all of the benefits of VS Code settings, meaning that they can have default, "User", "Workspace", and "Folder" values. So you can set a global value for `C_Cpp.default.cppStandard` in your "User" settings and have it apply to all of the folders you open. If any one folder needs a different value, you can override the value by adding a "Folder" or "Workspace" value. + +This property of VS Code settings allows you to configure each of your workspaces independently - making the `c_cpp_properties.json` file optional. + +## Updated `c_cpp_properties.json` syntax + +A special variable has been added to the accepted syntax of `c_cpp_properties.json` that will instruct the extension to insert the value from the VS Code settings mentioned above. If you set the value of any setting in `c_cpp_properties.json` to "${default}" it will instruct the extension to read the VS Code default setting for that property and insert it. For example: + +```json +"configurations": [ + { + "name": "Win32", + "includePath": [ + "additional/paths", + "${default}" + ], + "defines": [ + "${default}", + ], + "macFrameworkPath": [ + "${default}", + "additional/paths" + ], + "forceInclude": [ + "${default}", + "additional/paths" + ], + "compileCommands": "${default}", + "browse": { + "limitSymbolsToIncludedHeaders": true, + "databaseFilename": "${default}", + "path": [ + "${default}", + "additional/paths" + ] + }, + "intelliSenseMode": "${default}", + "cStandard": "${default}", + "cppStandard": "${default}", + "compilerPath": "${default}" + } +], +``` + +Take note that for the properties that accept string[], the syntax proposed above allows you to augment the VS Code setting with additional values, thus allowing you to have common paths listed in the VS Code settings and configuration-specific settings in `c_cpp_properties.json`. + +If a property is missing from `c_cpp_properties.json`, the extension will use the value in the VS Code setting. If a developer assigns values to all of the settings that apply for a given folder, then `c_cpp_properties.json` could be removed from the .vscode folder as it will no longer be needed. + +### System includes + +A new setting will be added that allows you specify the system include path separate from the folder's include path. If this setting has a value, then the system include path the extension gets from the compiler specified in the `compilerPath` setting will not be added to the path array that the extension uses for IntelliSense. We may want to provide a VS Code command to populate this value from the compiler's default for users who are interested in using it in case they want to make some modifications to the defaults. + +```json +C_Cpp.default.systemIncludePath : string[] +``` + +### System Include Path/Defines Resolution Strategies + +The extension determines the system includePath and defines to send to the IntelliSense engine in the following manner: + +1. If `compileCommands` has a valid value and the file open in the editor is in the database, use the compile command in the database entry to determine the include path and defines. + - The system include path and defines are determined using the following logic (in order): + 1. If `systemIncludePath` has a value, use it (continue to the next step to search for system defines). + 2. If `compilerPath` is valid, query it. + 3. Interpret the first argument in the command as the compiler and attempt to query it. + 4. If `compilerPath` is "", use an empty array for system include path and defines. + 5. If `compilerPath` is undefined, look for a compiler on the system and query it. + +2. If `compileCommands` is invalid or the current file is not listed in the database, use the `includePath` and `defines` properties in the configuration for IntelliSense. + - The system include path and defines are determined using the following logic (in order): + 1. If `systemIncludePath` has a value, use it (continue to the next step to search for system defines). + 2. If `compilerPath` is valid, query it. + 3. If `compilerPath` is ``, use an empty array for system include path and defines (they are assumed to be in the `includePath` and `defines` for the current config already). + 4. If `compilerPath` is undefined, look for a compiler on the system and query it. + +System includes should not be added to the `includePath` or `browse.path` variables. If the extension detects any system include paths in the `includePath` property it will silently remove them so that it can ensure system include paths are added last and in the correct order (this is especially important for GCC/Clang). diff --git a/docs/cpp/enable-logging-cpp.md b/docs/cpp/enable-logging-cpp.md new file mode 100644 index 000000000..b3936c613 --- /dev/null +++ b/docs/cpp/enable-logging-cpp.md @@ -0,0 +1,27 @@ +--- +Order: 15 +Area: cpp +TOCTitle: Enable logging +ContentId: EC8DC085-A0E4-4401-B41F-6497EDD49352 +PageTitle: How to enable logging in the Visual Studio Code C/C++ extension +DateApproved: 06/25/2019 +MetaDescription: How to enable logging in the Visual Studio Code C/C++ extension +--- + +# How to enable logging in the extension + +If you are experiencing a problem that we are unable to diagnose based on information in your issue report, we might ask you to enable logging and send us your logs. + +Logging information is delivered directly to the Output window in VSCode. To turn on full logging for an issue report, follow these steps: + +1. Open the **Command Palette** and choose **Preferences: Workspace settings**. +1. Search for "logging" in the search box. +1. Find **C_cpp Logging Level** and change the level to **Debug**. + + ![Logging level](images/cpp/logging-level.png) + +1. From the main menu, open the Output Window by choosing **View** > **Output**. + +1. Select the "C/C++" option in the log filter selector: + + ![Log filter selector](images/cpp/log-filter-selector.png) diff --git a/docs/cpp/faq-cpp.md b/docs/cpp/faq-cpp.md new file mode 100644 index 000000000..77bca8ebf --- /dev/null +++ b/docs/cpp/faq-cpp.md @@ -0,0 +1,79 @@ +--- +Order: 15 +Area: cpp +TOCTitle: FAQ +ContentId: EC8DC085-A0E4-4401-B41F-6497EDD49352 +PageTitle: C/C++ extension FAQ +DateApproved: 06/25/2019 +MetaDescription: Frequently asked questions about the C/C++ extension in Visual Studio Code. +--- +# Frequently asked questions + +- [Why are my files corrupted on format?](#why-are-my-files-corrupted-on-format) +- [How do I get IntelliSense to work correctly?](#how-do-i-get-intellisense-to-work-correctly) +- [Why do I see red squiggles under Standard Library types?](#why-do-i-see-red-squiggles-under-standard-library-types) +- [How do I get the new IntelliSense to work with MinGW on Windows?](#how-do-i-get-the-new-intellisense-to-work-with-mingw-on-windows) +- [How do I get the new IntelliSense to work with the Windows Subsystem for Linux?](#how-do-i-get-the-new-intellisense-to-work-with-the-windows-subsystem-for-linux) +- [What is the difference between `includePath` and `browse.path` in **c_cpp_properties.json**?](#what-is-the-difference-between-includepath-and-browsepath-in-c_cpp_propertiesjson) +- [How do I re-create the IntelliSense database?](#how-do-i-re-create-the-intellisense-database) + +## Why are my files corrupted on format? + +Files can be corrupted due to the fact that you either have a multi-root workspace where one folder is a child of the other, or you are using symlinks to open your file. Reduce the folders in the workspace to one and remove the symlink. This should fix your problem. + +## How do I get IntelliSense to work correctly? + +There are two IntelliSense engines present in the extension: the "fuzzy" engine (or Tag Parser), and the new "Default" engine. If you are using version 0.11.0 or higher of the cpptools extension, then you can preview the new IntelliSense engine, which has more accurate autocomplete suggestions and tooltips. To use the new engine, you need to ensure that `C_Cpp.intelliSenseEngine` is set to `Default` in your settings. Since the engine is still in preview, it is not on by default for everyone yet. + +After selecting the IntelliSense engine that you prefer, take a look at the Problems window in VS Code to see if you need to do any further configuration for your folder. For example, the Default engine will not provide squiggles and auto-complete suggestions for a translation unit (read: a source file and its dependencies) if the include path is not configured properly. You can select any of the problems in the window to navigate to the line when the problem was detected and a light bulb will appear in the editor with some options (code actions) to help you resolve the problem: + +1. Update your `includePath` (and preprocessor defines) +2. Force semantic IntelliSense + +### Update your `includePath` (and preprocessor defines) + +Selecting this option will open a file called **c_cpp_properties.json**. If you haven't created this file already, it will be created for you in the **.vscode** folder of your workspace. + +Add the necessary paths to your include files to the `includePath` array. The `${workspaceRoot}` variable is available to use to get a relative path to the folder you have opened. Also add any required symbols that need to be defined to the `defines` array. Both "\" and "\=\" syntax is accepted. When you edit and save this file, the IntelliSense engine will reset and reparse source your source files and headers with the new settings. + +### Force semantic IntelliSense + +If you want IntelliSense to operate on your files even when all #include directives do not resolve, then you can choose the `Force semantic IntelliSense` code action to always use the new IntelliSense engine. You can also set the `C_Cpp.intelliSenseEngineFallback` setting to `Disabled`. + +## Why do I see red squiggles under Standard Library types? + +The most common reason for this is missing include paths and defines. The easiest way to fix this on each platform is as follows: + +**Linux/Mac**: Set `intelliSenseMode": "clang-x64` or `intelliSenseMode": "gcc-x64` and `compilerPath` in **c_cpp_properties.json** to the path to your compiler. + +**Windows**: If you are using the Microsoft C++ compiler, set `intelliSenseMode": "msvc-x64`, but don't add the `compilerPath` property to **c_cpp_properties.json**. If you are using Clang for Windows, set `intelliSenseMode": "msvc-x64`, and `compilerPath` in **c_cpp_properties.json** to the path to your compiler. + +## How do I get the new IntelliSense to work with MinGW on Windows? + +The page discussing configuration with MinGW is [here](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/MinGW.md). + +## How do I get the new IntelliSense to work with the Windows Subsystem for Linux? + +See [Get Started with C++ and Windows Subsystem for Linux in Visual Studio Code](config-wsl.md). + +## What is the difference between `includePath` and `browse.path` in **c_cpp_properties.json**? + +There are two settings in the **c_cpp_properties.json** file. They are used by the different IntelliSense engines that we support and have slightly different meanings for the components that use them. + +The active IntelliSense engine is controlled by the `C_Cpp.intelliSenseEngine` setting in your **settings.json** file. The valid values for this setting are `Default` and `Tag Parser`. + +### includePath + +This array of path strings is used by the "Default" IntelliSense engine. This new engine provides semantic-aware IntelliSense features and will be the eventual replacement for the Tag Parser that has been powering the extension since it was first released. It currently provides tooltips and error squiggles in the editor. The remaining features (for example, code completion, signature help, go to definition, ...) are implemented using the Tag Parser's database, so it is still important to ensure that the browse.path setting is properly set. + +The paths that you specify for this setting are the same paths that you would send to your compiler via the `-I` switch. When your source files are parsed, the IntelliSense engine will prepend these paths to the files specified by your #include directives while attempting to resolve them. These paths are **not** searched recursively. + +### browse.path + +This array of path strings is used by the "Tag Parser" (a.k.a. "browse engine"). This engine will _recursively_ enumerate all files under the paths specified and track them as potential includes while tag parsing your project folder. To disable recursive enumeration of a path, you can append a `/*` to the path string. + +When you open a workspace for the first time, the extension adds `${workspaceRoot}` to both arrays. If this is undesirable, you can open your **c_cpp_properties.json** file and remove it. + +## How do I re-create the IntelliSense database? + +Starting in version 0.12.3 of the extension, we added a command that will reset your IntelliSense database. Open the command palette and choose the "C/Cpp: Reset IntelliSense Database" command. diff --git a/docs/cpp/images/clang-mac/intellisense-configurations-mac-clang.png b/docs/cpp/images/clang-mac/intellisense-configurations-mac-clang.png new file mode 100644 index 000000000..742833011 --- /dev/null +++ b/docs/cpp/images/clang-mac/intellisense-configurations-mac-clang.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ec8dc77b4cb0d78b8b30c45fb99571d04d790c60fc31a4ccc117d0fa51da85ef +size 165688 diff --git a/docs/cpp/images/cpp/Lightbulb.png b/docs/cpp/images/cpp/Lightbulb.png new file mode 100644 index 000000000..25cee1574 --- /dev/null +++ b/docs/cpp/images/cpp/Lightbulb.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6c2d575fb2781313041e34edc19126ef374875b511a122d751ee846c9c42faa6 +size 11979 diff --git a/docs/cpp/images/cpp/c-cpp-properties-file.png b/docs/cpp/images/cpp/c-cpp-properties-file.png new file mode 100644 index 000000000..13e66c904 --- /dev/null +++ b/docs/cpp/images/cpp/c-cpp-properties-file.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ea3ee58adf83b088d868d9d9c559352e13ea12b3360659030e3ad80190603d53 +size 12134 diff --git a/docs/cpp/images/cpp/compile_commands.png b/docs/cpp/images/cpp/compile_commands.png new file mode 100644 index 000000000..7ae71a8c9 --- /dev/null +++ b/docs/cpp/images/cpp/compile_commands.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e518041ebbe81b120e641a39f7bc590c7257b0caa8fe2a0a8db19e46afa6453d +size 12731 diff --git a/docs/cpp/images/cpp/condbreak.png b/docs/cpp/images/cpp/condbreak.png new file mode 100644 index 000000000..ca9975623 --- /dev/null +++ b/docs/cpp/images/cpp/condbreak.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c404d86420d20987d38af62aa0dab0525730aec8b71643232d199edfd55f328e +size 16182 diff --git a/docs/cpp/images/cpp/configure-includepath.png b/docs/cpp/images/cpp/configure-includepath.png new file mode 100644 index 000000000..0ad6efd21 --- /dev/null +++ b/docs/cpp/images/cpp/configure-includepath.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:45ce012f4b5bce4bdc72cf3b2fa15798e32893ddc5c70fe33246b86d36975e3c +size 5476 diff --git a/docs/cpp/images/cpp/cpp-lightbulb.png b/docs/cpp/images/cpp/cpp-lightbulb.png new file mode 100644 index 000000000..9b1b48253 --- /dev/null +++ b/docs/cpp/images/cpp/cpp-lightbulb.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1f0b403773894dbbf8df15bc0b4195e401df6064e4d4c44936b0eccb2c278587 +size 9894 diff --git a/docs/cpp/images/cpp/filesearch.png b/docs/cpp/images/cpp/filesearch.png new file mode 100644 index 000000000..9ee9334c9 --- /dev/null +++ b/docs/cpp/images/cpp/filesearch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:252c14bb05c9a2a04bb10de2e28f513ccbb5fec843f610f7e4c5521b135dbcb7 +size 46438 diff --git a/docs/cpp/images/cpp/include-errors.png b/docs/cpp/images/cpp/include-errors.png new file mode 100644 index 000000000..7c2a28fae --- /dev/null +++ b/docs/cpp/images/cpp/include-errors.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:86db364e54ec26fc9f1400a8950034b7e50aa0d5bcb49e7d635b0325f6234b65 +size 72518 diff --git a/docs/cpp/images/cpp/languages_cpp.png b/docs/cpp/images/cpp/languages_cpp.png new file mode 100644 index 000000000..7d2df7e6c --- /dev/null +++ b/docs/cpp/images/cpp/languages_cpp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:97d5a9e8ffd4e886086cc21f5772db80ee2619bcd88bfafc8352917aa24cbed2 +size 159605 diff --git a/docs/cpp/images/cpp/launchjson.png b/docs/cpp/images/cpp/launchjson.png new file mode 100644 index 000000000..7f5c97d8d --- /dev/null +++ b/docs/cpp/images/cpp/launchjson.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d998c8cdebc094b4200b099aea1007fb3282c11e20894e8a0a815c1911ee552e +size 42901 diff --git a/docs/cpp/images/cpp/lightbulb-suggestion.png b/docs/cpp/images/cpp/lightbulb-suggestion.png new file mode 100644 index 000000000..7dd12adaf --- /dev/null +++ b/docs/cpp/images/cpp/lightbulb-suggestion.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3061be6fd48f6a904976be9b75e13c104b70acbba4c9dd1f5c5660eb9bb3fb3a +size 15341 diff --git a/docs/cpp/images/cpp/list-members-cpp.png b/docs/cpp/images/cpp/list-members-cpp.png new file mode 100644 index 000000000..218745600 --- /dev/null +++ b/docs/cpp/images/cpp/list-members-cpp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1733c8522fb9441948a0ee97dd5a47f6510ec587baa48c864a2f63c74b02be6a +size 65351 diff --git a/docs/cpp/images/cpp/log-filter-selector.png b/docs/cpp/images/cpp/log-filter-selector.png new file mode 100644 index 000000000..cd01a7bc3 --- /dev/null +++ b/docs/cpp/images/cpp/log-filter-selector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:80e5913416863238261549e03c6df7d9c69ba9216ef45831a605eb625483feda +size 11003 diff --git a/docs/cpp/images/cpp/logging-level.png b/docs/cpp/images/cpp/logging-level.png new file mode 100644 index 000000000..ad809a990 --- /dev/null +++ b/docs/cpp/images/cpp/logging-level.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:90d385f96c11685865c1c8b1340d70070b7464541773c10891aeeb0163566a03 +size 21612 diff --git a/docs/cpp/images/cpp/parsing.png b/docs/cpp/images/cpp/parsing.png new file mode 100644 index 000000000..8896be42f --- /dev/null +++ b/docs/cpp/images/cpp/parsing.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:60dad47433331e2f689f8f36b7a14ace80ca29a7c93ce7e6a600c8fd8af69df8 +size 2442 diff --git a/docs/cpp/images/cpp/peekdefn.png b/docs/cpp/images/cpp/peekdefn.png new file mode 100644 index 000000000..4581d58e7 --- /dev/null +++ b/docs/cpp/images/cpp/peekdefn.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0e89a8491c08b8febad3bb58526318e87ec2c068a98958735b3e4c66b22fc047 +size 37327 diff --git a/docs/cpp/images/cpp/threads.png b/docs/cpp/images/cpp/threads.png new file mode 100644 index 000000000..8b30ba446 --- /dev/null +++ b/docs/cpp/images/cpp/threads.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4d1541e7fbcaa08f73d934c7f867252b967077a290adc3139fbc72d5401ade4e +size 29650 diff --git a/docs/cpp/images/cpp/workspacesearch.png b/docs/cpp/images/cpp/workspacesearch.png new file mode 100644 index 000000000..4e590d494 --- /dev/null +++ b/docs/cpp/images/cpp/workspacesearch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:30d27599ed38cfce73d42e197b2365612869f7bc3f62e52c0cd4f9186189ef01 +size 44327 diff --git a/docs/cpp/images/mingw/intellisense-configurations-mingw.png b/docs/cpp/images/mingw/intellisense-configurations-mingw.png new file mode 100644 index 000000000..64cc675de --- /dev/null +++ b/docs/cpp/images/mingw/intellisense-configurations-mingw.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dfa86e359d600adc2e9a9f52be4fddcb6225285ad81da386dba1b28c7394be7b +size 37345 diff --git a/docs/cpp/images/mingw/quickinfo.png b/docs/cpp/images/mingw/quickinfo.png new file mode 100644 index 000000000..249926b21 --- /dev/null +++ b/docs/cpp/images/mingw/quickinfo.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dea5e9ce4a7280c9a8b6206864785fe5bfbefd85225324eacb17b43bc7c3deed +size 21355 diff --git a/docs/cpp/images/msvc/msvc-intellisense-configurations.png b/docs/cpp/images/msvc/msvc-intellisense-configurations.png new file mode 100644 index 000000000..11f9cd01c --- /dev/null +++ b/docs/cpp/images/msvc/msvc-intellisense-configurations.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9b5e12791ee86a15093a597ef3e99e435f3ff6f8ddb9b534b0c3175c13b8010f +size 153036 diff --git a/docs/cpp/images/wsl/intellisense-configurations-wsl.png b/docs/cpp/images/wsl/intellisense-configurations-wsl.png new file mode 100644 index 000000000..893741362 --- /dev/null +++ b/docs/cpp/images/wsl/intellisense-configurations-wsl.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b90b4aa28bc19d392683a52e73905dbb487030834a9cf79284a25ef2ce943061 +size 138698 diff --git a/docs/cpp/intellisense-engine-cpp.md b/docs/cpp/intellisense-engine-cpp.md new file mode 100644 index 000000000..7d3380547 --- /dev/null +++ b/docs/cpp/intellisense-engine-cpp.md @@ -0,0 +1,56 @@ +--- +Order: 9 +Area: cpp +TOCTitle: IntelliSense engines +ContentId: ---------- +PageTitle: C/C++ IntelliSense engines in Visual Studio Code +DateApproved: 06/25/2019 +MetaDescription: About the C/C++ IntelliSense engines in Visual Studio Code +--- + +# IntelliSense engines + +There are two IntelliSense engines used to power the C/C++ IntelliSense experience in VS Code. + +* `Default` - Visual Studio's IntelliSense engine, which is the default engine that provides semantic-aware IntelliSense features +* `Tag Parser` - the "fuzzy" IntelliSense engine that provides quick but "fuzzy" results, is used to provide the fallback experience if the default engine is unable to fully resolve include paths + +Ultimately all the IntelliSense and code browsing features will be powered by the "Default" engine. The following features have been implemented so far: + +* Autocomplete suggestions for class/struct/namespace members +* Parameter hints +* Quick info (hover over tooltip) +* Error squiggles +* Reference highlighting + +The other IntelliSense features, such as global autocomplete, and code browsing features, such as Go to definition/declaration, are currently powered by the "Tag Parser" based engine. + +## `includePath` and `browse.path` + +The two IntelliSense engines use two different settings in the `c_cpp_properties.json` file for specifying include paths. This file is located in the **.vscode** directory in the opened folder. You can create or open this file by either using the **C/Cpp: Edit Configurations** command in the command palette or by selecting "Edit "includePath" setting" in the Light Bulb menu. Look for the following settings in the section where your current configuration is defined (by default there's one configuration per OS, such as "Win32 or "Mac"). + +### includePath + +This array of path strings is used by the "Default" IntelliSense engine. The paths that you specify for this setting are the same paths that you would send to your compiler via the -I switch. When your source files are parsed, the IntelliSense engine will prepend these paths to the files specified by your #include directives while attempting to resolve them. These paths are searched **non-recursively**. + +### browse.path + +This array of path strings is used by the "Tag Parser" (also called the *browse engine*). This engine will **recursively** enumerate all files under the paths specified and track them as potential includes while tag parsing your project folder. To disable recursive enumeration of a path, you can append a `/*` to the path string. + +### How fallback works and how to control the behavior + +The extension first tries to fully parse any opened file using the "Default" IntelliSense engine. If it discovers that it cannot find a header file or a dependency, it will fall back to the tag parser and provide the fuzzy IntelliSense behavior. The fallback affects a full translation unit (TU), not just a single open file. The Problems panel provides details about unresolved headers and dependencies. Other opened TUs will continue to use the "Default" IntelliSense engine provided that all #include dependencies are resolved. + +We recognize that resolving all #includes may not be necessary for all projects and you may still want to experience the productivity benefits of using the "Default" semantic engine without customizing the default include path. For that, the “Force semantic IntelliSense” action can be chosen. When invoked, all unresolved #include squiggles will turn red and semantic member list and linting will be enabled in all files regardless of whether or not #include statements can be resolved. + +### IntelliSense engine setting + +We recommend using the "Default" engine for the best IntelliSense experience. However, it is possible to explicitly choose the IntelliSense engine by editing your [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings). The setting you should modify is `C_Cpp.intelliSenseEngine`. There are two values for this setting: + +* `Default` - use Visual Studio's IntelliSense engine +* `Tag Parser` - use the "fuzzy" IntelliSense engine + +### See Also + +[Configuring includePath for better IntelliSense results](configure-intellisense-cpp.md) +[c_cpp_properties.json reference guide](c-cpp-properties-schema-reference.md) diff --git a/docs/cpp/launch-json-reference.md b/docs/cpp/launch-json-reference.md new file mode 100644 index 000000000..025a3c4a3 --- /dev/null +++ b/docs/cpp/launch-json-reference.md @@ -0,0 +1,249 @@ +--- +Order: 14 +Area: cpp +TOCTitle: launch.json reference +ContentId: EC8DC085-A0E4-4401-B41F-6497EDD49352 +PageTitle: Configure launch.json for C/C++ debugging in Visual Studio Code +DateApproved: 06/25/2019 +MetaDescription: Configure launch.json for C/C++ debugging in Visual Studio Code +--- +# Configuring launch.json for C/C++ debugging + +The `launch.json` file is used to configure the debugger in Visual Studio Code. + +Visual Studio Code generates a `launch.json` with almost all of the required information. To get started +debugging you need to fill in the `program` field with the path to the executable you plan to debug. This must be specified for +both the launch and attach (if you plan to attach to a running instance at any point) configurations. + +The generated file contains two sections, one that configures debugging for launch and a second that configures debugging for attach. + +## Configure VS Code's debugging behavior + +Set or change the following options to control VS Code's behavior during debugging: + +### program (required) + +Specifies the full path to executable the debugger will launch or attach to. + +### symbolSearchPath + +Tells the Visual Studio Windows Debugger what paths to search for symbol (.pdb) files. Separate multiple paths with a semicolon. For example: `"C:\\Symbols;C:\\SymbolDir2"`. + +### additionalSOLibSearchPath + +Tells GDB or LLDB what paths to search for .so files. Separate multiple paths with a semicolon. For example: `"/Users/user/dir1;/Users/user/dir2"`. + +### externalConsole + +- **Windows**: When set to true, it will spawn an external console. When set to false, it will use VS Code's integratedTerminal. +- **Linux**: When set to true, it will notify VS Code to spawn an external console. When set to false, it will use VS Code's integratedTerminal. +- **macOS**: When set to true, it will spawn an external console through `lldb-mi`. When set to false, the output can be seen in VS Code's debugConsole. Due to limitations within `lldb-mi`, integratedTerminal support is not available. + +### avoidWindowsConsoleRedirection + +In order to support VSCode's Integrated Terminal with gdb on Windows, the extension adds console redirection commands to the debuggee's arguments to have console input and output show up in the integrated terminal. Setting this option to `true` will disable it. + +### logging + +Optional flags to determine what types of messages should be logged to the Debug Console. + +- **exceptions**: Optional flag to determine whether exception messages should be logged to the Debug Console. Defaults to true. +- **moduleLoad**: Optional flag to determine whether module load events should be logged to the Debug Console. Defaults to true. +- **programOutput**: Optional flag to determine whether program output should be logged to the Debug Console. Defaults to true. +- **engineLogging**: Optional flag to determine whether diagnostic engine logs should be logged to the Debug Console. Defaults to false. +- **trace**: Optional flag to determine whether diagnostic adapter command tracing should be logged to the Debug Console. Defaults to false. +- **traceResponse**: Optional flag to determine whether diagnostic adapter command and response tracing should be logged to the Debug Console. Defaults to false. + +### visualizerFile + +.natvis file to be used when debugging. See [Create Custom Views of Native Objects](https://docs.microsoft.com/visualstudio/debugger/create-custom-views-of-native-objects) for information on how to create Natvis files. + +### showDisplayString + +When a `visualizerFile` is specified, `showDisplayString` will enable the display string. Turning on this option can cause slower performance during debugging. + +**Example:** + +```json +{ + "name": "C++ Launch (Windows)", + "type": "cppvsdbg", + "request": "launch", + "program": "C:\\app1\\Debug\\app1.exe", + "symbolSearchPath": "C:\\Symbols;C:\\SymbolDir2", + "externalConsole": true, + "logging": { + "moduleLoad": false, + "trace": true + }, + "visualizerFile": "${workspaceRoot}/my.natvis", + "showDisplayString": true +} +``` + +## Configure the target application + +The following options enable you to modify the state of the target application when it is launched: + +### args + +JSON array of command-line arguments to pass to the program when it is launched. Example `["arg1", "arg2"]`. If you are escaping characters, you will need to double escape them. For example, `["{\\\"arg\\\": true}]` will send `{"arg1": true}` to your application. + +### cwd + +Sets the working directory of the application launched by the debugger. + +### environment + +Environment variables to add to the environment for the program. Example: `[ { "name": "squid", "value": "clam" } ]`. + +**Example:** + +```json +{ + "name": "C++ Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceRoot}/a.out", + "args": ["arg1", "arg2"], + "environment": [{"name": "squid", "value": "clam"}], + "cwd": "${workspaceRoot}" +} +``` + +## Customizing GDB or LLDB + +You can change the behavior of GDB or LLDB by setting the following options: + +### MIMode + +Indicates the debugger that VS Code will connect to. Must be set to `gdb` or `lldb`. This is pre-configured on a per-operating system basis and can be changed as needed. + +### miDebuggerPath + +The path to the debugger (such as gdb). When only the executable is specified, it will search the operating system's PATH variable for a debugger (GDB on Linux and Windows, LLDB on OS X). + +### miDebuggerArgs + +Additional arguments to pass to the debugger (such as gdb). + +### stopAtEntry + +If set to true, the debugger should stop at the entry-point of the target (ignored on attach). Default value is `false`. + +### setupCommands + +JSON array of commands to execute in order to set up the GDB or LLDB. Example: `"setupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`. + +### customLaunchSetupCommands + +If provided, this replaces the default commands used to launch a target with some other commands. For example, this can be "-target-attach" in order to attach to a target process. An empty command list replaces the launch commands with nothing, which can be useful if the debugger is being provided launch options as command-line options. Example: `"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`. + +### launchCompleteCommand + +The command to execute after the debugger is fully set up in order to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run". + +**Example:** + +```json +{ + "name": "C++ Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceRoot}/a.out", + "stopAtEntry": false, + "customLaunchSetupCommands": [ + { "text": "target-run", "description": "run target", "ignoreFailures": false } + ], + "launchCompleteCommand": "exec-run", + "linux": { + "MIMode": "gdb", + "miDebuggerPath": "/usr/bin/gdb" + }, + "osx": { + "MIMode": "lldb" + }, + "windows": { + "MIMode": "gdb", + "miDebuggerPath": "C:\\MinGw\\bin\\gdb.exe" + } +} +``` + +## Debugging dump files + +The C/C++ extension enables debugging dump files on Windows and core dump files Linux and OS X. + +### dumpPath + +If you want to debug a Windows dump file, set this to the path to the dump file to start debugging in the `launch` configuration. + +### coreDumpPath + +Full path to a core dump file to debug for the specified program. Set this to the path to the core dump file to start debugging in the `launch` configuration. +_Note: core dump debugging is not supported with MinGw._ + +## Remote debugging or debugging with a local debugger server + +### miDebuggerServerAddress + +Network address of the debugger server (for example, gdbserver) to connect to for remote debugging (example: `localhost:1234`). + +### debugServerPath + +Full path to debug server to launch. + +### debugServerArgs + +Arguments for the debugger server. + +### serverStarted + +Server-started pattern to look for in the debug server output. + +### serverLaunchTimeout + +Time in milliseconds, for the debugger to wait for the debugServer to start up. Default is 10000. + +## Additional properties + +### processId + +Defaults to `${command.pickProcess}` which will display a list of available processes the debugger can attach to. We recommend that you leave this default, but the property can be explicitly set to a specific process ID for the debugger to attach to. + +### request + +Indicates whether the configuration section is intended to `launch` the program or `attach` to an already running instance. + +### targetArchitecture + +`Deprecated` This option is no longer needed as the target architecture is automatically detected. + +### type + +Indicates the underlying debugger being used. Must be `cppvsdbg` when using the Visual Studio Windows debugger, and `cppdbg` when using GDB or LLDB. This is automatically set to the correct value when the +`launch.json` file is created. + +### sourceFileMap + +This allows mapping of the compile-time paths for source to local source locations. It is an object of key/value pairs and will resolve the first string-matched path. (example: `"sourceFileMap": { "/mnt/c": "c:\\" }` will map any path returned by the debugger that begins with `/mnt/c` and convert it to `c:\\`. You can have multiple mappings in the object but they will be handled in the order provided.) + +## Environment variable definitions file + +An environment variable definitions file is a simple text file containing key-value pairs in the form of `environment_variable=value`, with `#` used for comments. Multiline values are not supported. + +The `cppvsdbg` debugger configuration also contains an `envFile` property that allows you to easily set variables for debugging purposes. + +For example: + +**project.env file**: + +```bash +# project.env + +# Example environment with key as 'MYENVRIONMENTPATH' and value as C:\\Users\\USERNAME\\Project +MYENVRIONMENTPATH=C:\\Users\\USERNAME\\Project + +# Variables with spaces +SPACED_OUT_PATH="C:\\This Has Spaces\\Project" +``` diff --git a/docs/cpp/natvis.md b/docs/cpp/natvis.md new file mode 100644 index 000000000..8e6e6894c --- /dev/null +++ b/docs/cpp/natvis.md @@ -0,0 +1,1160 @@ +--- +Order: 12 +Area: cpp +TOCTitle: C++ +ContentId: F684A0E8-0AEB-4CA9-83E2-891CC012EA8B +PageTitle: Pipe transport for remote communication in C++ projects +DateApproved: 06/25/2019 +MetaDescription: How to set up pipe transport for debugging C++ code in Visual Studio Code. +--- +# Natvis - Custom views for native objects + +The Natvis framework allows developers to write custom schemas to help visualize native objects. + +For gdb/lldb debugging (`type": "cppdbg`), a subset of the Natvis framework has been ported to the C/C++ extension and the code resides in the [MIEngine](https://github.com/Microsoft/MIEngine) shared component. If additional features that are not implemented are requested, please [file an issue](https://github.com/Microsoft/MIEngine/issues) on the MIEngine GitHub page with details of what is missing. + +For Microsoft C++ debugging (`type": "cppvsdbg`), the debugger contains the full implementation of the Natvis framework as Visual Studio. + +## Documentation + +The official Natvis documentation is located at [Create custom views of C++ objects in the debugger](https://docs.microsoft.com/visualstudio/debugger/create-custom-views-of-native-objects). + +## Schema + +The Natvis schema is provided here for convenience: + +```xml + + + + + + + + Values of this type will look like: "01234567-89AB-CDEF-0123-456789ABCDEF" or "{01234567-89AB-CDEF-0123-456789ABCDEF}". + + + + + + + + + A valid C++ identifier. + + + + + + + + + + + + + + + + Specifies the maximum number of collection items that can be displayed at one time. If the number of items in the collection + exceeds this limit, a special node will be created at the end, which can be expanded to show additional items. + + The precise cutoff for the maximum number of items to show in a view is a tuning parameter. While a higher number allow more items + to be visible at one time, a lower number will improve the performance of Visual Studio when a custom list object is expanded. In general, + the more complicated the traversal logic, the smaller the number of items per view needs to be in order to keep the IDE responsive. + + The maximum number of items per view must be between 1 and 50,000. A default value of 5,000 items will be used if this attribute is not specified. + + + + + + + + + + + Specifies the condition under which this element is active. The expression should produce a boolean value when evaluated. + + + + + + + + + + Specifies whether the element is optional. An optional element that fails to parse allows the remainder of the elements in the enclosing <Type> entry + to be used. A mandatory element that fails to parse will cause the entire enclosing <Type> element to be invalidated. All elements are assumed, by default, to be mandatory, + unless Optional="true" is specified. + + + + + + + + + + Specifies a semi-colon-delimited list of views in which this element should be shown. The view of the object is controlled + via the ,view(<name>) format specifier. + + + + + + + + + + Specifies a semi-colon-delimited list of views in which this element should be hidden. The view of the object is controlled + via the ,view(<name>) format specifier. + + + + + + + + + + Specifies the fully qualified name of the type to be visualized. If the type is a template class, it might contain '*' as a wildcard character for template parameters. Primitive data type names are only allowed with UIVisualizer definitions. + + + + + + + + + Specifies the name of a module. It should include just the module name and no absolute or relative paths. + + + + + + + + + + + 1.2.3.4 or 1.2 are acceptable. + + + + + + + + + + Specifies an alternative HRESULT which will share the same visualizer. + + + + + + + Specifies the type of the parameter to the given intrinsic function. + + + + + If an expression is provided, specifies the name by which the expression can refer to the parameter. If the function is implemented via a debugger extension, + this attribute may be omitted. + + + + + + + + Describes a custom intrinsic function that can be called from an expression. An <Intrinsic> element must be + accompanied by a debugger component that implements the function through the IDkmIntrinsicFunctionEvaluator140 interface. + + + + + + + + + The name of the intrinsic function. This must be a valid C++ identifier. + + + + + + Specifies which category icon should be assigned to the results of expressions that invoke this function. This controls which icon is used + in the watch window for expressions that call the function. The default category value is 'Method'. + + + + + The return type of the intrinsic function. The return type may be omitted if an expression is provided (the type of the expression will imply the return type). + + + + + + Expression that evaluates to the return value of the function. + + + + + + Specifies the source id used to identify the debugger component that implements the function. This must match the filter constraints of the IDkmIntrinsicFunctionEvaluator140 implementation. + + + + + Specifies the language id used to identify the debugger component that implements the function. This must match the filter constraints of the IDkmIntrinsicFunctionEvaluator140 implementation. + + + + + Specifies unique id for this function, given the source id and language id. It is used by the implementing component to determine which function was called + if it implements multiple intrinsic functions. + + + + + If true, indicates that this function may cause side effects. If true, calls to this function will be disabled + in scenarios where unexpected side effects may be confusing to the user. Functions that modify state, either inside the debuggee or inside Visual Studio, should set this to true. + By default, this value is false. + + + + + + If true, indicates that this function is a varargs function, and that additional arguments can be passed after the explicitly-listed parameters. Default is false. + + + + + + + + Specifies an alternative type which will share the same visualizer. + + + + + + + True if this visualizer may be used by objects of classes derived from the given type, false if an object must be directly of this type for the visualizer to take effect. + Default is true. + + + + + + + + Specifies a matching module name and version for this visualizer. + + + + + Specifies the minimum (inclusive) version number. + + + + + Specifies the maximum (inclusive) version number. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specifies the string to be shown as the value of objects of the visualized type. It accepts arbitrary strings mixed with expressions. Everything inside curly braces (i.e. { and }) is interpreted as an expression and gets evaluated. To escape a curly brace, you can type two curly braces (i.e. {{ or }}). + + + + + + + If a legacy add-in exists, specifies the dll of the legacy addin. If a full path isn't specified, Visual Studio will look in the visualizer directory next to the .natvis file that specified the add-in. A regular display string is still allowed in conjunction with an add-in, and will be used as a fallback if the add-in dll cannot be loaded. + + + + + If a legacy add-in exists, specifies the name of the export for the legacy add-in implementation. This attribute is valid only if 'LegacyAddin' is also specified. + + + + + Specifies the encoding of the string returned by the legacy addin. Default is Utf8. This attribute is valid only if 'LegacyAddin' is also specified. + + + + + + + + + + + + + + + + + Specifies a visualizer add-in which customizes the debugger view of this object. + + + + + + + + Specifies the expression whose value is sent to the built-in text visualizers. + + + + + + + + + + + + + + + + + + + + + Specifies an optional name, in <DisplayString> syntax, for this node. If omitted, the name + of the node will simply be the index of the item in the tree traversal. Expressions in curly braces + are evaluated in the context of the node. + + + + + + + Expression that points to value of the linked list node. It can be left empty or have 'this' to refer to the linked list node itself. This expression is evaluated under the context of the linked list node and not the parent linked list type. + + + + + + + + + + + + + + + + + + + + Specifies a single child element. It only accepts expressions and no arbitrary strings. If the expression produces a complex type value, the child node itself can be expanded by the user. + + + + + + Name of the child element as it will be shown under the name column in the debugger variable windows. + + + + + + + + + + Specifies a child element whose children will be shown as the children of the current node. Use when you need to generate a flat view of a type when expanded. + + + + + + + + + + + Specifies how the multi-dimensional array indices should be unrolled. Use 'Forward' for row-major arrays and 'Backward' for column-major arrays. + + + + + + + + + + + + + Indicates that the item should use the icon associated with general data. + + + + + + + Indicates that the item should use the icon associated with method calls. + + + + + + + Indicates that the item should use the icon associated with properties. + + + + + + + + + Specifies the list of child elements to be shown when a variable of the visualized type is expanded in the debugger windows. + + + + + + + + + + + + + + Specifies whether or not the the "[Raw View]" node for this object should be hidden. By default, this attribute is set to 'false', + which will result in the raw view node of the current object visible to the user. + + + + + + + + Specifies custom logic for iterating through a collection which cannot be visualized by other means. + + + + + + + + + + + + + + + + + + + + + + + + + Specifies logic to skip a specified number of items in the collection. The skip logic is invoked + when the user scrolls in the watch window in order to quickly navigate the collection traversal down to the desired point. After the skip logic, + control will return to be start of the execution, but with iteration variables modified as needed to reflect the updated state. + + The <Skip> element exist as an optional performance optimization to allow the collection traversal to skip through large numbers + of items quickly. If a <Skip> element is not specified, the expression evaluator will run the traversal logic when it needs to do + a skip until the desired number of <Item> elements have executed. Depending on the data structure of the underlying collection, + this may involve a significant amount of unnecessary computation. + + + + + + + + + + + Name of the variable specifying the number of items to skip, as an unsigned 32-bit integer. If a <Size> element is specified, + the expression evaluator will never pass in a skip value that would cause the current index of the traversal to exceed the bounds of the collection. + If no <Size> element is specified, the skip value may be any arbitrary integer, and it is the responsibility of the <Skip> logic + to do any bounds checking necessary. In the event that it is not possible to skip over the full number of items requested, the <Skip> logic + should modify the value to the skip variable so that when execution completes, it contains the actual number of items skipped. + + + + + + + + Specifies the total number of items in the collection. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Condition controlling whether this element and inner elements should execute + + + + + + + + + + + + Specifies a block of instructions which will only execute multiple times until a <Break> element is encountered, or an expression fails to evaluate. + + + + + + + + + + + + + Specifies a block of instructions which will only execute multiple times until a <Break> element is encountered, or an expression fails to evaluate. + + + + + + + + + + + + Specifies a block of instructions which will only execute if a condition is true. + + + + + + + + + + + + Specifies a block of instructions which will only execute if a condition is true. + + + + + + + + + + + + Specifies a block of instructions which will only execute if a condition is true. + + + + + + + + + + + + Specifies a block of instructions which will only execute if a condition is true. + + + + + + + + + + + + + Declares a variable for use in future expressions with the <CustomListItems> block. + + + + + Name of the variable. + + + + + + Expression evaluating to the initial value of the variable. + This expression also specifies the type of the variable. Initial value expressions may make use of other variables already defined. + + + + + + + + + Executes a single expression. The expression executes in the context of the object, but may use iteration variables. + The expression may also modify iteration variables, but no other side effects are allowed. + + + + + + + + + + + + Generates a child item obtained by evaluating the given expression. + + + + + + + + Specifies an optional name to use for the item. The name is provided in <DisplayString> syntax and may contain embedded expressions. + If no name is provided a default name will be used in the form "[i]", where 'i' is the index representing the order in which the item was returned. + + + + + + + + + + Breaks out of the innermost <Loop> element. A <Break> element outside of a loop will terminate iteration of the collection. + + + + + + + Specifies a child element whose value is not backed by an expression. The value of the item can be specified using a 'DisplayString' element. The children of the item can be specified using an 'Expand' element. + + + + + + + + + + Name of the child element as it will be shown under the name column in the debugger windows. + + + + + Expression that will be used to retrieve the value of the item when the user wants to track it separately using 'Add watch' command on the item. + + + + + + + + + + + + + + + + + + + + + + + + Specifies an array view of the contents of a variable. It assumes data elements are contiguous in memory. + + + + + + Specifies the rank of the array. + + + + + Specifies the size of each dimension of the array. For multi-dimensional arrays, you can specify an expression that uses the implicit $i parameter. The parameter will be substituted with the dimension index to find the size of the array in that dimension. + + + + + Specifies the lower bound of each dimension of the array. For multi-dimensional arrays, you can specify an expression that uses the implicit $i parameter. The parameter will be substituted with the dimension index to find the lower bound of the array in that dimension. + + + + + Specifies the expression that points to the first element of the array. The expression must be a pointer of the element type that is not void*. + + + + + + + + + Specifies a more generalized form of array view of a variable. Use when your data elements are not contiguous in memory and you need to compute index to the data elements. + + + + + Specifies the size of the index list. + + + + + Specifies the expression that uses the implicit $i parameter that points to the ith element. + + + + + + + + + Specifies a linked list view of the contents of a variable. + + + + + Specifies the number of elements in the linked list. If multiple size elements are specified, the first size element with a true condition (or no condition) will + determine the size. If no size is specified (or all size elements have a false condition), the debugger will traverse the list to figure out the size. It is recommended that natvis entries + specify a size for linked lists when possible, as providing a size will improve the performance of the debugger. + + + + + Expression that points to the first node of the linked list. + + + + + Expression that points to the next element. This expression is evaluated under the context of the linked list node and not the parent linked list type. + + + + + + + + + + + Specifies a tree view of the contents of a variable. + + + + + The size of the tree. + + + + + Expression that points to the head of the tree. + + + + + Expression that points to the left child of a tree node. This expression is evaluated under the context of the tree node and not the parent type. + + + + + Expression that points to the right child of a tree node. This expression is evaluated under the context of the tree node and not the parent type. + + + + + Expression that points to the value of the tree node. It can be left empty or have 'this' to refer to the tree node itself. This expression is evaluated under the context of the tree node and not the parent type. + + + + + + + + + Specifies a UI visualizer which can handle objects of this type. The UI visualizer must be previously defined in the natvis file. + + + + + + The service GUID of the visualizer. + + + + + Specifies the visualizer id. Use to differentiate multiple viewers provided by the visualizer service. + + + + + + + + + + Specifies an expression which evaluates to the current object, casted to its most-derived type. + In most cases, the debugger is able to automatically determine an object's most-derived type, in which case use of the <MostDerivedType> element is unnecessary. Automatic determination of an object's most-derived type requires the object to be an instance of a C++ class, with a + compiler-generated virtual function table. This is sufficient for most class-hierarchies; however, custom logic may occasionally be necessary + when dealing with a class hierarchy that does not contain virtual functions, or when the virtual function table is manually constructed by the application code. + + + + + + + + + If true, indicates that the most derived type of the object will always be the static type of the provided expression. By default, + the debugger will use vtables to calculate the most-derived type of the provided most-derived-type expressions. This option should + be used only when the application code builds vtables using custom logic that the debugger does not understand. + + + + + + + + + + Specifies how a smart pointer may be used syntactically. + + + + + + Indicates that the smart pointer may be used syntactically only for the purposes of dereferencing and comparing. + It defines the following overloaded operators: + - operator*() (dereference) + - operator->() (access field of dereferenced value) + - operator==() (compare with raw pointer or another smart pointer of the same type) + - operator!=() (compare with raw pointer or another smart pointer of the same type) + + + + + + + Indicates that the smart pointer may be used syntactically for the purposes of dereferencing and comparing, and indexing + It defines the following overloaded operators: + - operator+() (add an offset of type size_t) + - operator-() (subtract an offset of type size_t) + - operator[] (add an offset of type size_t and dereference) + - All of the operators supported by SmartPointerUsage="Minimal" + + + + + + + Indicates that the smart pointer will contain a conversion operator to the underlying pointer. All valid uses of the underlying pointer in the language may be used through the conversion operator. Direct assignment to the smart pointer is still forbidden; in order to modify the internal pointer in an expression, you must do so explicitly. + + + + + + + + + + Indicates that the given type is a smart pointer. The text inside this element specifies the expression to evaluate the underlying pointer. + The <SmartPointer> element has the following effects: + - If no alternative <DisplayString> element is provided (or all <DisplayString> elements have failed conditions), the underlying pointer will be the display string + - If no alternative <StringView> element is provided (or all <StringView> elements have failed conditions), the underlying pointer will be the string view, if it has one. + - If no alternative <Expand> element is provided, the expansion of the smart pointer will be the expansion of the underlying pointer. + - The smart pointer class will also support overloaded operators as determined by the <Usage> attribute. You can opt out of this behavior by specifying + 'DefaultExpansion="false"' + + + + + + + + Indicates which combinations of operators this smart pointer object supports. + + + + + + + If true and no expand element is provided, a default expansion will be supplied based on the expansion of the underyling pointer. If false, no <Expand> element will be automatically created + based on the smart pointer. If this attribute is not present, the default value is 'true'. + + + + + + + + + + Specifies a visualizer entry which customizes the debugger view of a type. + + + + + + + + + + + + + + + + + + + + + + + + True if this visualizer may be used by objects of classes derived from the given type, false if an object must be directly of this type for the visualizer to take effect. + Default is true. + + + + + + + + Specifies an optional priority to assign to this entry for type matching. Higher priority entries within a particular file or directory + are checked first. <Type> entries that do not specify a priority receive default priority of "Medium" <AlternativeType> entries which do not specify a priority + will inherit the priority of the enclosing <Type> element. The priority is only used to disambiguate type matching when all other means of disambiguation are unavailable. + For example, entries with more specific template instantiations, module constraints, or view constraints will take priority regardless of any priority values specified. + Similarly, regardless of priority, natvis files that are part of a loaded project will always take precedence over files in the user natvis directory, + which will, in turn, take precedence over files in the system-wide natvis directory. + If two entries have the same priority and cannot otherwise be disambiguated, it is unspecified which one will get used. + + + + + + + + + + + + + + + + + + Specifies details of a UI visualizer which creates its own interface to display an object. Visualizer entry for a type needs to reference a UI visualizer in order to associate the type with the UI visualizer. + + + + + + Specifies the visualizer service GUID. The service must be provided by a Visual Studio package that also implements IVsCppDebugUIVisualizer interface. The debugger will load the package only when user requests this visualization service. + + + + + Specifies the visualizer id. Use to differentiate multiple viewers provided by this visualizer service. + + + + + Specifies the name which will be shown in the UI visualizer list for a variable. + + + + + Specifies the description for this UI visualizer. + + + + + + + + + Specifies a visualizer entry which customizes the debugger view of an HRESULT. + + + + + Other HResult types that will share the same visualizer. + + + + + 32 bit HRESULT value to be customized. + + + + + The description for this HRESULT value to be shown in the debugger windows. + + + + + + The name of the HRESULT value to be shown in the debugger windows. + + + + + + + + Defines a localized string resource that can be referenced by natvis elements that accept strings (.g.e.g. DisplayString, Name attribute of Item element). + Use @<id>; format to reference a localized string (e.g. @1001;) + + + + + + + The id of the localized string. Use @<id>; format to reference this localized string. + + + + + + + + + + + + + + + Specifies a list of localized strings that can be referenced by natvis elements. Define localized strings in a satellite natvis file with the same name as the main file + and deploy it into a locale specific folder next to the main natvis file. Debugger will load localized resources from the appropriate satellite file. + Define localized strings in the main natvis file to serve as defaults when there is no satellite file for a locale. + + + + + + + + + + + + Root element of the natvis file. + + + + + + Specifies a matching module name and version for all visualizers which do not explicitly specify a module name and version in this file. + + + + + + + + + + + + + +``` \ No newline at end of file diff --git a/docs/cpp/pipe-transport.md b/docs/cpp/pipe-transport.md new file mode 100644 index 000000000..b467546f3 --- /dev/null +++ b/docs/cpp/pipe-transport.md @@ -0,0 +1,67 @@ +--- +Order: 13 +Area: cpp +TOCTitle: C++ +ContentId: 59BE5FF7-563F-4044-A562-294E75A75F96 +PageTitle: Pipe transport for remote communication in C++ projects +DateApproved: 06/25/2019 +MetaDescription: How to set up pipe transport for debugging C++ code in Visual Studio Code. +--- +# Pipe Transport + +Pipe Transport allows communication through a pipe program to a remote shell. An example on Linux would be `ssh`. With the introduction of [Visual Studio Code Remote Development](../remote/remote-overview.md) pipe transport is relevant primarily for IoT scenarios. + +## How-To + +`pipeTransport` is an option within the **launch.json** file. The structure looks as follows: + +```json +"pipeTransport": { + "pipeCwd": "/usr/bin", + "pipeProgram": "/usr/bin/ssh", + "pipeArgs": [ + "-pw", + "", + "user@10.10.10.10" + ], + "debuggerPath": "/usr/bin/gdb" +}, +``` + +The `pipeArgs` can be any set of arguments necessary to set up and authenticate the pipe connection. In the example, a password is used but you can also use an ssh key. + +You may also need to add a `sourceFileMap` to map the path of where the code exists on the remote shell to where it is locally: + +```json +"sourceFileMap": { + // "remote": "local" + "/home/user/src": "/src/projectA/src" +} +``` + +## Attach + +You can also use the above `pipeTransport` block to attach to a remote process. In the attach case, you need to specify a `processId`. The extension can query processes from the remote machine. To do this, change `processId": "${command.pickProcess}` to `processId": "${command.pickRemoteProcess}`. The `pipeTransport` settings will be used to query the processes on the remote machine. Then select the process from the drop-down list. As with `launch`, you may need to configure `sourceFileMap`. + +## Docker example + +The `pipeTransport` can also be used to debug a process in a Docker container. For an attach, **launch.json** will include: + +```json +"pipeTransport": { + "pipeCwd": "${workspaceRoot}", + "pipeProgram": "docker", + "pipeArgs": [ + "exec", + "-i", + "hello_gdb", + "sh", + "-c" + ], + "debuggerPath": "/usr/bin/gdb" +}, +``` + +Where `hello_gdb` is the name of your container. + +Launch process by starting a container and then using the same `pipeTransport` to launch additional processes in the container. See this [**launch.json**](https://github.com/andyneff/hello-world-gdb/blob/master/.vscode/launch.json) for a [full example](https://github.com/andyneff/hello-world-gdb/).