Merge pull request MicrosoftDocs#2499 from corob-msft/cr-add-bin-compat-restrict

GitHubber17 · web-flow · commit 15846c5f2bb0 · 2019-11-18T19:17:06.000-08:00
Per STL email, add restriction to bin compat doc
diff --git a/docs/porting/binary-compat-2015-2017.md b/docs/porting/binary-compat-2015-2017.md
@@ -1,7 +1,7 @@
 ---
-title: "C++ binary compatibility between Visual Studio 2015, 2017, and 2019"
+title: "C++ binary compatibility 2015-2019"
 description: "Describes how binary compatibility works between compiled C++ files in Visual Studio 2015, 2017, and 2019. One Microsoft Visual C++ Redistributable package works for all three versions."
-ms.date: "11/11/2019"
+ms.date: "11/18/2019"
 helpviewer_keywords: ["binary compatibility, Visual C++"]
 ms.assetid: 591580f6-3181-4bbe-8ac3-f4fbaca949e6
 ---
@@ -11,9 +11,13 @@ The Microsoft C++ (MSVC) compiler toolsets in Visual Studio 2013 and earlier don
 
 We've changed this behavior in Visual Studio 2015, 2017, and 2019. The runtime libraries and apps compiled by any of these versions of the compiler are binary-compatible. It's reflected in the C++ toolset major number, which is 14 for all three versions. (The toolset version is v140 for Visual Studio 2015, v141 for 2017, and v142 for 2019). Say you have third-party libraries built by Visual Studio 2015. You can still use them in an application built by Visual Studio 2017 or 2019. There's no need to recompile with a matching toolset. The latest version of the Microsoft Visual C++ Redistributable package (the Redistributable) works for all of them.
 
-There's an exception to this rule: static libraries or object files compiled using the `/GL` compiler switch *aren't* binary-compatible across versions.
+There are three important restrictions on binary compatibility:
 
-The Redistributable your app uses has an important binary-compatibility restriction. It applies when you mix binaries built with different supported versions of the toolset. The Redistributable version must be at least as new as the latest toolset used by any app component.
+- You can mix binaries built by different versions of the toolset. However, you must use a toolset at least as recent as the most recent binary to link your app. Here's an example: you can link an app compiled using the 2017 toolset to a static library compiled using 2019, if they're linked using the 2019 toolset.
+
+- The Redistributable your app uses has a similar binary-compatibility restriction. When you mix binaries built by different supported versions of the toolset, the Redistributable version must be at least as new as the latest toolset used by any app component.
+
+- Static libraries or object files compiled using the [/GL (Whole program optimization)](../build/reference/gl-whole-program-optimization.md) compiler switch *aren't* binary-compatible across versions. All object files and libraries compiled using `/GL` must use exactly the same toolset for the compile and the final link.
 
 ## Upgrade the Microsoft Visual C++ Redistributable from Visual Studio 2015 or 2017 to Visual Studio 2019
 
diff --git a/docs/porting/visual-cpp-porting-and-upgrading-guide.md b/docs/porting/visual-cpp-porting-and-upgrading-guide.md
@@ -1,35 +1,35 @@
 ---
-title: "Microsoft C++ Porting and Upgrading Guide"
+title: "Microsoft C++ porting and upgrading guide"
 description: "Upgrade Microsoft C++ code to the latest version of Visual Studio."
-ms.date: "11/05/2019"
+ms.date: "11/18/2019"
 ms.assetid: f5fbcc3d-aa72-41a6-ad9a-a706af2166fb
 ms.topic: "overview"
 ---
-# Microsoft C++ Porting and Upgrading Guide
+# Microsoft C++ porting and upgrading guide
 
-This topic provides a guide for upgrading Microsoft C++ code to the latest version of Visual Studio. If you are upgrading from a project created in Visual Studio 2008 or earlier, you must first use Visual Studio 2010 to convert the project to MSBuild format, then open the project in Visual Studio 2019. For projects created in Visual Studio 2010 through 2015, just open the project in Visual Studio 2019. For complete instructions, see [Upgrading C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md).
+This article provides a guide for upgrading Microsoft C++ code to the latest version of Visual Studio. For projects created in Visual Studio 2010 through 2015, just open the project in Visual Studio 2019. You can upgrade a Visual Studio 2008 or earlier project in two steps. Use Visual Studio 2010 to convert the project to MSBuild format first. Then open the project in Visual Studio 2019. For complete instructions, see [Upgrading C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md).
 
-The toolsets in Visual Studio 2015, Visual Studio 2017 and Visual Studio 2019 are binary-compatible, which enables you to upgrade to a more recent version of the compiler without having to upgrade library dependencies. For more information, see [C++ Binary Compatibility between 2015 and 2019](binary-compat-2015-2017.md).
+The toolsets in Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. Now you can upgrade to a more recent version of the compiler without having to upgrade your library dependencies. For more information, see [C++ binary compatibility 2015-2019](binary-compat-2015-2017.md).
 
 When upgrading projects that use open-source libraries or are meant to run on multiple platforms, we recommended migrating to a CMake-based project. For more information, see [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md)
 
 ## Reasons to upgrade C++ code
 
-If a legacy application is running satisfactorily, in a secure environment, and is not under active development, then there might not be much incentive to upgrade it. However, if an application requires ongoing maintenance, or new feature development including performance or security improvements, then you might consider upgrading the code for any of the following reasons:
+If a legacy application is running satisfactorily, in a secure environment, and isn't under active development, there might not be much incentive to upgrade it. However, consider an upgrade in these cases: Your application requires ongoing maintenance. Or, you're doing new feature development, or making performance or security improvements. An upgrade brings these benefits:
 
-- The same code can run faster due to improved compiler optimizations.
+- The same code can run faster, because we've improved compiler optimizations.
 
-- Modern C++ features and programming practices eliminate many common causes of bugs and produce code that is far easier to maintain than older C-style idioms.
+- Modern C++ features and programming practices eliminate many common causes of bugs, and produce code that's far easier to maintain than older C-style idioms.
 
-- Build times are significantly faster, due to performance improvements in the compiler and linker.
+- Build times are faster, because of performance improvements in the compiler and linker.
 
-- Better standards conformance. The [/permissive-](../build/reference/permissive-standards-conformance.md) compiler option enables you to identify code that was formerly allowed by the Microsoft C++ compiler but does not conform to the current C++ standard.
+- Better standards conformance. The [/permissive-](../build/reference/permissive-standards-conformance.md) compiler option helps you identify code that doesn't conform to the current C++ standard.
 
-- Better run-time security, including more secure [C Runtime library]() features and compiler features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (Visual Studio 2019 version 16.4).
+- Better run-time security, including more secure [C Runtime library]() features. And, compiler features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (new in Visual Studio 2019 version 16.4).
 
 ## Multitargeting vs. upgrading
 
-If upgrading your code base to a new toolset is not an option, you can still use a recent version of Visual Studio to build and edit projects that compile with older toolsets and libraries. In Visual Studio 2019 you can take advantage of features such as:
+Perhaps upgrading your code base to a new toolset isn't an option for you. You can still use the latest Visual Studio to build and edit projects that use older toolsets and libraries. In Visual Studio 2019, you can take advantage of features such as:
 
 - modern static analysis tools, including the C++ Core Guidelines checkers and Clang-Tidy, to help identify potential problems in your source code.
 
@@ -43,11 +43,11 @@ For more information, see [Use native multi-targeting in Visual Studio to build
 |-----------|-----------------|
 |[Upgrading C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md)|How to upgrade your code base to Visual Studio 2019 and v142 of the compiler.|
 |[IDE tools for upgrading C++ code](ide-tools-for-upgrading-code.md)|Useful IDE features that help in the upgrade process.|
-|[C++ Binary Compatibility between 2015 and 2019](binary-compat-2015-2017.md)|Consume v140 libraries as-is from v142 projects.|
+|[C++ binary compatibility 2015-2019](binary-compat-2015-2017.md)|Consume v140 and v141 libraries as-is from v142 projects.|
 |[Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md)|Use Visual Studio 2019 with older compilers and libraries.|
 |[Visual C++ change history 2003 - 2015](visual-cpp-change-history-2003-2015.md)|A list of all the changes in the Microsoft C++ libraries and build tools from Visual Studio 2003 through 2015 that might require changes in your code.|
 |[Visual C++ What's New 2003 through 2015](visual-cpp-what-s-new-2003-through-2015.md)|All the "what's new" information for Microsoft C++ from Visual Studio 2003 through Visual Studio 2015.|
-|[Porting and Upgrading: Examples and Case Studies](porting-and-upgrading-examples-and-case-studies.md)|For this section, we ported and upgrades several samples and applications and discussed the experiences and results. You might find that reading these gives you a sense of what is involved in the porting and upgrading process. Throughout the process, we discuss tips and tricks for upgrading and show how specific errors were fixed.|
+|[Porting and Upgrading: Examples and Case Studies](porting-and-upgrading-examples-and-case-studies.md)|For this section, we ported and upgrades several samples and applications and discussed the experiences and results. These articles give you a sense of what's involved in the porting and upgrading process. Throughout the process, we discuss tips and tricks for upgrading and show how specific errors were fixed.|
 |[Porting to the Universal Windows Platform](porting-to-the-universal-windows-platform-cpp.md)|Contains information about porting code to Windows 10|
 |[Introduction to Visual C++ for UNIX Users](introduction-to-visual-cpp-for-unix-users.md)|Provides information for UNIX users who are new to Visual C++ and want to become productive with it.|
 |[Running Linux programs on Windows](porting-from-unix-to-win32.md)|Discusses options for migrating UNIX applications to Windows.|
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -2854,7 +2854,7 @@
       href: porting/visual-cpp-change-history-2003-2015.md
     - name: Visual C++ What's New 2003 through 2015
       href: porting/visual-cpp-what-s-new-2003-through-2015.md
-    - name: C++ Binary Compatibility between 2015 and 2019
+    - name: C++ binary compatibility 2015-2019
       href: porting/binary-compat-2015-2017.md
     - name: "Port and upgrade: examples and case studies"
       items: 
