Merge pull request #1142 from csholmq/patch-1

Typo

Documentation/Debugger/gdb/Windows Subsystem for Linux.md

@@ -1,9 +1,9 @@
 # Windows 10's Windows Subsystem for Linux
-With the release of Windows 10 Creators Update, you will now be able to use Visual Studio Code and the Microsoft C/C++ extension to debug your `Windows Subsystem for Linux (WSL)` [Bash on Ubuntu](https://msdn.microsoft.com/en-us/commandline/wsl/about) projects.
+With the release of Windows 10 Creators Update (Build 15063), you will now be able to use Visual Studio Code and the Microsoft C/C++ extension to debug your `Windows Subsystem for Linux (WSL)` [Bash on Ubuntu](https://msdn.microsoft.com/en-us/commandline/wsl/about) projects.
 
 Code can be written on Windows itself using VSCode and debugged through `bash.exe` to the Bash on Windows layer. 
 
-**NOTE: Creator's Update is required due to bugfixes within the subsystem that we rely on to provide debugging. Debugging using a previous version of WSL is unsupported and likely will not work.**
+**NOTE: Creator's Update (Build 15063 or later) is required due to bugfixes within the subsystem that we rely on to provide debugging. Debugging using a previous version of WSL is unsupported and likely will not work. To check your Windows version, enter `winver` in a command prompt.**
 
 ## Prerequisites
 * [Windows 10 Creators Update with Windows Subsystem for Linux and Bash](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) installed.
@@ -83,4 +83,4 @@ This configuration similar to the launch process above. I have chosen to start t
                 "/mnt/z": "z:\\"
             }
         }
-```
+```

Documentation/Getting started.md

@@ -0,0 +1,21 @@
+# Getting started
+
+## Configuring IntelliSense
+
+**Quick summary**: Open your settings file and add `"C_Cpp.intelliSenseEngine": "Default"` to preview the new and improved IntelliSense. Then add the necessary include paths and preprocessor defines to your c_cpp_properties.json file so that IntelliSense can find your symbols.
+
+#### The IntelliSense engines
+
+When the extension was first released, we shipped an IntelliSense engine that provided quick, but "fuzzy" results for common operations like auto-complete, parameter help, quick info tooltips, and goto definition. This "tag parser" built up a database of symbols by parsing the most important "tags" from your source files, ignoring preprocessor blocks, local variables, and most errors. More recently, we have begun the process of porting the MSVC IntelliSense engine from Visual Studio to VS Code to provide more accurate results. 
+
+You can choose the engine that works best for your projects 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 (in preview, the default for VS Code Insiders)
+* `"Tag Parser"` - use the "fuzzy" IntelliSense engine (the default for users on the stable VS Code build)
+
+#### Include paths
+
+In order to get accurate IntelliSense results with either engine, the extension needs some information about your project.  When you open a folder, the extension will attempt to locate your system headers based on your operating system, but it does not know about any auxiliary libraries that your project depends on.  You can specify the remaining paths by using the `"C/Cpp: Edit Configurations"` command in the command palette.
+
+This command will create or open a file called **c_cpp_properties.json** in your workspace.  In this file, you can specify the paths to the headers that your project depends on.  There are two settings in this file that you should pay particular attention to: `"includePath"` and `"browse.path"`.  `"includePath"` is the setting used by the `"Default"` IntelliSense engine and `"browse.path"` is the setting used by the tag parser engine.  [More information about these settings is documented here](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/FAQ.md#what-is-the-difference-between-includepath-and-browsepath-in-c_cpp_propertiesjson).
+

Documentation/LanguageServer/Enabling logging.md

@@ -0,0 +1,16 @@
+# 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 is controlled by environment variables and is disabled by default. To enable logging, launch VS Code from an environment that contains the following variables:
+
+```
+VSCODE_CPP_LOGDIR=c:\path\to\logfolder
+VSCODE_CPP_LOGFILE_LEVEL=5
+```
+
+When you open your folder in VS Code, we will create a vscode.cpp.log.\<pid\>.txt file for each extension process launched (\<pid\> = process id).
+
+The log file level is a number that determines how much detail we'll log. Level 5 is generally detailed enough to give us information about what is going on in your session. We don't recommend you set this higher than 7 since the log quickly becomes cluttered with information that doesn't really help us diagnose your issues and actually makes it harder for us to spot problems. It may also slow down the extension considerably and make it harder for you to reproduce your problem.
+
+**Don't forget to remove the environment variables when you are finished providing us with the logs.** You wouldn't want the extension to needlessly spend CPU time and disk space writing data you don't need into log files.

Documentation/LanguageServer/FAQ.md

@@ -1,38 +1,35 @@
 # Frequently asked questions
 
-[Why do I have red underlines everywhere after updating to the latest version](#why-do-i-have-red-underlines-everywhere-after-updating-to-the-latest-version)?
+[How do I get IntelliSense to work correctly](#how-do-i-get-intellisense-to-work-correctly)?
 
 [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)?
 
 [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)?
 
-## Why do I have red underlines everywhere after updating to the latest version?
+[How do I re-create the IntelliSense database](#how-do-i-re-create-the-intellisense-database)?
 
-If you are using the VS Code Insider build with version 0.11.0 or higher of the cpptools extension or any build of VS Code with version 0.11.1 of the extension, then the extension will default to using the new IntelliSense engine for linting and providing quick info tooltips in your source files.
+## How do I get IntelliSense to work correctly?
 
-For some users this may result in a large number of red underlines ("squiggles") appearing in your source files. There are a few things you can do to resolve this issue. Select the one that best meets your needs for your situation.
+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 our new IntelliSense engine which has more accurate auto-complete 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.
 
-1. Update your includePath and defines
-2. Disable the error squiggles
-3. Disable the new IntelliSense engine
+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 lightbulb will appear in the editor with some options (code actions) to help you resolve the problem.
 
-#### Update your includePath and defines
+1. Update your includePath (and preprocessor defines)
+2. Force semantic IntelliSense
 
-If you haven't already created a c_cpp_properties.json file for your project, you can do so by selecting "C/Cpp: Edit Configurations" from the command palette. This will create and open the c_cpp_properties.json file for you. 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 "\<var\>" and "\<var\>=\<value\>" 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.
+#### Update your includePath (and preprocessor defines)
 
-#### Disable the error squiggles
+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.
 
-If you want to keep using the semantic-aware features that will be coming online via the new IntelliSense engine, but don't want to see the error squiggles in the editor, then you can disable the lint messages by adding `"C_Cpp.errorSquiggles": "Disabled"` to your settings.json file.
+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 "\<var\>" and "\<var\>=\<value\>" 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.
 
-#### Disable the new IntelliSense engine
+#### Force semantic IntelliSense
 
-If you were happy with the old behavior of the extension or want to wait to get the semantic-aware features until build system support arrives in the extension so that you don't have to manually configure a c_cpp_properties.json file, you can disable the new IntelliSense engine entirely by adding `"C_Cpp.intelliSenseEngine": "Tag Parser"` to your settings.json file.
+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"`.
 
 ## How do I get the new IntelliSense to work with MinGW on Windows?
 
-On Windows PCs, the new IntelliSense engine is configured to compile your source files in Microsoft mode. But since MinGW is a relative of GCC, Microsoft mode compilation doesn't work very well with it. While the IntelliSense engine supports compiling code in clang/gcc mode, the extension does not currently expose any settings that allow you to configure it.
-
-You can, however, override the engine's configuration by changing the contents of the  `%userprofile%\.vscode\extensions\ms-vscode.cpptools-0.11.1\bin\msvc.64.intel.json` file. In fact, copying `msvc.64.linux.json` over `msvc.64.intel.json` will reconfigure the engine to compile your source code in clang mode. The caveat is that making changes to the `msvc.64.intel.json` is not a permanent operation. The next time you upgrade the extension, your changes will be reverted. However, this workaround should be able to enable you to use the new IntelliSense engine with MinGW until we have time to expose a proper setting.
+Since MinGW is a relative of GCC, Microsoft mode compilation (which is the default on Windows) doesn't work very well with it. To use GCC/CLang mode, set the `"intelliSenseMode"` property in your **c_cpp_properties.json** file to `"clang-x64"`. An example **c_cpp_properties.json** [is shared here for your convenience](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/MinGW.md).
 
 ## What is the difference between "includePath" and "browse.path" in c\_cpp\_properties.json?
 
@@ -48,4 +45,8 @@ The paths that you specify for this setting are the same paths that you would se
 
 **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.
 
-The extension will also implicitly add `${workspaceRoot}` to the array of paths unless `"C_Cpp.addWorkspaceRootToIncludePath"` is explicitly set to `false` in your settings.json file.
+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.

Documentation/LanguageServer/MinGW.md

@@ -0,0 +1,76 @@
+For developers using MinGW on Windows, we recommend you start with the following **c_cpp_properties.json** template.  Select "C/Cpp: Edit Configurations" from the command palette to create this file if you haven't already.
+
+Note that you may have to change the MinGW version number to match what you have installed. Eg. `C:/MinGW/lib/gcc/mingw32/5.3.0/` instead of `C:/MinGW/lib/gcc/mingw32/6.3.0/`.
+
+```
+{
+    "configurations": [
+        {
+            "name": "Win32",
+            "intelliSenseMode": "clang-x64",
+            "includePath": [
+                "${workspaceRoot}",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include/c++",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include/c++/mingw32",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include/c++/backward",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include",
+                "C:/MinGW/include",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include-fixed"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "__GNUC__=6",
+                "__cdecl=__attribute__((__cdecl__))"
+            ],
+            "browse": {
+                "path": [
+                    "C:/MinGW/lib/gcc/mingw32/6.3.0/include",
+                    "C:/MinGW/lib/gcc/mingw32/6.3.0/include-fixed",
+                    "C:/MinGW/include/*"
+                ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+    ]
+}
+```
+
+The `includePath` above includes the system header paths that gcc uses in version 6.3.0 for C++ projects and matches the output of `gcc -v -E -x c++ -`. The `intelliSenseMode` should be set to **"clang-x64"** to get MinGW projects to work properly with IntelliSense. The `__GNUC__=#` define should match the major version of the toolchain in your installation (6 in this example).
+
+For C projects, simply remove the c++ lines:
+
+```
+{
+    "configurations": [
+        {
+            "name": "Win32",
+            "intelliSenseMode": "clang-x64",
+            "includePath": [
+                "${workspaceRoot}",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include",
+                "C:/MinGW/include",
+                "C:/MinGW/lib/gcc/mingw32/6.3.0/include-fixed"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "__GNUC__=6",
+                "__cdecl=__attribute__((__cdecl__))"
+            ],
+            "browse": {
+                "path": [
+                    "C:/MinGW/lib/gcc/mingw32/6.3.0/include",
+                    "C:/MinGW/lib/gcc/mingw32/6.3.0/include-fixed",
+                    "C:/MinGW/include/*"
+                ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+    ]
+}
+```
+
+With these configurations, you should be all set up to use the new IntelliSense engine for linting, memberlist autocomplete, and quick info (tooltips).  Add `"C_Cpp.intelliSenseEngine": "Default"` to your **settings.json** file to try out the new IntelliSense engine.

Documentation/LanguageServer/Windows Subsystem for Linux.md

@@ -0,0 +1,75 @@
+For developers using the Windows Subsystem for Linux, we recommend you start with the following **c_cpp_properties.json** template.  Select "C/Cpp: Edit Configurations" from the command palette to create this file if you haven't already.
+
+```
+        {
+            "name": "WSL",
+            "intelliSenseMode": "clang-x64",
+            "includePath": [
+                "${workspaceRoot}",
+                "${localappdata}/lxss/rootfs/usr/include/c++/5",
+                "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu/c++/5",
+                "${localappdata}/lxss/rootfs/usr/include/c++/5/backward",
+                "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include",
+                "${localappdata}/lxss/rootfs/usr/local/include",
+                "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include-fixed",
+                "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu",
+                "${localappdata}/lxss/rootfs/usr/include"
+            ],
+            "defines": [
+                "__linux__",
+                "__x86_64__"
+            ],
+            "browse": {
+                "path": [
+                    "${localappdata}/lxss/rootfs/usr/include/c++/5",
+                    "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu/c++/5",
+                    "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include",
+                    "${localappdata}/lxss/rootfs/usr/local/include",
+                    "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include-fixed",
+                    "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu",
+                    "${localappdata}/lxss/rootfs/usr/include/*"
+                ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+
+```
+
+The `includePath` above includes the system header paths that gcc uses for C++ projects and matches the output of `gcc -v -E -x c++ - < /dev/null`. The intelliSenseMode should be set to **"clang-x64"** to get WSL projects to work properly with IntelliSense.
+
+For C projects, simply remove the c++ lines:
+
+```
+        {
+            "name": "WSL",
+            "intelliSenseMode": "clang-x64",
+            "includePath": [
+                "${workspaceRoot}",
+                "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include",
+                "${localappdata}/lxss/rootfs/usr/local/include",
+                "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include-fixed",
+                "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu",
+                "${localappdata}/lxss/rootfs/usr/include"
+            ],
+            "defines": [
+                "__linux__",
+                "__x86_64__"
+            ],
+            "browse": {
+                "path": [
+                    "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include",
+                    "${localappdata}/lxss/rootfs/usr/local/include",
+                    "${localappdata}/lxss/rootfs/usr/lib/gcc/x86_64-linux-gnu/5/include-fixed",
+                    "${localappdata}/lxss/rootfs/usr/include/x86_64-linux-gnu",
+                    "${localappdata}/lxss/rootfs/usr/include/*"
+                ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+```
+
+With these configurations, you should be all set up to use the new IntelliSense engine for linting, memberlist autocomplete, and quick info (tooltips).  Add `"C_Cpp.intelliSenseEngine": "Default"` to your **settings.json** file to try out the new IntelliSense engine.
+
+And remember to [heed the warnings of the Windows team about not creating or editing Linux files from a Windows app](https://blogs.msdn.microsoft.com/commandline/2016/11/17/do-not-change-linux-files-using-windows-apps-and-tools/)! 

Documentation/LanguageServer/c_cpp_properties.json.md

@@ -0,0 +1,47 @@
+# c_cpp_properties.json Reference Guide
+
+### Example:
+```
+{
+    "configurations": [
+        {
+            "name": "Win32",
+            "intelliSenseMode": "msvc-x64",
+            "includePath": [ "${workspaceRoot}" ],
+            "defines": [ "FOO", "BAR=100" ],
+            "browse": {
+                "path": [ "${workspaceRoot}" ],
+                "limitSymbolsToIncludedHeaders": true,
+                "databaseFilename": ""
+            }
+        }
+    ],
+    "version": 2
+}
+```
+
+## Top-level properties
+
+**configurations**: An array of configuration objects that provide the IntelliSense engine with information about your project and your preferences. By default, the extension creates 3 configurations for you, one each for Linux, Mac, and Windows, but it is not required to keep them all. You may also add additional configurations if necessary.
+
+**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 GCC/CLang mode with 64-bit pointer sizes. Windows uses `"msvc-x64"` by default and Linux/Mac use `"clang-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; 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 is basically the same as the list of symbols you pass to your compiler with the `-D` switch.
+
+**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).
+
+### Browse properties
+
+**path**: This list of paths will be used by the Tag Parser to search for headers included by your source files. 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 the ${workspaceRoot}. 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 ${workspaceRoot} variable can be used to specify a path relative to the workspace folder (e.g. $[workspaceRoot}/.vscode/browse.vc.db)

ISSUE_TEMPLATE.md

@@ -0,0 +1,16 @@
+<!--
+  If this is a bug report, please give us as much information as possible so we can reproduce your issue.
+  Examples of information that can help us find and fix bugs:
+    * Operating System and version
+    * VS Code version and if you are using the Insiders build
+    * C/C++ extension version
+    * Other extensions you installed and if the issue persists after disabling them
+    * step-by-step instructions to reproduce the issue
+    * A small code sample, zipped up project, or open source repo we can use to verify the bug
+    * Relevant settings from your settings.json, c_cpp_properties.json, and/or launch.json files
+
+  Please also take a look at our documentation, as we may already have answers for your questions:
+    * https://github.com/Microsoft/vscode-cpptools/tree/master/Documentation
+
+  Thank you!
+-->

README.md

@@ -6,4 +6,4 @@ This repo is the official repository for filing issues against and getting suppo
 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]](mailto:[email protected]) with any additional questions or comments. 
 
 ### Documentation
-Documentation has been moved to a folder marked Documentation within the repository. If you would like to contribute, please create markdown file and submit a pull request.
+Documentation has been moved to a folder marked Documentation within the repository. If you would like to contribute, please create a markdown file and submit a pull request.