Skip to content

Commit c9a2a13

Browse files
author
mikeblome
committed
new file for launch properties
1 parent d8251d1 commit c9a2a13

4 files changed

Lines changed: 167 additions & 37 deletions

File tree

‎docs/build/cppproperties-schema-reference.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
title: "CppProperties.json schema reference"
3-
ms.date: "08/07/2019"
4-
helpviewer_keywords: ["CMake in Visual Studio"]
3+
ms.date: "08/09/2019"
4+
helpviewer_keywords: ["CppProperties.json file [C++]"]
55
---
66

77
# CppProperties.json schema reference
88

9-
Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a `CppProperties.json` file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. See [Open Folder projects for C++](open-folder-projects-cpp.md) for more information about how to add configurations in an Open Folder project.
9+
Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *CppProperties.json* file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. See [Open Folder projects for C++](open-folder-projects-cpp.md) for more information about how to add configurations in an Open Folder project.
1010

1111
## Configuration properties
1212

@@ -56,7 +56,7 @@ Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only
5656

5757
## Pre-defined Environments
5858

59-
Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using ${env.\<VARIABLE>}.
59+
Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: ${env.\<VARIABLE>}.
6060

6161
|Variable Name|Description|
6262
|-----------|-----------------|
@@ -66,7 +66,6 @@ Visual Studio provides the following predefined environments for Microsoft C++ w
6666
|msvc_arm|Compile for ARM using x86 tools|
6767
|msvc_arm64|Compile for ARM64 using x86 tools|
6868
|msvc_x86_x64|Compile for AMD64 using x86 tools|
69-
|msvc_x64_x64|Compile for AMD64 using 64-bit tools|
7069
|msvc_arm_x64|Compile for ARM using 64-bit tools|
7170
|msvc_arm64_x64|Compile for ARM64 using 64-bit tools|
7271

@@ -78,9 +77,9 @@ When the Linux workload is installed, the following environments are available f
7877
|linux_x64|Target x64 Linux remotely|
7978
|linux_arm|Target ARM Linux remotely|
8079

81-
## User-defined environments
80+
## <a name="user_defined_enviroments"></a> User-defined environments
8281

83-
You can optionally use the `environments` property to define sets of variables in `CppProperties.json` either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally.
82+
You can optionally use the `environments` property to define sets of variables in *CppProperties.json* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed with the ${env.\<VARIABLE>} syntax from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally.
8483

8584
When you consume an environment, then you have to specify it in the `inheritsEnvironments` property even if the environment is defined as part of the same configuration; the `environment` property specifies the name of the environment. The following example shows a sample configuration for enabling IntelliSense for GCC in an MSYS2 installation. Note how the configuration both defines and inherits the `mingw_64` environment, and how the `includePath` property can access the `INCLUDE` variable.
8685

@@ -116,15 +115,17 @@ When you define an **environments** property inside a configuration, it override
116115

117116
## Built-in macros
118117

119-
You have access to the following built-in macros inside `CppProperties.json`:
118+
You have access to the following built-in macros inside *CppProperties.json*:
120119

121120
|||
122121
|-|-|
123122
|`${workspaceRoot}`| The full path to the workspace folder|
124-
|`${projectRoot}`| The full path to the folder where `CppProperties.json` is placed|
123+
|`${projectRoot}`| The full path to the folder where *CppProperties.json* is placed|
125124
|`${env.vsInstallDir}`| The full path to the folder where the running instance of Visual Studio is installed|
126125

127-
For example, if your project has an include folder and also includes windows.h and other common headers from the Windows SDK, you may want to update your `CppProperties.json` configuration file with the following includes:
126+
### Example
127+
128+
If your project has an include folder and also includes *windows.h* and other common headers from the Windows SDK, you may want to update your *CppProperties.json* configuration file with the following includes:
128129

129130
```json
130131
{
@@ -155,6 +156,6 @@ If you are not seeing the IntelliSense that you expect, you can troubleshoot by
155156

156157
![Diagnostic logging](media/diagnostic-logging.png)
157158

158-
Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log*. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *cppproperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data.
159+
Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log*. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *CppProperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data.
159160

160161
To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** and filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...".

‎docs/build/launch-vs-schema-reference-cpp.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: "launch.vs.json schema reference (C++)"
3+
ms.date: "08/09/2019"
4+
helpviewer_keywords: ["CppProperties.json file [C++]"]
5+
---
6+
7+
# launch.vs.json schema reference (C++)
8+
9+
10+
## Default properties
11+
12+
||||
13+
|-|-|-|
14+
|**Property**|**Type**|**Description**|
15+
|name|string|Specifies the name of the entry in the Debug target dropdown.|
16+
|type|string|Specifies whether the project is a dll or .exe (Defaults to .exe)|
17+
|project|string|Specifies the relative path to the project file.|
18+
|projectTarget|string|Specifies the optional target invoked when building 'project'. This projectTarget must exists already and match the name in the Debug Target dropdown.|
19+
|debugType|string|Specifies the debugging mode according to the type of code (native, managed or mixed). This will automatically be detected unless this parameter is set. Allowed values: "native", "managed", "mixed".|
20+
|inheritEnvironments|array|Specifies a set of environment variables inherited from multiple sources. You can define some variables in files like CMakeSettings.json or CppProperties.json and make them available to debug context|
21+
|args|array|Specifies the command-line arguments passed to the launched program.|
22+
|currentDir|string|Specifies the full directory path to the Build Target. This will automatically be detected unless this parameter is set.|
23+
|noDebug|boolean|Specifies whether or not to debug the launched program. The default value for this parameter is false if not specified.|
24+
|stopOnEntry|boolean|Specifies whether or not to break a soon as the process is launched and the debugger attaches. The default value for this parameter is false.|
25+
|remoteMachine|string|Specifies the name of the remote machine where the program is launched.|
26+
|env|array|(Deprecated. Use the `env.NAME` syntax instead.) Specifies a key-value list of custom environment variables. env":{"myEnv":"myVal"}.|
27+
|portName|string|Specifies the name of port when attaching to a running process.|
28+
|buildConfigurations|array| A key-value pair that specifies the name of the build mode to apply the configurations. For example 'Debug' or 'Release' and the configurations to use according to the selected build mode. See example below.
29+
30+
31+
## C++ Linux properties
32+
33+
||||
34+
|-|-|-|
35+
|**Property**|**Type**|**Description**|
36+
|program|string|Full path to program executable on the remote machine. When using CMake the macro ${debugInfo.fullTargetPath} can be used as the value of this field.|
37+
|processId|integer|Optional process id to attach the debugger to.|
38+
|sourceFileMap|object|Optional source file mappings passed to the debug engine. Format: '{ "\<Compiler source location>": "\<Editor source location>" }' OR '{ "\<Compiler source location>": { "editorPath": "\<Editor source location>", "useForBreakpoints": true } }'. Example: '{ "/home/user/foo": "C:\\foo" }' OR '{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }'. See [Source file map options](#source_file_map_otpions).|
39+
|additionalProperties|string|One of the sourceFileMapOptions. (See below.)|
40+
|MIMode|string|Indicates the type of MI-enabled console debugger that the MIDebugEngine will connect to. Allowed values are "gdb", "lldb".|
41+
|args|array|Command line arguments passed to the program|
42+
|environment|array|Environment variables to add to the environment for the program. Example: [ { "name": "squid", "value": "clam" } ].|
43+
|targetArchitecture|string|The architecture of the debuggee. This will automatically be detected unless this parameter is set. Allowed values are x86, arm, arm64, mips, x64, amd64, x86_64.|
44+
|visualizerFile|string|.natvis file to be used when debugging this process. This option is not compatible with GDB pretty printing. Please also see "showDisplayString" if using this setting.|
45+
|showDisplayString|boolean|When a visualizerFile is specified, showDisplayString will enable the display string. Turning this option on can cause slower performance during debugging.|
46+
|remoteMachineName|string|The remote Linux machine which hosts gdb and the program to debug. Please use the Connection Manager for adding new Linux machines. When using CMake the macro ${debugInfo.remoteMachineName} can be used as the value of this field.|
47+
|cwd|string|The working directory of the target on the remote machine. When using CMake the macro ${debugInfo.defaultWorkingDirectory} can be used as the value of this field. Default value is the remote workspace root, unless overridden in the CMakeLists.txt file.|
48+
|miDebuggerPath|string|The path to the MI-enabled debugger (such as gdb). When unspecified, it will search PATH first for the debugger.|
49+
|miDebuggerServerAddress|string|Network address of the MI-enabled debugger server to connect to. Example: localhost:1234.|
50+
|setupCommands|array|One or more GDB/LLDB commands to execute in order to setup the underlying debugger. Example: "setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]. See [Launch setup commands](#launch_setup_commands).|
51+
|customLaunchSetupCommands|array|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 }].|
52+
|launchCompleteCommand|string|The command to execute after the debugger is fully setup in order to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run".|
53+
|debugServerPath|string|Optional full path to debug server to launch. Defaults to null.|
54+
|debugServerArgs|string|Optional debug server args. Defaults to null.|
55+
|filterStderr|boolean|Search stderr stream for server-started pattern and log stderr to debug output. Defaults to false.|
56+
|coreDumpPath|string|Optional full path to a core dump file for the specified program. Defaults to null.|
57+
externalConsole|boolean|If true, a console is launched for the debuggee. If false, no console is launched. Defaults to false. NOTE: This option is ignored in some cases for technical reasons.|
58+
|pipeTransport|string|When present, this tells the debugger to connect to a remote computer using another executable as a pipe that will relay standard input/output between Visual Studio and the MI-enabled debugger (such as gdb). Allowed values: one or more [Pipe Transport Options](#pipe_transport_options).|
59+
60+
61+
## <a name="launch_setup_options"></a> Launch setup commands
62+
63+
Used with the setupCommands property:
64+
65+
||||
66+
|-|-|-|
67+
|text|string|The debugger command to execute.|
68+
|description|string|Optional description for the command.|
69+
|ignoreFailures|boolean|If true, failures from the command should be ignored. Defaults to false.|
70+
71+
## <a name = "pipe_transport_options"></a> Pipe transport options
72+
73+
Used with the pipeTransport property:
74+
75+
||||
76+
|-|-|-|
77+
|pipeCwd|string|The fully qualified path to the working directory for the pipe program.|
78+
|pipeProgram|string|The fully qualified pipe command to execute.|
79+
|pipeArgs|array|Command line arguments passed to the pipe program to configure the connection.|
80+
|debuggerPath|string|The full path to the debugger on the target machine, for example /usr/bin/gdb.|
81+
|pipeEnv|object|Environment variables passed to the pipe program.|
82+
|quoteArgs|boolean|If individual arguments contain characters (such as spaces or tabs), should it be quoted? If 'false', the debugger command will no longer be automatically quoted. Default is 'true'.|
83+
84+
## <a name="source_file_map_otpions"></a> Source file map options
85+
86+
Use with the sourceFIleMap property:
87+
88+
||||
89+
|-|-|-|
90+
|editorPath|string|The location of the source code for the editor to locate.|
91+
|useForBreakpoints|boolean|When setting breakpoints, this source mapping should be used. If 'false', only the filename and line number is used for setting breakpoints. If 'true', breakpoints will be set with the full path to the file and line number only when this source mapping is used. Otherwise just filename and line number will be used when setting breakpoints. Default is 'true'.|
92+

0 commit comments

Comments
 (0)