8/3/2021 AM Publish (#3690)

* fix code sample (#3676)

* fix code sample

* acrolinx

Co-authored-by: TylerMSFT <[email protected]>

* Address 3269 typo in warning number (#3680)

* Fixed typo: evalution --> evaluation

* Bulk Fix - Sentence form for all alt text (#3683)

* Updated C/C++ workload name

The workload for C/C++ development in VS Build Tools 2019 installer is called 'Desktop development with C++'.

* Split out docs by version

Add VS2017-specific instructions.

* Add 16.11 Compiler Warnings C5247 and C5248 (MicrosoftDocs#3689)

* Add C5247 and C5248

* Fix link typos

* Updates per Xiang Fan review

* More wordsmithage

* More fix per X.F.

Co-authored-by: Tyler Whitney <[email protected]>
Co-authored-by: TylerMSFT <[email protected]>
Co-authored-by: Colin Robertson <[email protected]>
Co-authored-by: ystamant <[email protected]>
Co-authored-by: Andrew Shymanel <[email protected]>

Author: 6 people

docs/build/building-on-the-command-line.md

@@ -2,7 +2,7 @@
 title: "Use the Microsoft C++ toolset from the command line"
 description: "Use the Microsoft C++ (MSVC) compiler toolset from the command line outside of the Visual Studio IDE."
 ms.custom: "conceptual"
-ms.date: "04/21/2020"
+ms.date: 08/02/2021
 helpviewer_keywords: ["command-line builds [C++]", "compiling source code [C++], command line", "builds [C++], command-line", "command line [C++], building from", "command line [C++], compilers"]
 ms.assetid: 7ca9daed-a003-4162-842d-908f79058365
 ---
@@ -15,7 +15,16 @@ You can build C and C++ applications on the command line by using tools that are
 
 ## Download and install the tools
 
-If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **C++ build tools** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 or 2017 toolsets, select the optional MSVC v140 or MSVC v141 build tools. When you're satisfied with your selections, choose **Install**.
+::: moniker range=">=msvc-160"
+
+If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 or 2017 toolsets, select the optional MSVC v140 or MSVC v141 build tools. When you're satisfied with your selections, choose **Install**.
+
+::: moniker-end
+::: moniker range="<=msvc-150"
+
+If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio 2017](https://my.visualstudio.com/Downloads?q=2017). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Visual C++ build tools** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 toolset, select the optional MSVC v140 build tools. When you're satisfied with your selections, choose **Install**.
+
+::: moniker-end
 
 ## How to use the command-line tools
 

docs/c-runtime-library/crt-initialization.md

@@ -2,16 +2,18 @@
 title: "CRT Initialization"
 description: "Describes how the CRT initializes global state in native code."
 ms.topic: "conceptual"
-ms.date: "11/04/2016"
+ms.date: 08/02/2021
 helpviewer_keywords: ["CRT initialization [C++]"]
 ms.assetid: e7979813-1856-4848-9639-f29c86b74ad7
 ---
 # CRT Initialization
 
-This topic describes how the CRT initializes global state in native code.
+This article describes how the CRT initializes global state in native code.
 
 By default, the linker includes the CRT library, which provides its own startup code. This startup code initializes the CRT library, calls global initializers, and then calls the user-provided `main` function for console applications.
 
+It's possible, though not recommended, to take advantage of Microsoft-specific linker behavior to insert your own global initializers in a specific order. This code isn't portable, and comes with some important caveats.
+
 ## Initializing a Global Object
 
 Consider the following code:
@@ -32,13 +34,13 @@ int main()
 
 According to the C/C++ standard, `func()` must be called before `main()` is executed. But who calls it?
 
-One way to determine the caller is to set a breakpoint in `func()`, debug the application, and examine the stack. This is possible because the CRT source code is included with Visual Studio.
+One way to determine the caller is to set a breakpoint in `func()`, debug the application, and examine the stack. It's possible because the CRT source code is included with Visual Studio.
 
 When you browse the functions on the stack, you'll see that the CRT is calling a list of function pointers. These functions are similar to `func()`, or constructors for class instances.
 
-The CRT gets the list of function pointers from the Microsoft C++ compiler. When the compiler sees a global initializer, it generates a dynamic initializer in the `.CRT$XCU` section where `CRT` is the section name and `XCU` is the group name. To get a list of dynamic initializers, run the command **dumpbin /all main.obj**, and then search the `.CRT$XCU` section. This applies when main.cpp is compiled as a C++ file, not a C file. It will be similar to the following example:
+The CRT gets the list of function pointers from the Microsoft C++ compiler. When the compiler sees a global initializer, it generates a dynamic initializer in the `.CRT$XCU` section where `CRT` is the section name and `XCU` is the group name. To get a list of dynamic initializers, run the command **`dumpbin /all main.obj`**, and then search the `.CRT$XCU` section. The command only applies when *`main.cpp`* is compiled as a C++ file, not a C file. It should be similar to this example:
 
-```
+```cmd
 SECTION HEADER #6
 .CRT$XCU name
        0 physical address
@@ -72,11 +74,11 @@ The CRT defines two pointers:
 
 Neither group has any other symbols defined except `__xc_a` and `__xc_z`.
 
-Now, when the linker reads various `.CRT` groups, it combines them in one section and orders them alphabetically. This means that the user-defined global initializers (which the Microsoft C++ compiler puts in `.CRT$XCU`) will always come after `.CRT$XCA` and before `.CRT$XCZ`.
+Now, when the linker reads various `.CRT` subsections (the part after the `$`), it combines them in one section and orders them alphabetically. It means that the user-defined global initializers (which the Microsoft C++ compiler puts in `.CRT$XCU`) always come after `.CRT$XCA` and before `.CRT$XCZ`.
 
-The section will resemble the following example:
+The section should resemble this example:
 
-```
+```asm
 .CRT$XCA
             __xc_a
 .CRT$XCU
@@ -88,6 +90,26 @@ The section will resemble the following example:
 
 So, the CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded.
 
+## Linker features for initialization
+
+The C++ Standard doesn't provide a conforming way to specify relative order across translation units for a user-supplied global initializer. However, since the Microsoft linker orders the `.CRT` subsections alphabetically, it's possible to take advantage of this ordering to specify initialization order. We don't recommend this Microsoft-specific technique, and it may break in a future release. We've documented it only to keep you from creating code that's broken in hard-to-diagnose ways.
+
+To help prevent issues in your code, starting in Visual Studio 2019 version 16.11, we've added two new off by default warnings: [C5247](../error-messages/compiler-warnings/c5247.md) and [C5248](../error-messages/compiler-warnings/c5248.md). Enable these warnings to detect problems when creating your own initializers.
+
+You can add initializers to unused reserved section names to create them in a specific relative order to the compiler generated dynamic initializers:
+
+```cpp
+#pragma section(".CRT$XCT", read)
+// 'i1' is guaranteed to be called before any compiler generated C++ dynamic initializer
+__declspec(allocate(".CRT$XCT")) type i1 = f;
+
+#pragma section(".CRT$XCV", read)
+// 'i2' is guaranteed to be called after any compiler generated C++ dynamic initializer
+__declspec(allocate(".CRT$XCV")) type i2 = f;
+```
+
+The names `.CRT$XCT` and `.CRT$XCV` aren't used by either the compiler or the CRT library right now, but there's no guarantee that they'll remain unused in the future. And, your variables could still be optimized away by the compiler. Consider the potential engineering, maintenance, and portability issues before adopting this technique.
+
 ## See also
 
 [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md)

docs/error-messages/compiler-warnings/c5247.md

@@ -0,0 +1,50 @@
+---
+title: "Compiler Warning C5247"
+description: Compiler warning C5247 description and solution.
+ms.date: 08/02/2021
+f1_keywords: ["C5247"]
+helpviewer_keywords: ["C5247"]
+---
+# Compiler Warning C5247
+
+> section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior
+
+## Remarks
+
+The Microsoft C++ compiler uses reserved section names for internal implementation of features such as C++ dynamic initialization. If your code creates a section with the same name as a reserved section, such as `.CRT$XCU`, it interferes with the compiler. It may prevent other dynamic initialization and cause undefined behavior.
+
+To resolve this error, don't create a section that uses the reserved name.
+
+There's no C++ standard conforming way to initialize variables across translation units, in a specific relative order with compiler generated dynamic initializers. Ways to force initialization before or after compiler generated C++ dynamic initializers are implementation-specific. For more information on Microsoft-specific implementation details, see [CRT initialization](../../c-runtime-library/crt-initialization.md).
+
+Compiler Warning C5247 is new in Visual Studio 2019 version 16.11. It's off by default. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md).
+
+## Example
+
+Code that tries to emulate the C++ compiler behavior for dynamic initialization often takes this form:
+
+```cpp
+void f();
+typedef void (*type)();
+
+#pragma section(".CRT$XCU", read)
+__declspec(allocate(".CRT$XCU")) type i = f;
+```
+
+This code creates a section using a reserved name, `.CRT$XCU`. It stops the compiler from creating the section with the expected properties, and it may skip other initializations. The variable `i` placed in the section is a regular variable, and isn't considered an initializer by the compiler. The compiler may optimize `i` away. The relative order when `f` gets called compared to other dynamic initializers is unspecified.
+
+If initialization order isn't important, you can use this pattern to dynamically initialize a variable at startup:
+
+```cpp
+void f();
+
+struct init_helper {
+    init_helper() { f(); }
+};
+
+init_helper i;
+```
+
+## See also
+
+[CRT initialization](../../c-runtime-library/crt-initialization.md)

docs/error-messages/compiler-warnings/c5248.md

@@ -0,0 +1,50 @@
+---
+title: "Compiler Warning C5248"
+description: Compiler warning C5248 description and solution.
+ms.date: 08/02/2021
+f1_keywords: ["C5248"]
+helpviewer_keywords: ["C5248"]
+---
+# Compiler Warning C5248
+
+> section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified
+
+## Remarks
+
+The Microsoft C++ compiler uses reserved section names for internal implementation of features such as C++ dynamic initialization. If your code inserts a variable in a reserved section, such as `.CRT$XCU`, it interferes with the compiler. Your variable isn't considered a C++ dynamic initializer. Also, its relative initialization order compared to compiler generated dynamic initializers isn't specified.
+
+To resolve this error, don't create a section that uses the reserved name or insert a variable in the reserved section.
+
+There's no C++ standard conforming way to initialize variables across translation units, in a specific relative order with compiler generated dynamic initializers. Ways to force initialization before or after compiler generated C++ dynamic initializers are implementation-specific. For more information on Microsoft-specific implementation details, see [CRT initialization](../../c-runtime-library/crt-initialization.md).
+
+Compiler Warning C5248 is new in Visual Studio 2019 version 16.11. It's off by default. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md).
+
+## Example
+
+Code that tries to emulate the C++ compiler behavior for dynamic initialization often takes this form:
+
+```cpp
+void f();
+typedef void (*type)();
+
+#pragma section(".CRT$XCU", read)
+__declspec(allocate(".CRT$XCU")) type i = f;
+```
+
+This code creates a section using a reserved name, `.CRT$XCU`. It stops the compiler from creating the section with the expected properties, and it may skip other initializations. The variable `i` placed in the section is a regular variable, and isn't considered an initializer by the compiler. The compiler may optimize `i` away. The relative order when `f` gets called compared to other dynamic initializers is unspecified.
+
+If initialization order isn't important, you can use this pattern to dynamically initialize a variable at startup:
+
+```cpp
+void f();
+
+struct init_helper {
+    init_helper() { f(); }
+};
+
+init_helper i;
+```
+
+## See also
+
+[CRT initialization](../../c-runtime-library/crt-initialization.md)