Merge pull request #1810 from corob-msft/cr-cl-options

rjagiewich · web-flow · commit a55324b2981c · 2019-03-08T16:49:10.000-06:00
Update /Zm recommendation per issue 821
diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md
@@ -111,9 +111,9 @@ This article contains a categorical list of compiler options. For an alphabetica
 |[/vms](vmm-vms-vmv-general-purpose-representation.md)|Declares single inheritance.|
 |[/vmv](vmm-vms-vmv-general-purpose-representation.md)|Declares virtual inheritance.|
 |[/Z7](z7-zi-zi-debug-information-format.md)|Generates C 7.0-compatible debugging information.|
-|[/Za](za-ze-disable-language-extensions.md)|Disables language extensions.|
+|[/Za](za-ze-disable-language-extensions.md)|Disables C89 language extensions.|
 |[/Zc](zc-conformance.md)|Specifies standard behavior under [/Ze](za-ze-disable-language-extensions.md).|
-|[/Ze](za-ze-disable-language-extensions.md)|Deprecated. Enables language extensions.|
+|[/Ze](za-ze-disable-language-extensions.md)|Deprecated. Enables C89 language extensions.|
 |[/Zf](zf.md)|Improves PDB generation time in parallel builds.|
 |[/ZI](z7-zi-zi-debug-information-format.md)|Includes debug information in a program database compatible with Edit and Continue. (x86 only)|
 |[/Zi](z7-zi-zi-debug-information-format.md)|Generates complete debugging information.|
diff --git a/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md b/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md
@@ -1,6 +1,6 @@
 ---
 title: "/Zm (Specify Precompiled Header Memory Allocation Limit)"
-ms.date: "11/04/2016"
+ms.date: "03/08/2019"
 f1_keywords: ["/zm"]
 helpviewer_keywords: ["PCH files, memory allocation limit", "Zm compiler option [C++]", "/Zm compiler option [C++]", "precompiled header files, memory allocation limit", "Specify Precompiled Header Memory Allocation Limit compiler option", "cl.exe compiler, memory allocation limit", ".pch files, memory allocation limit", "memory allocation, Memory Allocation Limit compiler option", "-Zm compiler option [C++]"]
 ms.assetid: 94c77d5e-6672-46a7-92e0-3f69e277727d
@@ -24,9 +24,11 @@ The *factor* argument is a percentage of the default size of a compiler-defined
 
 ## Remarks
 
-In earlier versions of Visual C++, the compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and requires a fixed-size buffer only to construct precompiled headers. Consequently, the **/Zm** compiler option is rarely necessary.
+In versions before Visual Studio 2015, the C++ compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and allows the precompiled header to comprise multiple address ranges. Consequently, the **/Zm** compiler option is rarely necessary.
 
-If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **/Zm** compiler option, you might have reserved too much memory. Consider removing the **/Zm** option. If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *factor* argument to use when you recompile by using the **/Zm** compiler option.
+If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **/Zm** compiler option, you might have reserved too much memory. Consider removing the **/Zm** option.
+
+If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *factor* argument to use when you recompile by using the **/Zm** compiler option. This message is only significant when a precompiled header uses `#pragma hdrstop`. In other cases, it is a spurious error caused by Windows virtual memory pressure issues, and the recommendation to use the **/Zm** option should be ignored. Instead, consider reducing the number of parallel processes when using the **/maxcpucount** option to MSBUILD.EXE in conjunction with the **/MP** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/).
 
 The following table shows how the *factor* argument affects the memory allocation limit if you assume the size of the default precompiled header buffer is 75 MB.
 
@@ -40,15 +42,15 @@ The following table shows how the *factor* argument affects the memory allocatio
 
 ## Other Ways to Set the Memory Allocation Limit
 
-#### To set the /Zm compiler option in the Visual Studio development environment
+### To set the /Zm compiler option in the Visual Studio development environment
 
 1. Open the project's **Property Pages** dialog box. For details, see [Working with Project Properties](../../ide/working-with-project-properties.md).
 
-1. In the navigation pane, select **Configuration Properties**, **C/C++**, **Command Line**.
+1. In the navigation pane, select **Configuration Properties** > **C/C++** > **Command Line**.
 
 1. Enter the **/Zm** compiler option in the **Additional Options** box.
 
-#### To set the /Zm compiler option programmatically
+### To set the /Zm compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
 
diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1076.md b/docs/error-messages/compiler-errors-1/fatal-error-c1076.md
@@ -1,19 +1,21 @@
 ---
 title: "Fatal Error C1076"
-ms.date: "11/04/2016"
+ms.date: "03/08/2019"
 f1_keywords: ["C1076"]
 helpviewer_keywords: ["C1076"]
 ms.assetid: 84ac1180-3e8a-48e8-9f77-7f18a778b964
 ---
 # Fatal Error C1076
 
-compiler limit : internal heap limit reached; use /Zm to specify a higher limit
+> compiler limit : internal heap limit reached; use /Zm to specify a higher limit
 
-This error can be caused by too many symbols, or too many template instantiations.
+This error can be caused by too many symbols, or too many template instantiations. Starting in Visual Studio 2015, this message may result from Windows virtual memory pressure caused by too many parallel build processes. In this case, the recommendation to use the **/Zm** option should be ignored unless you are using a `#pragma hdrstop` directive.
 
 To resolve this error:
 
-1. Use the [/Zm](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md) option to set the compiler memory limit to the value specified in the [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) error message. For more information that includes how to set this value in Visual Studio, see the Remarks section in [/Zm (Specify Precompiled Header Memory Allocation Limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md).
+1. If your precompiled header uses a `#pragma hdrstop` directive, use the [/Zm](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md) option to set the compiler memory limit to the value specified in the [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) error message. For more information that includes how to set this value in Visual Studio, see the Remarks section in [/Zm (Specify Precompiled Header Memory Allocation Limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md).
+
+1. Consider reducing the number of parallel processes specified by using the **/maxcpucount** option to MSBUILD.EXE in conjunction with the **/MP** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/).
 
 1. If you are using the 32-bit hosted compilers on a 64-bit operating system, use the 64-bit hosted compilers instead. For more information, see [How to: Enable a 64-Bit Visual C++ Toolset on the Command Line](../../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md).
 
@@ -23,10 +25,4 @@ To resolve this error:
 
 1. Eliminate unused declarations.
 
-1. Split large functions into smaller functions.
-
-1. Split large classes into smaller classes.
-
-1. Split the current file into smaller files.
-
 If C1076 occurs immediately after the build starts, the value specified for **/Zm** is probably too high for your program. Reduce the **/Zm** value.
diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3859.md b/docs/error-messages/compiler-errors-2/compiler-error-c3859.md
@@ -1,12 +1,14 @@
 ---
 title: "Compiler Error C3859"
-ms.date: "11/04/2016"
+ms.date: "03/08/2019"
 f1_keywords: ["C3859"]
 helpviewer_keywords: ["C3859"]
 ms.assetid: 40e93b25-4393-4467-90de-035434a665c7
 ---
 # Compiler Error C3859
 
-virtual memory range for PCH exceeded; please recompile with a command line option of '-Zmvalue' or greater
+> virtual memory range for PCH exceeded; please recompile with a command line option of '-Zm*value*' or greater
 
-Your precompiled header is too small for the amount of data the compiler is trying to put in it. Use the **/Zm** compiler flag to specify a larger value for the precompiled header file. For more information, see [/Zm (Specify Precompiled Header Memory Allocation Limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md).
+The virtual memory allocated for your precompiled header is too small for the amount of data the compiler is trying to put in it. Starting in Visual Studio 2015, the **/Zm** recommendation is only significant when using the `#pragma hdrstop` directive. In other cases, it's a spurious error that indicates Windows virtual memory pressure issues.
+
+If your precompiled header uses a `#pragma hdrstop` directive, use the **/Zm** compiler flag to specify a larger value for the precompiled header file. Otherwise, consider reducing the number of parallel compilation processes in your build. For more information, see [/Zm (Specify Precompiled Header Memory Allocation Limit)](../../build/reference/zm-specify-precompiled-header-memory-allocation-limit.md).
