Merge pull request #1557 from Microsoft/master

Merge for release.

Author: sean-mcmanus

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+## Microsoft Open Source Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [email protected] with any additional questions or comments.

CONTRIBUTING.md

@@ -1,18 +1,20 @@
 # How to Contribute Changes
 
-## Contribution Steps:
-  * [Build and debug the extension](Documentation/Getting%20started.md#build-and-debug-the-cpptools-extension).
-  * File an [issue](https://github.com/Microsoft/vscode-cpptools/issues) and a [pull request](https://github.com/Microsoft/vscode-cpptools/pulls) with the change and we will review it.
-  * If the change affects functionality, add a line describing the change to [CHANGELOG.md](Extension/CHANGELOG.md).
-  * Try and add a test in [test/extension.test.ts](Extension/test/unitTests/extension.test.ts).
-  * Run tests via opening the [Extension](https://github.com/Microsoft/vscode-cpptools/tree/master/Extension) folder in Visual Studio Code, selecting the `Launch Tests` configuration in the Debug pane, and choosing `Start Debugging`.
+## Contribution Steps
+
+* [Build and debug the extension](Documentation/Getting%20started.md#build-and-debug-the-cpptools-extension).
+* File an [issue](https://github.com/Microsoft/vscode-cpptools/issues) and a [pull request](https://github.com/Microsoft/vscode-cpptools/pulls) with the change and we will review it.
+* If the change affects functionality, add a line describing the change to [**CHANGELOG.md**](Extension/CHANGELOG.md).
+* Try and add a test in [**test/extension.test.ts**](Extension/test/unitTests/extension.test.ts).
+* Run tests via opening the [**Extension**](https://github.com/Microsoft/vscode-cpptools/tree/master/Extension) folder in Visual Studio Code, selecting the "Launch Tests" configuration in the Debug pane, and choosing "Start Debugging".
 
 ## About the Code
-  * Execution starts in the `activate` method in [main.ts](Extension/src/main.ts).
-    * `processRuntimeDependencies` handles the downloading and installation of the OS-dependent files. Downloading code exists in [packageManager.ts](Extension/src/packageManager.ts).
-    * `downloadCpptoolsJsonPkg` handles the `cpptools.json`, which can be used to enable changes to occur mid-update, such as turning the `intelliSenseEngine` to `"Default"` for a certain percentage of users.
-  * The debugger code is in the [Debugger](https://github.com/Microsoft/vscode-cpptools/tree/master/Extension/src/Debugger) folder.
-  * [LanguageServer/client.ts](Extension/src/LanguageServer/client.ts) handles various language server functionality.
-  * [LanguageServer/configurations.ts](Extension/src/LanguageServer/configurations.ts) handles functionality related to `c_cpp_properties.json`.
-  * [telemetry.ts](Extension/src/telemetry.ts): Telemetry data gets sent to either `logLanguageServerEvent` or `logDebuggerEvent`.
-  * The Tag Parser (symbol database) doesn't automatically expand macros, so the [cpp.hint](Extension/cpp.hint) file contains definitions of macros that should be expanded in order for symbols to be parsed correctly.
+
+* Execution starts in the `activate` method in [**main.ts**](Extension/src/main.ts).
+  * `processRuntimeDependencies` handles the downloading and installation of the OS-dependent files. Downloading code exists in [**packageManager.ts**](Extension/src/packageManager.ts).
+  * `downloadCpptoolsJsonPkg` handles the **cpptools.json**, which can be used to enable changes to occur mid-update, such as turning the `intelliSenseEngine` to `"Default"` for a certain percentage of users.
+* The debugger code is in the [**Debugger**](https://github.com/Microsoft/vscode-cpptools/tree/master/Extension/src/Debugger) folder.
+* [**LanguageServer/client.ts**](Extension/src/LanguageServer/client.ts) handles various language server functionality.
+* [**LanguageServer/configurations.ts**](Extension/src/LanguageServer/configurations.ts) handles functionality related to **c_cpp_properties.json**.
+* [**telemetry.ts**](Extension/src/telemetry.ts): Telemetry data gets sent to either `logLanguageServerEvent` or `logDebuggerEvent`.
+* The Tag Parser (symbol database) doesn't automatically expand macros, so the [**cpp.hint**](Extension/cpp.hint) file contains definitions of macros that should be expanded in order for symbols to be parsed correctly.

Documentation/Building the Extension.md

@@ -0,0 +1,14 @@
+## How to build and debug the Microsoft CppTools Extension  
+  
+These steps will allow you to debug the TypeScript code that is part of the Microsoft CppTools extension for Visual Studio Code.  
+  
+Prerequisite steps:  
+  * Clone [this](https://github.com/Microsoft/vscode-cpptools) repository.  
+  * Install [npm](https://nodejs.org).  
+  * From a command line, run the following commands from the **Extension** folder in the root of the repository:  
+      * `npm install -g vsce` will install `vsce` globally to create the vsix package.  
+      * `npm install` will install the dependencies needed to build the extension.  
+  * Set an environment variable `CPPTOOLS_DEV=1`.  
+    * This enables the local developer workflow, copying dependencies from the **node_modules** folder.  
+  * Open the **Extension** folder in Visual Studio Code and F5.  
+  * Read the [contributing guidelines](https://github.com/Microsoft/vscode-cpptools/blob/master/CONTRIBUTING.md).  

Documentation/Debugger/How To Debug MIEngine.md

@@ -1,15 +1,16 @@
 # How To Debug MIEngine (Work in Progress)
+
 *This is a work in progress. Please create a pull request with updates if there is anything wrong with it.*
 
-MIEngine is one of the components used to enable the C/C++ debugging scenario with the Microsoft C/C++ extension with VS Code. This document is to help enable users who want to debug and contribute to MIEngine to fix issues or extend functionality. MIEngine is used to communicate with `gdb/lldb` using the MI protocol. 
+MIEngine is one of the components used to enable the C/C++ debugging scenario with the Microsoft C/C++ extension with VS Code. This document is to help enable users who want to debug and contribute to MIEngine to fix issues or extend functionality. MIEngine is used to communicate with `gdb`/`lldb` using the MI protocol. 
 
 **Repository:** https://github.com/Microsoft/MIEngine
 
 ## To Build
 
 To build MIEngine, you will either need Visual Studio 2015+ installed or at the very least [MSBuild](https://github.com/Microsoft/msbuild) installed. The configuration you want to build is `Desktop.Debug`.
 
-You can open the solution file `MIDebugEngine.sln` located under `src` and change the configuration and build. You will want to look in the `bin\Desktop.Debug` folder for the compiled bits. You will need to copy the following files to your `.vscode\extensions\ms-vscode.cpptools-<version>\debugadapters\bin` folder in your users/home folder:
+You can open the solution file **MIDebugEngine.sln** located under **src** and change the configuration and build. You will want to look in the **bin\Desktop.Debug** folder for the compiled bits. You will need to copy the following files to your **.vscode\extensions\ms-vscode.cpptools-\<version\>\debugadapters\bin** folder in your users/home folder:
 
 * Microsoft.MICore.dll
 * Microsoft.MICore.XmlSerializers.dll
@@ -27,7 +28,7 @@ The symbol files are as follows:
 
 ### Debugging On Windows
 
-On Windows, the easiest way to debug is to use Visual Studio. Locate the `package.json` file in the extension folder and open it in an editor.
+On Windows, the easiest way to debug is to use Visual Studio. Locate the **package.json** file in the **Extension** folder and open it in an editor.
 
 Locate the following line: 
 ```json
@@ -49,29 +50,32 @@ On Linux and Mac OS X, we use `mono` as our framework. You can download Xamarin
 2. Install [Xamarin Studio v5.10.1.6](http://download.xamarin.com/studio/Windows/XamarinStudio-5.10.1.6-0.msi)
 
 Remote attach functionality behind a flag.  You can run it like this:
-```
-    cd "\Program Files (x86)\MonoDevelop\bin"
-    set MONODEVELOP_SDB_TEST=1
-    MonoDevelop.exe
+```PowerShell
+cd "\Program Files (x86)\MonoDevelop\bin"
+set MONODEVELOP_SDB_TEST=1
+MonoDevelop.exe
 ```
 
 #### Create an empty project for attaching (one-time setup)
+
 1. Launch MonoDevelop
 2. File -> New Solution
 3. Misc/Generic Project
 4. Name project and hit "Create"
 5. Right-click the project node (blue square) and do "Options"
-6. Under Run -> Custom Commands, select "Execute" in the lower dropdown and choose a command (I use c:\windows\notepad.exe - it doesn't matter what the command is, but MonoDevelop requires it to exist before it'll light up the Run menu).
+6. Under Run -> Custom Commands, select "Execute" in the lower dropdown and choose a command (I use `c:\windows\notepad.exe` - it doesn't matter what the command is, but MonoDevelop requires it to exist before it'll light up the Run menu).
 
 #### Configure the extension to enable remote debugging
-Open the `~/.vscode/extensions/ms-vscode.cpptools-<version>/debugAdapters/OpenDebugAD7` file with a text editor and locate and uncomment the line at the bottom. When you start debugging, it will now hang until the remote debugger is attached from Xamarin Studio. 
+
+Open the **~/.vscode/extensions/ms-vscode.cpptools-\<version\>/debugAdapters/OpenDebugAD7** file with a text editor and locate and uncomment the line at the bottom. When you start debugging, it will now hang until the remote debugger is attached from Xamarin Studio. 
 
 #### Attach the remote debugger
+
 In MonoDevelop: Run -> Run With -> Custom Command Mono Soft Debugger
 Fill in the IP and port of the Linux/Mac OS X machine and hit "Connect" to start debugging
 
-After you've done this once, you can hit the MonoDevelop "Play" button or F5 to bring up the connect dialog again.
+After you've done this once, you can hit the MonoDevelop "Play" button or <kbd>F5</kbd> to bring up the connect dialog again.
 
 Note: If you are debugging to CentOS, you will need to make an exception in the firewall
-* sudo firewall-cmd --zone=public --add-port=1234/tcp --permanent
-* sudo firewall-cmd --reload
+* `sudo firewall-cmd --zone=public --add-port=1234/tcp --permanent`
+* `sudo firewall-cmd --reload`

Documentation/Debugger/gdb/PipeTransport.md

@@ -1,52 +1,54 @@
 # Pipe Transport
-Pipe Transport allows communication through a pipe program to a remote shell. An example on linux would be `ssh`.
+
+Pipe Transport allows communication through a pipe program to a remote shell. An example on Linux would be `ssh`.
 
 ## How-To
-We have added `"pipeTransport"` as an option within the `launch.json` file. The structure looks as follows:
-```
-    "pipeTransport": {
-        "pipeCwd": "/usr/bin",
-        "pipeProgram": "/usr/bin/ssh",
-        "pipeArgs": [
-            "-pw",
-            "<password>",
-            "[email protected]"
-        ],
-        "debuggerPath": "/usr/bin/gdb"
-    },
+
+We have added `"pipeTransport"` as an option within the **launch.json** file. The structure looks as follows:
+```json
+"pipeTransport": {
+    "pipeCwd": "/usr/bin",
+    "pipeProgram": "/usr/bin/ssh",
+    "pipeArgs": [
+        "-pw",
+        "<password>",
+        "[email protected]"
+    ],
+    "debuggerPath": "/usr/bin/gdb"
+},
 ```
 The `pipeArgs` can be any set of arguments necessary to setup 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:
-```
-    "sourceFileMap": {
-        // "remote": "local"
-        "/home/user/src": "/src/projectA/src"
-    }
+```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 will need to specify a `processId`. We have added the ability to 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, the `launch.json` will include:
-
+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"
+},
 ```
-    "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.
 
-Launching a process is accomplished by starting a container and then using the same `pipeTransport` 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/)
+Launching a process is accomplished by starting a container and then using the same `pipeTransport` 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/).