New standard template library named module import tutorial (#4682) (#4688)

* new topic: import the stl using named modules

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

Author: huypub

docs/build/walkthrough-header-units.md

@@ -11,7 +11,7 @@ monikerRange: '>=msvc-160'
 
 # Walkthrough: Build and import header units in Microsoft Visual C++
 
-This article is about building and importing header units with Visual Studio 2022. To learn how to import Standard Template Library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md).
+This article is about building and importing header units with Visual Studio 2022. To learn how to import C++ standard library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md).
 
 Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). Header units are easier to set up and use, are significantly smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio).
 
@@ -49,7 +49,7 @@ There are several ways to compile a file into a header unit:
 
 - **Automatically scan for and build header units**. This approach is convenient, but is best suited to smaller projects because it doesn't guarantee optimal build throughput. For details about this approach, see [Approach 2: Automatically scan for header units](#approach2).
 
-- As mentioned in the introduction, you can build and import STL header files as header units and automatically treat `#include` for STL library headers as `import` without rewriting your code. To see how, visit [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md).
+- As mentioned in the introduction, you can build and import STL header files as header units, and automatically treat `#include` for STL library headers as `import` without rewriting your code. To see how, visit [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md).
 
 ## <a name="approach1"></a>Approach 1: Translate a specific file into a header unit
 
@@ -157,4 +157,5 @@ Enabling the new preprocessor affects the processing of variadic macros. For mor
 [`/headerUnit`](./reference/headerunit.md)\
 [`header-units.json`](./reference/header-unit-json-reference.md)\
 [Overview of modules in C++](../cpp/modules-cpp.md)\
+[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
 [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)

docs/build/walkthrough-import-stl-header-units.md

@@ -10,7 +10,7 @@ monikerRange: '>=msvc-160'
 ---
 # Walkthrough: Import STL libraries as header units
 
-This walkthrough shows how to import C++ Standard Template Library (STL) libraries as header units in Visual Studio.
+This walkthrough shows how to import C++ Standard Template Library (STL) libraries as header units in Visual Studio. For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md).
 
 Importing an STL header as a header unit is simpler than using [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use, are substantially smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio).
 
@@ -219,5 +219,6 @@ The main consideration for whether to use this approach is the balance between c
 
 ## See also
 
-[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md) \
+[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
+[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\
 [`/translateInclude`](./reference/translateinclude.md)

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

@@ -1,12 +1,12 @@
 ---
-title: "C runtime (CRT) and C++ Standard Library (STL) lib files"
-description: "List of Microsoft C runtime and C++ Standard Library (STL) lib files that you can link against and their associated compiler options and preprocessor directives."
+title: "C runtime (CRT) and C++ standard library (STL) lib files"
+description: "List of Microsoft C runtime and C++ standard library (STL) lib files that you can link against and their associated compiler options and preprocessor directives."
 ms.date: "3/5/2021"
 ms.topic: "reference"
 ms.custom: contperf-fy21q3
 helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries", "STL libraries", "Microsoft standard template libraries"]
 ---
-# C runtime (CRT) and C++ Standard Library (STL) `.lib` files
+# C runtime (CRT) and C++ standard library (STL) `.lib` files
 
 This article lists the Microsoft C runtime library `.lib` files that you can link against when you develop your application, and their associated compiler options and preprocessor directives.
 
@@ -15,13 +15,13 @@ See [Redistributing Visual C++ files](../windows/redistributing-visual-cpp-files
 See [C runtime library reference](./c-run-time-library-reference.md) if you're looking for API reference for the C runtime library.
 
 >[!NOTE]
-> Microsoft's implementation of the C++ Standard Library is often referred to as the *STL* or *Standard Template Library*. Although *C++ Standard Library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation.
+> Microsoft's implementation of the C++ standard library is often referred to as the *STL* or *Standard Template Library*. Although *C++ standard library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation.
 
-From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ Standard Library. The Standard Library also incorporated the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ Standard Library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ Standard Library as a whole.
+From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ standard library. The standard library also incorporates the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ standard library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ standard library as a whole.
 
 ## C runtime `.lib` files
 
-The C runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files.
+The ISO C standard library is part of the C++ standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files.
 
 In Visual Studio 2015, the CRT was refactored into new binaries. The Universal CRT (UCRT) contains the functions and globals exported by the standard C99 CRT library. The UCRT is now a Windows component, and ships as part of Windows 10 and later versions. The static library, DLL import library, and header files for the UCRT are now found in the Windows SDK. When you install Visual C++, Visual Studio setup installs the subset of the Windows SDK required to use the UCRT. You can use the UCRT on any version of Windows supported by Visual Studio 2015 and later versions. You can redistribute it using vcredist for supported versions of Windows other than Windows 10 or later. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md).
 
@@ -47,7 +47,7 @@ This table lists the libraries that implement the vcruntime library.
 
 > [!NOTE]
 > When the UCRT was refactored, the Concurrency Runtime functions were moved into
-*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ Standard Library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables.
+*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ standard library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables.
 
 The code that initializes the CRT is in one of several libraries, based on whether the CRT library is statically or dynamically linked, or native, managed, or mixed code. This code handles CRT startup, internal per-thread data initialization, and termination. It's specific to the version of the compiler used. This library is always statically linked, even when using a dynamically linked UCRT.
 
@@ -78,16 +78,16 @@ To build a debug version of your application, the [`_DEBUG`](./debug.md) flag mu
 
 This version of the CRT isn't fully conformant with the C99 standard. In versions before Visual Studio 2019 version 16.8, the `<tgmath.h>` header isn't supported. In all versions, the `CX_LIMITED_RANGE` and `FP_CONTRACT` pragma macros aren't supported. Certain elements such as the meaning of parameter specifiers in standard IO functions use legacy interpretations by default. You can use **`/Zc`** compiler conformance options and specify linker options to control some aspects of library conformance.
 
-## C++ Standard Library (STL) `.lib` files
+## C++ standard library (STL) `.lib` files
 
-| C++ Standard Library | Characteristics | Option | Preprocessor directives |
+| C++ standard library | Characteristics | Option | Preprocessor directives |
 |--|--|--|--|
 | *`libcpmt.lib`* | Multithreaded, static link | **`/MT`** | `_MT` |
 | *`msvcprt.lib`* | Multithreaded, dynamic link (import library for *`msvcp<version>.dll`*) | **`/MD`** | `_MT`, `_DLL` |
 | *`libcpmtd.lib`* | Multithreaded, static link | **`/MTd`** | `_DEBUG`, `_MT` |
 | *`msvcprtd.lib`* | Multithreaded, dynamic link (import library for *`msvcp<version>d.dll`*) | **`/MDd`** | `_DEBUG`, `_MT`, `_DLL` |
 
-When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ Standard Library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ Standard Library will be linked automatically by Visual C++ at compile time. For example:
+When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ standard library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ standard library will be linked automatically by Visual C++ at compile time. For example:
 
 ```cpp
 #include <ios>

docs/cpp/modules-cpp.md

@@ -12,13 +12,21 @@ You can use modules side by side with header files. A C++ source file can `impor
 
 ## Enable modules in the Microsoft C++ compiler
 
-Modules have had experimental support in the Microsoft C++ compiler for a long time. As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler. You can use the modules feature to create single-partition modules and to import the Standard Library modules provided by Microsoft. To enable support for Standard Library modules, compile with [`/experimental:module`](../build/reference/experimental-module.md) and [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). In a Visual Studio project, right-click the project node in **Solution Explorer** and choose **Properties**. Set the **Configuration** drop-down to **All Configurations**, then choose **Configuration Properties** > **C/C++** > **Language** > **Enable C++ Modules (experimental)**.
+As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler.
+
+Before it was specified by the C++20 standard, Microsoft had experimental support for modules in the Microsoft C++ compiler. The compiler also supported importing the Standard Library as modules, described below.
+
+Starting with Visual Studio 2022 version 17.5, importing the Standard Library as a module is both standardized and fully implemented in the Microsoft C++ compiler. This section describes the older, experimental method, which is still supported. For information about the new standardized way to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md).
+
+You can use the modules feature to create single-partition modules and to import the Standard Library modules provided by Microsoft. To enable support for Standard Library modules, compile with [`/experimental:module`](../build/reference/experimental-module.md) and [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). In a Visual Studio project, right-click the project node in **Solution Explorer** and choose **Properties**. Set the **Configuration** drop-down to **All Configurations**, then choose **Configuration Properties** > **C/C++** > **Language** > **Enable C++ Modules (experimental)**.
 
 A module and the code that consumes it must be compiled with the same compiler options.
 
-## Consume the C++ Standard Library as modules
+## Consume C++ Standard Library as modules (experimental)
+
+This section describes the experimental implementation, which is still supported. The new standardized way of consuming the C++ Standard Library as modules is described in [Import the C++ standard library using modules](tutorial-import-stl-named-module.md).
 
-Although not specified by the C++20 standard, Microsoft makes its implementation of the C++ Standard Library importable as modules. By importing the C++ Standard Library as modules rather than including it through header files, you can potentially speed up compilation times depending on the size of your project. The library is split into the following named modules:
+By importing the C++ Standard Library as modules rather than including it through header files, you can potentially speed up compilation times depending on the size of your project. The experimental library is split into the following named modules:
 
 - `std.regex` provides the content of header `<regex>`
 - `std.filesystem` provides the content of header `<filesystem>`
@@ -99,7 +107,7 @@ The `import` declaration can appear only at global scope.
 
 ## Implementing modules
 
-A *module interface* exports the module name and all the namespaces, types, functions and so on that make up the public interface of the module. A *module implementation* defines the things exported by the module. In its simplest form, a module can consist of a single file that combines the module interface and implementation. You can also put the implementations in one or more separate module implementation files, similar to how *`.h`* and *`.cpp`* files are used.
+A *module interface* exports the module name and all the namespaces, types, functions, and so on that make up the public interface of the module. A *module implementation* defines the things exported by the module. In its simplest form, a module can consist of a single file that combines the module interface and implementation. You can also put the implementations in one or more separate module implementation files, similar to how *`.h`* and *`.cpp`* files are used.
 
 For larger modules, you can split parts of the module into submodules called *partitions*. Each partition consists of a module interface file that exports a module partition name. A partition may also have one or more partition implementation files. The module as a whole has one *primary module interface*, the public interface of the module that may also import and export the partition interfaces.
 

docs/cpp/toc.yml

@@ -554,6 +554,8 @@ items:
           href: ../cpp/modules-cpp.md
         - name: module, import, export
           href: ../cpp/import-export-module.md
+        - name: "Tutorial: Import the standard library as a module"
+          href: ../cpp/tutorial-import-stl-named-module.md
         - name: Named modules tutorial in C++
           href: ../cpp/tutorial-named-modules-cpp.md
     - name: Templates