Merge pull request #1382 from Microsoft/users/piel/merge

Move extension code to github.

Author: pieandcakes

Code Samples/SampleClangProject/.gitignore

@@ -0,0 +1,2 @@
+main.exe
+main.exe.dSYM

Code Samples/SampleClangProject/.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "(lldb) Launch",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceRoot}/main.exe", // this is executable to launch the debugger with
+            "args": ["YourNameHere"],
+            "stopAtEntry": true, // if true then stop at the main entry (function)
+            "cwd": "${workspaceRoot}",
+            "environment": [],
+            "externalConsole": true,
+            "MIMode": "lldb"
+        }
+    ]
+}

Code Samples/SampleClangProject/.vscode/tasks.json

@@ -0,0 +1,19 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "taskName": "clang++",
+            "command": "clang++ --debug -o main.exe main.cpp",
+                // "--debug" enables debugging symbols
+                // "-o main.exe" specifies the output executable
+                // "main.cpp" is the source file to compile
+            "type": "shell",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

Code Samples/SampleClangProject/README.md

@@ -0,0 +1,10 @@
+# README
+This is a sample debuggable C++ project. It uses the vendor provided version of clang installed. `tasks.json` and `launch.json` have been edited to demonstrate how to create a configuration for a C++ project that builds with clang.
+
+There's a sample build task in `.vscode/tasks.json`; you can also see the build configurations by using the menu option `Configure` -> `Configure Tasks` or by clicking the gear icon in the Debug Panel.
+
+To run a build, use the menu option `Tasks` -> `Run Build Task...`.
+
+There's a sample debug configuration in `.vscode/launch.json`; you can also see the configuration by using the menu option `Debug` -> `Open Configurations`.
+
+To debug the build, use the menu option `Debug` -> `Start Debugging`. The executable will launch and stop in the main function.

Code Samples/SampleClangProject/main.cpp

@@ -0,0 +1,17 @@
+#include <iostream>
+#include <string>
+
+using namespace std;
+
+void greet(const string& person) {
+    cout << "Hello, " << person << "!" << endl;
+}
+
+int main(int argc, char** argv) {
+    if(argc >= 2) {
+        greet(argv[1]);
+    } else {
+        cerr << "insufficient args, usage: " << argv[0] << " personNameHere" << endl;
+    }
+    return 0;
+}

Documentation/FAQs.md

@@ -0,0 +1,51 @@
+# FAQs
+
+## Table of Contents
+* Setup
+  * [Debugging Setup](#debugging-setup)
+
+* Debugger
+  * [Why is debugging not working](#why-is-debugging-not-working)?
+* Build
+  * [How to enable debug symbols](#how-to-enable-debug-symbols)
+
+## Debugging Setup
+The debugger needs to be configured to know which executable and debugger to use:
+
+Click menu item: `Debug` -> `Add Configuration...`
+
+The `launch.json` will now be open for editing with a new configuration. The default settings will *probably* work except that you need to specify the **program** setting.
+
+See the [`Documentation/Debugger`](https://github.com/Microsoft/vscode-cpptools/tree/master/Documentation/Debugger) folder in this repository for more in-depth documentation on how to configure the debugger.
+
+## Why is debugging not working?
+
+### My breakpoints aren't being hit
+
+When you start debugging, if it is showing that your breakpoints aren't bound (solid red circle) or they are not being hit, you may need to enable [debug symbols](#how-to-enable-debug-symbols) during compilation. 
+
+### Debugging starts but all the lines in my stack trace are grey
+
+If your debugger is showing a grey stacktrace or won't stop at a breakpoint,or the symbols in the call stack are grey then your executable was compiled without [debug symbols](#how-to-enable-debug-symbols).
+
+## How to enable debug symbols
+
+Enabling debug symbols are dependent on the type of compiler you are using. Below are some of the compilers and the compiler options necessary to enable debug symbols.
+
+When in doubt, please check your compiler's documentation for the options necessary to include debug symbols in the output. This may be some variant of `-g` or `--debug`.
+
+#### Clang (C++)
+If you invoke the compiler manually then add the `--debug` option.
+
+If you're using a script then make sure the `CXXFLAGS` environment variable is set; e.g. `export CXXFLAGS="${CXXFLAGS} --debug"`
+
+If you're using cmake then set make sure the `CMAKE_CXX_FLAGS` is set; e.g. `export CMAKE_CXX_FLAGS=${CXXFLAGS}`
+
+#### Clang (C)
+See Clang C++ but use `CFLAGS` instead of `CXXFLAGS`.
+
+#### gcc or g++
+If you invoke the compiler manually, add the `-g` option.
+
+#### cl.exe
+Symbols are located in the `*.pdb` file.

Documentation/Getting started.md

@@ -1,3 +1,19 @@
+## 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/msvscode-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`
+        * This 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.
+  * [How to contribute changes](LanguageServer/How%20to%20Contribute%20Changes.md).
+
 # 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.

Documentation/LanguageServer/How to Contribute Changes.md

@@ -0,0 +1,18 @@
+# How to Contribute Changes
+
+## Contribution Steps:
+  * [Build and debug the extension](../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/extension.test.ts).
+  * Run tests via opening the [Extension](https://github.com/Microsoft/vscode-cpptools/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/Extension/src/Debugger) folder.
+  * [LanguageServer/C_Cpp.ts](../../Extension/src/LanguageServer/C_Cpp.ts) handles various language server functionality.
+  * [LanguageServer/C_Cpp_ConfigurationProperties.ts](../../Extension/src/LanguageServer/C_Cpp_ConfigurationProperties.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.

Extension/.gitattributes

@@ -0,0 +1,3 @@
+*.sh text eol=lf
+OpenDebugAD7 text eol=lf
+link-binaries text eol=lf

Extension/.gitignore

@@ -0,0 +1,5 @@
+out
+server
+node_modules
+debugAdapters
+*.vsix