Merge pull request #3646 from MicrosoftDocs/master

7/5/2021 AM Publish

Author: Taojunshen

docs/build/reference/external-external-headers-diagnostics.md

@@ -1,19 +1,19 @@
 ---
 title: "/external (External headers diagnostics)"
 description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage."
-ms.date: 06/07/2021
+ms.date: 07/02/2021
 f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external"]
 helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"]
 ---
 # `/external` (External headers diagnostics)
 
-The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The `/external` compiler options give you control over these warnings.
+The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The **`/external`** compiler options give you control over these warnings.
 
 The **`/external`** compiler options are available starting in Visual Studio 2017 version 15.6. In versions of Visual Studio before Visual Studio 2019 version 16.10, the **`/external`** options require you also set the **`/experimental:external`** compiler option.
 
 ## Syntax
 
-Use external header options:
+Use external header options (Not required in 16.10 and later):
 > **`/experimental:external`**
 
 Specify external headers:
@@ -22,7 +22,11 @@ Specify external headers:
 > **`/external:I`** *`path`*
 
 Specify diagnostics behavior:
-> **`/external:W`**_`n`_\
+> **`/external:W0`**\
+> **`/external:W1`**\
+> **`/external:W2`**\
+> **`/external:W3`**\
+> **`/external:W4`**\
 > **`/external:templates-`**
 
 ### Arguments
@@ -40,7 +44,9 @@ Defines a root directory that contains external headers. All recursive subdirect
 Specifies the name of an environment variable *`var`* that holds a semicolon-separated list of external header directories. It's useful for build systems that rely on environment variables such as `INCLUDE`, which you use to specify the list of external include files. Or, `CAExcludePath`, for files that shouldn't be analyzed by `/analyze`. For example, you can specify `/external:env:INCLUDE` to make every directory in `INCLUDE` an external header directory at once. It's the same as using **`/external:I`** to specify the individual directories, but much less verbose. There should be no space between *`var`* and **`/external:env:`**.
 
 **`/external:Wn`**\
-This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive:
+This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. If this option isn't specified, the compiler issues command line warning D9007 for other **`/external`** options. Those options are ignored, because they would have no effect.
+
+The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive:
 
 ```cpp
 #pragma warning (push, 0)
@@ -151,7 +157,9 @@ struct sample_struct
 
 With this change to the library header, the author of the library ensures that the global warning level in this header is 4, no matter what gets specified in **`/external:Wn`**. Now all level 4 and above warnings are reported. The library author can also force certain warnings to be errors, disabled, suppressed, or emitted only once in the header. The **`/external`** options don't override that deliberate choice.
 
-`#pragma system_header` is an intrusive header marker that allows library writers to mark certain headers as external. These headers have the warning level specified by **`/external:Wn`**, if any.
+### `system_header` pragma
+
+`#pragma system_header` is an intrusive marker that allows library writers to mark certain headers as external. A file containing `#pragma system_header` is considered external from the point of the pragma to the end of the file, as if it were specified as external on the command line. The compiler emits any diagnostics after the pragma at the warning level specified by **`/external:Wn`**. For more information, see [`system_header` pragma](../../preprocessor/system-header-pragma.md).
 
 ### Limitations
 

docs/build/reference/qspectre.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: /Qspectre"
 title: "/Qspectre"
-ms.date: 06/22/2021
+ms.date: 07/02/2021
 f1_keywords: ["VC.Project.VCCLCompilerTool.SpectreMitigation"]
 helpviewer_keywords: ["/Qspectre"]
 ---
@@ -52,21 +52,45 @@ The effect of **`/Qspectre`** on performance appeared to be negligible in severa
 
 ### Required libraries
 
-The **`/Qspectre`** compiler option generates code that implicitly links versions of the runtime libraries built to provide Spectre mitigations. These libraries are optional components that must be installed by using the Visual Studio Installer:
+The **`/Qspectre`** compiler option mitigates issues in your own code. For greater protection, we strongly recommend you also use libraries built to provide Spectre mitigations. Several of the Microsoft runtime libraries are available with Spectre mitigations.
+
+::: moniker range=">=msvc-150"
+
+These libraries are optional components that must be installed by using the Visual Studio Installer:
 
 - MSVC version *version_numbers* Libs for Spectre \[(x86 and x64) | (ARM) | (ARM64)]
 - Visual C++ ATL for \[(x86/x64) | ARM | ARM64] with Spectre Mitigations
 - Visual C++ MFC for \[x86/x64 | ARM | ARM64] with Spectre Mitigations
 
+::: moniker-end
+
 ::: moniker range=">=msvc-160"
 
-If you build your code by using **`/Qspectre`** and these libraries aren't installed, the build system reports warning [MSB8040](/visualstudio/msbuild/errors/msb8040). If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
+The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning [MSB8040](/visualstudio/msbuild/errors/msb8040). If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
 
 ::: moniker-end
 
-::: moniker range="<=msvc-150"
+::: moniker range="msvc-150"
+
+The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found". If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
+
+::: moniker-end
+
+::: moniker range=">=msvc-150"
 
-If you build your code by using **`/Qspectre`** and these libraries aren't installed, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found". If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
+There are several ways to specify the Spectre-mitigated libraries to the build command line. You can specify the path to the Spectre-mitigated libraries by using the [`/LIBPATH`](./libpath-additional-libpath.md) linker option to make them the default libraries. You can use the [`/NODEFAULTLIB`](./nodefaultlib-ignore-libraries.md) linker option and explicitly link the Spectre-mitigated libraries. Or, you can set the `LIBPATH` environment variable to include the path to the Spectre-mitigated libraries for your target platform. One way to set this path in the environment is to use a developer command prompt set up by using the `spectre_mode` option. For more information, see [Use the developer tools in an existing command window](../building-on-the-command-line.md#use-the-developer-tools-in-an-existing-command-window).
+
+::: moniker-end
+
+::: moniker range="msvc-140"
+
+Spectre-mitigated runtime libraries for x86, x64 and ARM platforms are available as part of the patch available through [KB 4338871](https://support.microsoft.com/help/4338871). By default, these libraries are installed in the following directories:
+
+- x86: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre`*
+- x64: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre\amd64`*
+- ARM: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre\arm`*
+
+There are several ways to specify the Spectre-mitigated libraries to the build command line. You can specify the path to the Spectre-mitigated libraries by using the [`/LIBPATH`](./libpath-additional-libpath.md) linker option to make them the default libraries. You can use the [`/NODEFAULTLIB`](./nodefaultlib-ignore-libraries.md) linker option and explicitly link the Spectre-mitigated libraries. Or, you can set the `LIBPATH` environment variable to include the path to the Spectre-mitigated libraries for your target architecture. For more information, see [Use the Microsoft C++ toolset from the command line](../building-on-the-command-line.md).
 
 ::: moniker-end
 
@@ -96,7 +120,11 @@ For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, se
 
 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
 
-1. Enter the *`/Qspectre`* compiler option in the **Additional Options** box. Choose **OK** to apply the change.
+1. Enter the *`/Qspectre`* compiler option in the **Additional Options** box. Choose **Apply** to apply the change.
+
+1. Select the **Configuration Properties** > **Linker** > **General** property page.
+
+1. For each Platform in your project properties, edit the **Additional Library Directories** property. Set the path to the Spectre-mitigated runtime library directory for the target platform, and then choose **Apply** to apply the change. When done, choose **OK**.
 
 ::: moniker-end
 

docs/c-language/c-pragmas.md

@@ -21,38 +21,39 @@ A *pragma* instructs the compiler to perform a particular action at compile time
         [`comment`](../preprocessor/comment-c-cpp.md)\
         [`component`](../preprocessor/component.md)\
         [`const_seg`](../preprocessor/const-seg.md)\
-        [`data_seg`](../preprocessor/data-seg.md)
+        [`data_seg`](../preprocessor/data-seg.md)\
+        [`deprecated`](../preprocessor/deprecated-c-cpp.md)
     :::column-end:::
     :::column:::
-        [`deprecated`](../preprocessor/deprecated-c-cpp.md)\
         [`detect_mismatch`](../preprocessor/detect-mismatch.md)\
         [`fenv_access`](../preprocessor/fenv-access.md)\
         [`float_control`](../preprocessor/float-control.md)\
         [`fp_contract`](../preprocessor/fp-contract.md)\
         [`function`](../preprocessor/function-c-cpp.md)\
         [`hdrstop`](../preprocessor/hdrstop.md)\
         [`include_alias`](../preprocessor/include-alias.md)\
-        [`inline_depth`](../preprocessor/inline-depth.md)
+        [`inline_depth`](../preprocessor/inline-depth.md)\
+        [`inline_recursion`](../preprocessor/inline-recursion.md)
     :::column-end:::
     :::column:::
-        [`inline_recursion`](../preprocessor/inline-recursion.md)\
         [`intrinsic`](../preprocessor/intrinsic.md)\
         [`make_public`](../preprocessor/make-public.md)\
         [`managed`](../preprocessor/managed-unmanaged.md)\
         [`message`](../preprocessor/message.md)\
         [`omp`](../preprocessor/omp.md)\
         [`once`](../preprocessor/once.md)\
         [`optimize`](../preprocessor/optimize.md)\
-        [`pack`](../preprocessor/pack.md)
+        [`pack`](../preprocessor/pack.md)\
+        [`pop_macro`](../preprocessor/pop-macro.md)
     :::column-end:::
     :::column:::
-        [`pop_macro`](../preprocessor/pop-macro.md)\
         [`push_macro`](../preprocessor/push-macro.md)\
         [`region`, `endregion`](../preprocessor/region-endregion.md)\
         [`runtime_checks`](../preprocessor/runtime-checks.md)\
         [`section`](../preprocessor/section.md)\
         [`setlocale`](../preprocessor/setlocale.md)\
         [`strict_gs_check`](../preprocessor/strict-gs-check.md)\
+        [`system_header`](../preprocessor/system-header-pragma.md)\
         [`unmanaged`](../preprocessor/managed-unmanaged.md)\
         [`warning`](../preprocessor/warning.md)
     :::column-end:::

docs/cppcx/collections-c-cx.md

@@ -54,7 +54,7 @@ Any element to be stored in a [Platform::Collections::Vector](../cppcx/platform-
 
 [Platform::Collections::VectorIterator](../cppcx/platform-collections-vectoriterator-class.md) and [Platform::Collections::VectorViewIterator](../cppcx/platform-collections-vectorviewiterator-class.md) enable the use of `range for` loops and algorithms like [std::sort](../standard-library/algorithm-functions.md#sort) with an [IVector\<T>](/uwp/api/windows.foundation.collections.ivector-1) container. But `IVector` elements cannot be accessed through C++ pointer dereference; they can be accessed only through [GetAt](/uwp/api/windows.foundation.collections.ivector-1.getat) and [SetAt](/uwp/api/windows.foundation.collections.ivector-1.setat) methods. Therefore, these iterators use the proxy classes `Platform::Details::VectorProxy<T>` and `Platform::Details::ArrowProxy<T>` to provide access to the individual elements through __\*__, __->__, and __\[]__ operators, as required by the Standard Library. Strictly speaking, given an `IVector<Person^> vec`, the type of `*begin(vec)` is `VectorProxy<Person^>`. However, the proxy object is almost always transparent to your code. These proxy objects are not documented because they are only for internal use by the iterators, but it is useful to know how the mechanism works.
 
-When you use a `range for` loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use **`auto`** or `auto&`, compiler warning C4239 is raised and `VectoryProxy` is mentioned in the warning text.
+When you use a range-based **`for`** loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use `auto&`, compiler warning [C4239](../error-messages/compiler-warnings/compiler-warning-level-4-c4239.md) is raised and `VectoryProxy` is mentioned in the warning text.
 
 The following illustration shows a `range for` loop over an `IVector<Person^>`. Notice that execution is stopped on the breakpoint on line 64. The **QuickWatch** window shows that the iterator variable `p` is in fact a `VectorProxy<Person^>` that has `m_v` and `m_i` member variables. However, when you call `GetType` on this variable, it returns the identical type to the `Person` instance `p2`. The takeaway is that although `VectorProxy` and `ArrowProxy` might appear in **QuickWatch**, the debugger certain compiler errors, or other places, you typically don't have to explicitly code for them.
 

docs/preprocessor/pragma-directives-and-the-pragma-keyword.md

@@ -67,16 +67,17 @@ The Microsoft C and C++ compilers recognize the following pragma directives:
       [`once`](../preprocessor/once.md)\
       [`optimize`](../preprocessor/optimize.md)\
       [`pack`](../preprocessor/pack.md)\
-      [`pointers_to_members`](../preprocessor/pointers-to-members.md) <sup>1</sup>
+      [`pointers_to_members`](../preprocessor/pointers-to-members.md) <sup>1</sup>\
+      [`pop_macro`](../preprocessor/pop-macro.md)
    :::column-end:::
    :::column span="":::
-      [`pop_macro`](../preprocessor/pop-macro.md)\
       [`push_macro`](../preprocessor/push-macro.md)\
       [`region`](../preprocessor/region-endregion.md)\
       [`runtime_checks`](../preprocessor/runtime-checks.md)\
       [`section`](../preprocessor/section.md)\
       [`setlocale`](../preprocessor/setlocale.md)\
       [`strict_gs_check`](../preprocessor/strict-gs-check.md)\
+      [`system_header`](../preprocessor/system-header-pragma.md)\
       [`unmanaged`](../preprocessor/managed-unmanaged.md)\
       [`vtordisp`](../preprocessor/vtordisp.md) <sup>1</sup>\
       [`warning`](../preprocessor/warning.md)

docs/preprocessor/system-header-pragma.md

@@ -0,0 +1,30 @@
+---
+description: "Learn more about the system_header pragma."
+title: "system_header pragma"
+ms.date: 07/02/2021
+f1_keywords: ["vc-pragma.system_header", "system_header_CPP", "system_header"]
+helpviewer_keywords: ["pragma, system_header", "system_header pragma"]
+no-loc: ["pragma"]
+---
+# `system_header` pragma
+
+Treat the rest of the file as external for diagnostics reports.
+
+## Syntax
+
+> **`#pragma system_header`**
+
+## Remarks
+
+Starting in Visual Studio 2017 version 15.6, the compiler lets you set two different default diagnostic warning levels on the command line. Normally, you use a [`/W0`, `/W1`, `/W2`, `/W3`, or `/W4`](../build/reference/compiler-option-warning-level.md) compiler option to specify a single diagnostic level for all code in a project. However, your project might include system header files or files from external libraries that generate warnings at the specified level. When you can't or don't want to edit these files, you can specify them as *external*. Files specified as external can have a separate compiler diagnostic level applied to them as a group. For more information on how to specify external files and the external warning level to the compiler, see [`/external`](../build/reference/external-external-headers-diagnostics.md).
+
+For example, a common scenario uses the **`/external:W1`** option to apply a **`/W1`** warning level to external library header files, while you use **`/W4 /WX`** on your own code. Then you don't see minor diagnostics for the code that isn't yours.
+
+The **`system_header`** pragma tells the compiler to show diagnostics at the **`/external:Wn`** level for the rest of the source file. The **`system_header`** pragma applies even if no other files are specified as external to the compiler. However, if no **`/external:Wn`** option level is specified, the compiler issues a diagnostic and uses the same warning level it applies to non-external files. Other pragma directives that affect warning behavior still apply after a **`system_header`** pragma.
+
+The **`system_header`** pragma is available starting in Visual Studio 2019 version 16.10.
+
+## See also
+
+[`/external`](../build/reference/external-external-headers-diagnostics.md)
+[Pragma directives and the `__pragma` and `_Pragma` keywords](./pragma-directives-and-the-pragma-keyword.md)

docs/preprocessor/toc.yml

@@ -198,6 +198,8 @@
       href: ../preprocessor/setlocale.md
     - name: strict_gs_check pragma
       href: ../preprocessor/strict-gs-check.md
+    - name: system_header pragma
+      href: ../preprocessor/system-header-pragma.md
     - name: vtordisp pragma
       href: ../preprocessor/vtordisp.md
     - name: warning pragma