Deprecate old documentation and update readme files (#3984)

microsoft · sean-mcmanus · Aug 21, 2019 · Jul 4, 2019 · Jul 4, 2019 · Jul 5, 2019
commit d3d96555340f28eb9cc214fc2d03a9830f7b524a
diff --git a/Documentation/Debugger/gdb/PipeTransport.md b/Documentation/Debugger/gdb/PipeTransport.md
@@ -1,54 +1 @@
-# Pipe Transport
-
-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:
-```json
-"pipeTransport": {
-    "pipeCwd": "/usr/bin",
-    "pipeProgram": "/usr/bin/ssh",
-    "pipeArgs": [
-        "-pw",
-        "<password>",
-        "user@10.10.10.10"
-    ],
-    "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:
-```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, **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.
-
-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/).
+The documentation for pipe transport has moved to https://code.visualstudio.com/docs/cpp/pipe-transport.
diff --git a/Documentation/Debugger/gdb/Windows Subsystem for Linux.md b/Documentation/Debugger/gdb/Windows Subsystem for Linux.md
@@ -1,91 +1 @@
-# Windows 10's Windows Subsystem for Linux
-
-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)](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.
-
-As of the Fall Creator's Update, you can have multiple distros installed, but `bash.exe` and `wsl.exe` use the default distro. Use [WSL Config](https://msdn.microsoft.com/en-us/commandline/wsl/wsl-config) to set your default distro.
-
-**NOTE: Creator's Update (Build 15063 or later) is required due to bug-fixes 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 or later with Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) installed.
-* Install g++/gcc and gdb within `WSL` to allow compiling and debugging. You can use the package manager to do this. For example, to install g++, you can run `sudo apt install g++` in the Bash window.
-* [Visual Studio Code](https://code.visualstudio.com) + Microsoft C/C++ extension for VSCode.
-
-## How-To
-
-To debug, commands will be routed from Windows through `bash.exe` to set up debugging. Because our extension runs as a 32-bit process, it will need to use the `C:\Windows\SysNative` folder to access the `bash.exe` executable that is normally in `C:\Windows\System32`. We will be using the `"pipeTransport"` ability within the extension to do debugging and `"sourceFileMap"` to map the source from the subsystem's paths back to Windows path.
-
-**NOTE: Applications will need to be compiled in the `Windows Subsystem for Linux (WSL)` prior to debugging.**
-
-### Example `launch.json` for Launching
-
-In the following example, I have a local drive, `Z:\` that has my source code within windows for an app called _kitchensink_. I have set up the `"program"` and `"cwd"` paths to point to the directory within `WSL`. I have set up the `"pipeTransport"` to use `bash.exe`. I have also set up a `"sourceFileMap"` to have everything that is returned by `gdb` that starts with `/mnt/z` to point to `Z:\\` in Windows.
-
-```json
-{
-    "name": "C++ Launch",
-    "type": "cppdbg",
-    "request": "launch",
-    "program": "/mnt/z/Bash/kitchensink/a.out",
-    "args": ["-fThreading"],
-    "stopAtEntry": false,
-    "cwd": "/mnt/z/Bash/kitchensink",
-    "environment": [],
-    "externalConsole": true,
-    "windows": {
-        "MIMode": "gdb",
-        "setupCommands": [
-            {
-                "description": "Enable pretty-printing for gdb",
-                "text": "-enable-pretty-printing",
-                "ignoreFailures": true
-            }
-        ]
-    },
-    "pipeTransport": {
-        "pipeCwd": "",
-        "pipeProgram": "c:\\windows\\sysnative\\bash.exe",
-        "pipeArgs": ["-c"],
-        "debuggerPath": "/usr/bin/gdb"
-    },
-    "sourceFileMap": {
-        "/mnt/z": "z:\\"
-    }
-}
-```
-
-### Example `launch.json` for Attaching to an Existing Process
-
-This configuration similar to the launch process above. I have chosen to start the same application above from the Bash command line and now I want to attach to it for debugging. I have changed the `"processID"` to use the remote process picker by specifying the command `"${command:pickRemoteProcess}"` and set up the same `"sourceFileMap"`. When I press <kbd>F5</kbd> to attach, I get a picker drop down showing the running processes within `WSL`. I can scroll or search for the process I want to attach to and start debugging.
-
-```json
-{
-    "name": "C++ Attach",
-    "type": "cppdbg",
-    "request": "attach",
-    "program": "/mnt/z/Bash/kitchensink/a.out",
-    "processId": "${command:pickRemoteProcess}",
-    "windows": {
-        "MIMode": "gdb",
-        "setupCommands": [
-            {
-                "description": "Enable pretty-printing for gdb",
-                "text": "-enable-pretty-printing",
-                "ignoreFailures": true
-            }
-        ]
-    },
-    "pipeTransport": {
-        "pipeCwd": "",
-        "pipeProgram": "c:\\windows\\sysnative\\bash.exe",
-        "pipeArgs": ["-c"],
-        "debuggerPath": "/usr/bin/gdb"
-    },
-    "sourceFileMap": {
-        "/mnt/z": "z:\\"
-    }
-}
-```
+The documentation for GCC on Windows Subsystem for Linux (WSL) has moved to https://code.visualstudio.com/docs/cpp/config-wsl.
diff --git a/Documentation/Debugger/natvis/Natvis.md b/Documentation/Debugger/natvis/Natvis.md
@@ -1,15 +1 @@
-# 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 Visual C++ debugging (`"type": "cppvsdbg"`), the debugger contains the full implementation of the Natvis framework as Visual Studio.
-
-## Documentation
-
-The official documentation can be found [here](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects).
-
-## Schema
-
-The Natvis schema can be found [here](natvis.xsd).
+The documentation for Natvis has moved to https://code.visualstudio.com/docs/cpp/natvis.
diff --git a/Documentation/FAQs.md b/Documentation/FAQs.md
@@ -1,103 +1 @@
-# FAQs
-
-## Table of Contents
-* Setup: [Debugging Setup](#debugging-setup)
-* Setup: [What is the ipch folder?](#What-is-the-ipch-folder)
-* Setup: [How do I disable the IntelliSense cache (ipch)?](#how-do-i-disable-the-intellisense-cache-ipch)
-* Debugger: [Why is debugging not working?](#why-is-debugging-not-working)
-* Build: [How to enable debug symbols](#how-to-enable-debug-symbols)
-* Logging: [How to enable logging](#how-to-enable-logging)
-
-## Debugging Setup
-The debugger needs to be configured to know which executable and debugger to use:
-
-Click menu item: `Debug` -> `Add Configuration...`
-
-The file **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.
-
-## What is the ipch folder?
-
-The language server caches information about included header files to improve the performance of IntelliSense. When you edit C/C++ files in your workspace folder, the language server will store cache files in the `ipch` folder. By default, the `ipch` folder is stored under the user directory. Specifically, it is stored under `%LocalAppData%\vscode-cpptools` on Windows, and for Linux and macOS it is under `~/.vscode-cpptools`. By using the user directory as the default path, it will create one cache location per user for the extension. As the cache size limit is applied to a cache location, having one cache location per user will limit the disk space usage of the cache to that one folder for everyone using the default setting value.
-
-VS Code per-workspace storage folders were not selected for the following reason:
-* The workspace storage location provided by VS Code is somewhat obscure and we had reservations about writing GB's worth of files in this location where users may not see them or know where to find them.
-
-With this in mind we knew that we would not be able to meet the needs of every different development environment, so we provided settings to allow you to customize the way that works best for your situation.
-
-#### `"C_Cpp.intelliSenseCachePath": <string>`
-This setting allows you to set workspace or global overrides for the cache path. For example, if you want to share a single cache location for all workspace folders, open the VS Code settings, and add a "User" setting for "IntelliSense Cache Path".
-
-#### `"C_Cpp.intelliSenseCacheSize": <number>`
-This setting allows you to set a limit on the amount of caching the extension does. This is an approximation, but the extension will make a best effort to keep the cache size as close to the limit you set as possible. If you are sharing the cache location across workspaces as explained above, you can still increase/decrease the limit, but you should make sure that you add a "User" setting for "IntelliSense Cache Size".
-
-## How do I disable the IntelliSense cache (ipch)?
-
-If you do not want to use the IntelliSense caching feature to improve the performance of IntelliSense, you can disable the feature by setting the "IntelliSense Cache Size" setting to 0. (or `"C_Cpp.intelliSenseCacheSize": 0"` in the JSON settings editor)
-
-## 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.
-
-## How to enable logging
-
-Enabling logging will show communication information between VS Code and our extension and between our extension and the debugger.
-
-### Logging for `MI` debuggers
-
-The logging block with its defaults is as follows:
-
-```
-"logging": {
-    "trace": false,
-    "traceResponse": false,
-    "engineLogging": false
-}
-```
-
-#### VS Code and the CppTools extension
-
-The logging here is called `trace` logging and can be enabled by setting `trace` and `traceResponse` to `true` in the logging block inside `launch.json`. This will help diagnose issues related to VS Code's communication to our extension and our responses.
-
-#### CppTools extension and the debugger
-
-The logging between CppTools and the debugger is called `engineLogging`. When using an `MI` debugger such as `gdb` or `lldb`, this will show the request, response and events using the `mi` interpreter. This logging will help us determine whether the debugger is receiving the right commands and generating the correct responses.
-
-### Logging for `Visual C++` debugger
-
-The logging block with its defaults is as follows:
-
-```
-"logging": { 
-    "engineLogging": false
-}
-```
-
-The `Visual C++` debugger logging will show only the communication to and from VS Code as all communication to the debugger is done internally to the process and is not visible through logging.
+The FAQs for the C/C++ extension has moved to https://code.visualstudio.com/docs/cpp/faq-cpp.
diff --git a/Documentation/Getting started with IntelliSense configuration.md b/Documentation/Getting started with IntelliSense configuration.md
@@ -1,56 +1,3 @@
+This file is deprecated.
 
-# 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](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/configure%20includepath.jpg)
-
-## 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 lightbulb menu (see the screenshot below). The quickest way to locate a lightbulb is to scroll to the top of the source file and click on any green squiggle that shows up under a #include statement.
-
-![lightbulb menu "Edit "includePath" setting"](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/Lightbulb.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](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/Include%20errors.png)
-
-## How to specify the include paths?
-
-You can specify the remaining paths using one of the techniques described below.
-
-#### 1. 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 auto-generated 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](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/compile_commands.png)
-
-#### 2. Use the lightbulb suggestions to auto-resolve includePath
-
-The first thing to try is to leverage the lightbulb path suggestions to auto-resolve 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 lightbulb offering suggestions of paths that will allow IntelliSense to resolve the included file.
-
-![lightbulb suggestions](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/lightbulb%20suggestion.png)
-
-If you don't see path suggestions in the lightbulb, 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 lightbulb as the search process goes on.
-
-#### 3. 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](https://github.com/Microsoft/vscode-cpptools/raw/master/Images/c_cpp_properties%20file.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. Note that 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](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/IntelliSense%20engine.md)
-
-[**c_cpp_properties.json** reference guide](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/c_cpp_properties.json.md)
+Please find documentation for the C/C++ extension at https://code.visualstudio.com/docs/languages/cpp.