From b78a34641b4995fbee8527168078a0a318ae1e80 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Tue, 11 Feb 2025 16:30:51 -0800 Subject: [PATCH 1/7] deemphasize experimental modules --- docs/build/reference/experimental-module.md | 30 ++++++++--- docs/cpp/import-export-module.md | 4 +- docs/cpp/modules-cpp.md | 56 ++++++-------------- docs/cpp/tutorial-import-stl-named-module.md | 4 +- 4 files changed, 40 insertions(+), 54 deletions(-) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index bd1c16ed79e..7525b47d2a2 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -5,9 +5,9 @@ ms.date: 01/27/2022 f1_keywords: ["module", "/experimental:module"] helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- -# `/experimental:module` (Enable module support) +# `/experimental:module` (Enable experimental module support) -Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio version 16.11 and later. It's still required (along with [`/std:c++latest`](std-specify-language-standard-version.md)) for the experimental Standard library modules. +Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio version 16.11 and later. This switch is only used (along with [`/std:c++latest`](std-specify-language-standard-version.md)) if you are still using the older experimental Standard library modules. We recommend that you use the new Standard Library modules provided by Microsoft without using this switch. ## Syntax @@ -15,20 +15,34 @@ Enables experimental compiler support for C++ Standard modules. This option is o ## Remarks -In versions of Visual Studio before Visual Studio 2019 version 16.11, you can enable experimental modules support by use of the **`/experimental:module`** compiler option along with the [`/std:c++latest`](std-specify-language-standard-version.md) option. In Visual Studio 2019 version 16.11, module support is enabled automatically by either **`/std:c++20`** or **`/std:c++latest`**. Use **`/experimental:module-`** to disable module support explicitly. +In versions of Visual Studio before Visual Studio 2019 version 16.11, you can enable experimental modules support using the **`/experimental:module`** compiler option along with the [`/std:c++latest`](std-specify-language-standard-version.md) option. In Visual Studio 2019 version 16.11, module support is enabled automatically by either **`/std:c++20`** or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. -This option is available starting in Visual Studio 2015 Update 1. As of Visual Studio 2019 version 16.2, C++20 Standard modules aren't fully implemented in the Microsoft C++ compiler. Modules support is feature complete in Visual Studio 2019 version 16.10. You can use the modules feature import the Standard Library modules provided by Microsoft. A module and the code that consumes it must be compiled with the same compiler options. +This compiler switch is available starting in Visual Studio 2015 Update 1. Modules support is feature complete in Visual Studio 2019 version 16.10. You can use the modules feature import the Standard Library modules provided by Microsoft. 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). -For more information on modules and how to use and create them, see [Overview of modules in C++](../../cpp/modules-cpp.md). +For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). + +The experimental library consists of the following named modules: + +- `std.regex` provides the content of header `` +- `std.filesystem` provides the content of header `` +- `std.memory` provides the content of header `` +- `std.threading` provides the contents of headers ``, ``, ``, ``, ``, and `` +- `std.core` provides everything else in the C++ Standard Library + +To consume these modules, add an import declaration to the top of the source code file. For example: + +```cpp +import std.core; +import std.regex; +``` + +To consume the experimental Microsoft Standard Library modules, compile your program with the [`/EHsc`](../build/reference/eh-exception-handling-model.md) and [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) options. ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Set the **Configuration** drop-down to **All Configurations**. - 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. - 1. Modify the **Enable C++ Modules (experimental)** property, and then choose **OK**. ## See also diff --git a/docs/cpp/import-export-module.md b/docs/cpp/import-export-module.md index 349708fa551..876aed188a3 100644 --- a/docs/cpp/import-export-module.md +++ b/docs/cpp/import-export-module.md @@ -1,13 +1,13 @@ --- title: "module, import, export" -ms.date: 02/14/2022 +ms.date: 02/11/2025 f1_keywords: ["module_cpp", "import_cpp", "export_cpp"] helpviewer_keywords: ["modules [C++]", "modules [C++], import", "modules [C++], export"] description: Use import and export declarations to access and to publish types and functions defined in the specified module. --- # `module`, `import`, `export` -The **`module`**, **`import`**, and **`export`** declarations are available in C++20 and require the [`/experimental:module`](../build/reference/experimental-module.md) compiler switch along with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**). For more information, see [Overview of modules in C++](modules-cpp.md). +The **`module`**, **`import`**, and **`export`** declarations are available in C++20 and require the compiler switch [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**). For more information, see [Overview of modules in C++](modules-cpp.md). ## `module` diff --git a/docs/cpp/modules-cpp.md b/docs/cpp/modules-cpp.md index bfdbfb73467..5e54689e96d 100644 --- a/docs/cpp/modules-cpp.md +++ b/docs/cpp/modules-cpp.md @@ -1,6 +1,6 @@ --- title: "Overview of modules in C++" -ms.date: 01/29/2024 +ms.date: 02/11/2025 helpviewer_keywords: ["modules [C++]", "modules [C++], overview"] description: Modules in C++20 provide a modern alternative to header files. --- @@ -14,44 +14,15 @@ You can use modules side by side with header files. A C++ source file can `impor To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). -## Enable modules in the Microsoft C++ compiler +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. To learn how to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md). -As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler. +## Single-partition modules -Before it was specified by the C++20 standard, Microsoft had experimental support for modules. The compiler also supported importing prebuilt Standard Library modules, described below. +A single-partition module is a module that consists of a single source file. The module interface and implementation are in the same file. -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). +The following single-partition module example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. You can also place the definitions in one or more separate module implementation files, as shown in a later example, but this is an example of a single-partition module. -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 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). - -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 `` -- `std.filesystem` provides the content of header `` -- `std.memory` provides the content of header `` -- `std.threading` provides the contents of headers ``, ``, ``, ``, ``, and `` -- `std.core` provides everything else in the C++ Standard Library - -To consume these modules, add an import declaration to the top of the source code file. For example: - -```cpp -import std.core; -import std.regex; -``` - -To consume the Microsoft Standard Library modules, compile your program with the [`/EHsc`](../build/reference/eh-exception-handling-model.md) and [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) options. - -## Example - -The following example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. However, you can also place the definitions in one or more separate module implementation files, as shown in a later example. - -The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier on `f()` indicates that this function is visible when another program or module imports `Example`. +The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier before `int f()` indicates that this function is visible when another program or module imports `Example`: ```cpp // Example.ixx @@ -61,12 +32,14 @@ export module Example; namespace Example_NS { - int f_internal() { - return ANSWER; - } + int f_internal() + { + return ANSWER; + } - export int f() { - return f_internal(); + export int f() + { + return f_internal(); } } ``` @@ -88,7 +61,7 @@ int main() } ``` -The `import` declaration can appear only at global scope. +The `import` declaration can appear only at global scope. A module and the code that consumes it must be compiled with the same compiler options. ## Module grammar @@ -138,6 +111,7 @@ When the compiler does argument-dependent lookup for overload resolutions in the ### Module partitions A module partition is similar to a module, except: + - It shares ownership of all declarations in the entire module. - All names exported by partition interface files are imported and exported by the primary interface file. - A partition's name must begin with the module name followed by a colon (`:`). diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index de5eec7bcf4..8640f0c5287 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -24,7 +24,7 @@ This tutorial requires Visual Studio 2022 17.5 or later. ## Introduction to standard library modules -Header files suffer from semantics that can change depending on macro definitions, the order in which you include them, and they slow compilation. Modules solve these problems. +Header file semantics can change depending on macro definitions, the order in which you include them, and they slow compilation. Modules solve these problems. It's now possible to import the standard library as a module instead of as a tangle of header files. This is much faster and more robust than including header files or header units or precompiled headers (PCH). @@ -45,8 +45,6 @@ C++20 introduces a modern alternative called *modules*. In C++23, we were able t Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules aren't fragile and are easier to compose because their semantics don't change due to macro definitions or the order in which you import them. The compiler can process modules much faster than it can process `#include` files, and uses less memory at compile time as well. Named modules don't expose macro definitions or private implementation details. -For in depth information about modules, see [Overview of modules in C++](modules-cpp.md) That article also discusses consuming the C++ standard library as modules, but uses an older and experimental way of doing it. - This article demonstrates the new and best way to consume the standard library. For more information about alternative ways to consume the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). ## Import the standard library with `std` From 92fc56d9fb9d215d69047d75671c4b1bb4f96641 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Wed, 12 Feb 2025 10:59:32 -0800 Subject: [PATCH 2/7] review edits --- docs/build/reference/experimental-module.md | 12 ++++++++---- docs/cpp/tutorial-named-modules-cpp.md | 9 +++++---- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index 7525b47d2a2..5f53625ea07 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -1,13 +1,13 @@ --- title: "/experimental:module (Enable module support)" description: "Use the /experimental:module compiler option to enable experimental compiler support for named modules." -ms.date: 01/27/2022 +ms.date: 02/12/2025 f1_keywords: ["module", "/experimental:module"] helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- # `/experimental:module` (Enable experimental module support) -Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio version 16.11 and later. This switch is only used (along with [`/std:c++latest`](std-specify-language-standard-version.md)) if you are still using the older experimental Standard library modules. We recommend that you use the new Standard Library modules provided by Microsoft without using this switch. +Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio 2019 version 16.11 and later. This switch is only used (along with [`/std:c++latest`](std-specify-language-standard-version.md)) if you are still using the older experimental Standard library modules. We recommend that you use the new Standard Library modules provided by Microsoft without using this switch. ## Syntax @@ -15,9 +15,13 @@ Enables experimental compiler support for C++ Standard modules. This option is o ## Remarks +Although you can use this switch to use the older experimental named modules listed below, we recommend that you use the the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). + +Before you can use the experimental modules, ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C++ support in Visual Studio](../install/install-visual-cpp.md). + In versions of Visual Studio before Visual Studio 2019 version 16.11, you can enable experimental modules support using the **`/experimental:module`** compiler option along with the [`/std:c++latest`](std-specify-language-standard-version.md) option. In Visual Studio 2019 version 16.11, module support is enabled automatically by either **`/std:c++20`** or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. -This compiler switch is available starting in Visual Studio 2015 Update 1. Modules support is feature complete in Visual Studio 2019 version 16.10. You can use the modules feature import the Standard Library modules provided by Microsoft. 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). +This compiler switch is available starting in Visual Studio 2015 Update 1. Modules support is feature complete in Visual Studio 2019 version 16.10. For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). @@ -36,7 +40,7 @@ import std.core; import std.regex; ``` -To consume the experimental Microsoft Standard Library modules, compile your program with the [`/EHsc`](../build/reference/eh-exception-handling-model.md) and [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) options. +To consume the experimental Microsoft Standard Library modules, compile your program with the [`/EHsc`](eh-exception-handling-model.md) and [`/MD`](md-mt-ld-use-run-time-library.md) options. ### To set this compiler option in the Visual Studio development environment diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index 89830e77642..a9f9924a0db 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -1,6 +1,6 @@ --- title: "Named modules tutorial in C++" -ms.date: 08/08/2022 +ms.date: 02/12/2025 ms.topic: "tutorial" author: "tylermsft" ms.author: "twhitney" @@ -237,7 +237,7 @@ int main() } ``` -The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It can come before or after any `#include` directives. +The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It should come after any `#include` directives. The app then uses the types and functions from the module to output the area and width of the defined rectangle: @@ -265,7 +265,7 @@ module; // optional. Defines the beginning of the global module fragment // #include directives go here but only apply to this file and // aren't shared with other module implementation files. -// Macro definitions aren't visible outside this file, or to importers. +// Macro definitions aren't visible outside this file or to importers. // import statements aren't allowed here. They go in the module preamble, below. export module [module-name]; // Required. Marks the beginning of the module preamble @@ -305,7 +305,8 @@ Module implementation units are useful for breaking up a large module into small Module implementation unit files have a *`.cpp`* extension. The basic outline of a module implementation unit file is: ```cpp -// optional #include or import statements. These only apply to this file +// optional #include statements. These only apply to this file +// optional import statements. These only apply to this file // imports in the associated module's interface are automatically available to this file module [module-name]; // required. Identifies which named module this implementation unit belongs to From 5bfd63f272628193be3b642065ede4042ee3f0a5 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Wed, 12 Feb 2025 13:39:43 -0800 Subject: [PATCH 3/7] edits --- docs/build/reference/experimental-module.md | 19 +++++++++++-------- docs/cpp/import-export-module.md | 4 ++-- docs/cpp/tutorial-named-modules-cpp.md | 8 +++----- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index 5f53625ea07..a3a4ea0a5d2 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- # `/experimental:module` (Enable experimental module support) -Enables experimental compiler support for C++ Standard modules. This option is obsolete for C++20 standard modules in Visual Studio 2019 version 16.11 and later. This switch is only used (along with [`/std:c++latest`](std-specify-language-standard-version.md)) if you are still using the older experimental Standard library modules. We recommend that you use the new Standard Library modules provided by Microsoft without using this switch. +Enables compiler support for an experimental form of C++ Standard modules. This option is obsolete in Visual Studio 2019 version 16.11 and later. ## Syntax @@ -15,15 +15,16 @@ Enables experimental compiler support for C++ Standard modules. This option is o ## Remarks -Although you can use this switch to use the older experimental named modules listed below, we recommend that you use the the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). +Although you can use this switch to use the older experimental named modules, we recommend that you use the the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). -Before you can use the experimental modules, ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C++ support in Visual Studio](../install/install-visual-cpp.md). +This compiler switch is available starting in Visual Studio 2015 Update 1. Ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C++ support in Visual Studio](../install/install-visual-cpp.md). -In versions of Visual Studio before Visual Studio 2019 version 16.11, you can enable experimental modules support using the **`/experimental:module`** compiler option along with the [`/std:c++latest`](std-specify-language-standard-version.md) option. In Visual Studio 2019 version 16.11, module support is enabled automatically by either **`/std:c++20`** or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. - -This compiler switch is available starting in Visual Studio 2015 Update 1. Modules support is feature complete in Visual Studio 2019 version 16.10. - -For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). +| Version | Status | +|---|---| +| Visual Studio 2015 Update 1 | `/experimental:module` is available. | +| Visual Studio 2019 version 16.10 | C++20 modules support is feature complete. | +| Visual Studio 2019 16.11 and earlier | Enable experimental modules support using **`/experimental:module`** along with [`/std:c++latest`](std-specify-language-standard-version.md). | +| Visual Studio 2019 version 16.11 and later | Modules support is enabled automatically with **`/std:c++20`** or later, or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. | The experimental library consists of the following named modules: @@ -49,6 +50,8 @@ To consume the experimental Microsoft Standard Library modules, compile your pro 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. 1. Modify the **Enable C++ Modules (experimental)** property, and then choose **OK**. +For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). + ## See also [`/headerUnit` (Use header unit IFC)](headerunit.md)\ diff --git a/docs/cpp/import-export-module.md b/docs/cpp/import-export-module.md index 876aed188a3..fa085680f74 100644 --- a/docs/cpp/import-export-module.md +++ b/docs/cpp/import-export-module.md @@ -1,6 +1,6 @@ --- title: "module, import, export" -ms.date: 02/11/2025 +ms.date: 02/12/2025 f1_keywords: ["module_cpp", "import_cpp", "export_cpp"] helpviewer_keywords: ["modules [C++]", "modules [C++], import", "modules [C++], export"] description: Use import and export declarations to access and to publish types and functions defined in the specified module. @@ -19,7 +19,7 @@ module ModuleA; ## `export` -Use an **`export module`** declaration for the module's primary interface file, which must have extension *`.ixx`*: +Use an **`export module`** declaration for the module's primary interface file, which should have an extension *`.ixx`* by default. If you want to use a different extension, you'll need to use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. ```cpp export module ModuleA; diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index a9f9924a0db..24ec86cfd67 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -9,7 +9,7 @@ description: Named modules in C++20 provide a modern alternative to header files --- # Named modules tutorial (C++) -This tutorial is about creating C++20 modules. Modules replace header files. You'll learn how modules are an improvement on header files. +This tutorial is about creating C++20 modules. Modules are a significant improvement on header files. In this tutorial, learn how to: @@ -22,13 +22,11 @@ In this tutorial, learn how to: This tutorial requires Visual Studio 2022 17.1.0 or later. -You might get IntelliSense errors while working on the code example in this tutorial. Work on the IntelliSense engine is catching up with the compiler. IntelliSense errors can be ignored and won't prevent the code example from building. To track progress on the IntelliSense work, see this [issue](https://developercommunity.visualstudio.com/t/When-importing-a-C20-module-or-header-/1550846). - ## What are C++ modules -Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and difficult to compose. They may compile differently depending on the order you include them in, or on the macros that are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. +Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and difficult to compose. They may compile differently depending on the order you include them in or on the macros that are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. -C++20 introduces a modern approach to componentizing C++ programs: *modules*. +C++20 introduces *modules* as a modern approach to componentizing C++ programs. Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules don't leak macro definitions or private implementation details. From bf4e2bc9e1d867de0161790706adc30d1bfa23e3 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Wed, 12 Feb 2025 14:38:37 -0800 Subject: [PATCH 4/7] fix link, acrolinx --- docs/build/reference/experimental-module.md | 2 +- docs/cpp/import-export-module.md | 2 +- docs/cpp/tutorial-import-stl-named-module.md | 4 +-- docs/cpp/tutorial-named-modules-cpp.md | 28 ++++++++++---------- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index a3a4ea0a5d2..963d9a06cc3 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -17,7 +17,7 @@ Enables compiler support for an experimental form of C++ Standard modules. This Although you can use this switch to use the older experimental named modules, we recommend that you use the the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). -This compiler switch is available starting in Visual Studio 2015 Update 1. Ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C++ support in Visual Studio](../install/install-visual-cpp.md). +This compiler switch is available starting in Visual Studio 2015 Update 1. Ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C and C++ support in Visual Studio](../vscpp-step-0-installation.md). | Version | Status | |---|---| diff --git a/docs/cpp/import-export-module.md b/docs/cpp/import-export-module.md index fa085680f74..6275e350060 100644 --- a/docs/cpp/import-export-module.md +++ b/docs/cpp/import-export-module.md @@ -19,7 +19,7 @@ module ModuleA; ## `export` -Use an **`export module`** declaration for the module's primary interface file, which should have an extension *`.ixx`* by default. If you want to use a different extension, you'll need to use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. +Use an **`export module`** declaration for the module's primary interface file, which should have an extension *`.ixx`* by default. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. ```cpp export module ModuleA; diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 8640f0c5287..b2c961353f2 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -39,7 +39,7 @@ Because named modules don't expose macros, macros like `assert`, `errno`, `offse ## About C++ modules -Header files are how declarations and definitions have been shared between source files in C++. Prior to standard library modules, you'd include the part of the standard library you needed with a directive like `#include `. Header files are fragile and difficult to compose because their semantics may change depending on the order you include them, or whether certain macros are defined. They also slow compilation because they're reprocessed by every source file that includes them. +Header files are how declarations and definitions have been shared between source files in C++. Before standard library modules, you'd include the part of the standard library you needed with a directive like `#include `. Header files are fragile and difficult to compose because their semantics may change depending on the order you include them, or whether certain macros are defined. They also slow compilation because they're reprocessed by every source file that includes them. C++20 introduces a modern alternative called *modules*. In C++23, we were able to capitalize on module support to introduce named modules to represent the standard library. @@ -55,7 +55,7 @@ The statement `import std;` or `import std.compat;` imports the standard library ### Example: How to build and import `std` -1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. +1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. 1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation. 1. Compile the `std` named module with the following command: diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index 24ec86cfd67..e1b3fe1d0a5 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -48,7 +48,7 @@ Your code can consume modules in the same project, or any referenced projects, a ## Create the project -As we build a simple project, we'll look at various aspects of modules. The project will implement an API using a module instead of a header file. +As we build a simple project, we look at various aspects of modules. The project implements an API using a module instead of a header file. In Visual Studio 2022 or later, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. @@ -60,7 +60,7 @@ Because modules are a C++20 feature, use the [`/std:c++20` or `/std:c++latest`]( ## Create the primary module interface unit -A module consists of one or more files. One of these files must be what is called the *primary module interface unit*. It defines what the module exports; that is, what importers of the module will see. There can only be one primary module interface unit per module. +A module consists of one or more files. One of these files must be what is called the *primary module interface unit*. It defines what the module exports; that is, what importers of the module see. There can only be one primary module interface unit per module. To add a primary module interface unit, in **Solution Explorer**, right-click **Source Files** then select **Add** > **Module**. @@ -86,13 +86,13 @@ Replace the contents of *`BasicPlane.Figures.ixx`* file with: export module BasicPlane.Figures; // the export module keywords mark this file as a primary module interface unit ``` -This line identifies this file as the primary module interface and gives the module a name: `BasicPlane.Figures`. The period in the module name has no special meaning to the compiler. A period can be used to convey how your module is organized. If you have multiple module files that work together, you can use periods to indicate a separation of concerns. In this tutorial, we'll use periods to indicate different functional areas of the API. +This line identifies this file as the primary module interface and gives the module a name: `BasicPlane.Figures`. The period in the module name has no special meaning to the compiler. A period can be used to convey how your module is organized. If you have multiple module files that work together, you can use periods to indicate a separation of concerns. In this tutorial, periods indicate different functional areas of the API. This name is also where the "named" in "named module" comes from. The files that are part of this module use this name to identify themselves as part of the named module. A named module is the collection of module units with the same module name. We should talk about the API we'll implement for a moment before going further. It impacts the choices we make next. The API represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes such as `Rectangle`. -To illustrate some features of modules, we'll factor this API into pieces. One piece will be the `Point` API. The other part will be `Rectangle`. Imagine that this API will grow into something more complex. The division is useful for separating concerns or easing code maintenance. +To illustrate some features of modules, we factor this API into pieces. One piece is the `Point` API. The other part is `Rectangle`. Imagine that this API will grow into something more complex. The division is useful for separating concerns or easing code maintenance. So far, we've created the primary module interface that will expose this API. Let's now build the `Point` API. We want it to be part of this module. For reasons of logical organization, and potential build efficiency, we want to make the code for this part of the API a *module partition* file. @@ -106,7 +106,7 @@ When you import a partition into the primary module, all its declarations become To create a module partition file, in the **Solution Explorer** right-click **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Point.ixx`* and choose **Add**. -Because it's a module partition file, we've added a hyphen and the name of the partition to the module name. This convention aids the compiler in the command-line case because the compiler uses name lookup rules based on the module name to find the compiled *`.ifc`* file for the partition. This way you don't have to provide explicit `/reference` command-line arguments to find the partitions that belong to the module. It's also helpful for organizing the files that belong to a module by name because you can easily see which files belong to which modules. +Because it's a module partition file, we add a hyphen and the name of the partition to the module name. This convention aids the compiler in the command-line case because the compiler uses name lookup rules based on the module name to find the compiled *`.ifc`* file for the partition. This way you don't have to provide explicit `/reference` command-line arguments to find the partitions that belong to the module. It's also helpful for organizing the files that belong to a module by name because you can easily see which files belong to which modules. Replace the contents of *`BasicPlane.Figures-Point.ixx`* with: @@ -127,7 +127,7 @@ In this file, the `export` keyword makes `struct Point` visible to consumers. ### `Rectangle` module partition example -The next partition we'll define is `Rectangle`. Create another module file using the same steps as before: In **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Rectangle.ixx`* and select **Add**. +The next partition we define is `Rectangle`. Create another module file using the same steps as before: In **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Rectangle.ixx`* and select **Add**. Replace the contents of *`BasicPlane.Figures-Rectangle.ixx`* with: @@ -154,13 +154,13 @@ Next, `import :Point;` shows how to import a module partition. The `import` stat Next, the code exports the definition of `struct Rectangle` and declarations for some functions that return various properties of the rectangle. The `export` keyword indicates whether to make what it precedes visible to consumers of the module. It's used to make the functions `area`, `height`, and `width` visible outside of the module. -All definitions and declarations in a module partition are visible to the importing module unit whether they have the `export` keyword or not. The `export` keyword governs whether the definition, declaration, or typedef will be visible outside of the module when you export the partition in the primary module interface. +All definitions and declarations in a module partition are visible to the importing module unit whether they have the `export` keyword or not. The `export` keyword governs whether the definition, declaration, or typedef is visible outside of the module when you export the partition in the primary module interface. Names are made visible to consumers of a module in several ways: - Put the keyword `export` in front of each type, function, and so on, that you want to export. - If you put `export` in front of a namespace, for example `export namespace N { ... }`, everything defined within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. It's not available because that namespace declaration isn't prefaced by `export`, even though there's another namespace with the same name that is. -- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It will be visible to other files that are part of the module, but not to importers of the module. +- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It is visible to other files that are part of the module, but not to importers of the module. - Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file. This section is visible only within the file. - To make an imported module or module partition visible, use `export import`. An example is shown in the next section. @@ -177,11 +177,11 @@ export import :Point; // bring in the Point partition, and export it to consumer export import :Rectangle; // bring in the Rectangle partition, and export it to consumers of this module ``` -The two lines that begin with `export import` are new here. When combined like this, these two keywords instruct the compiler to import the specified module and make it visible to consumers of this module. In this case, the colon (`:`) in the module name indicates that we are importing a module partition. +The two lines that begin with `export import` are new here. When combined like this, these two keywords instruct the compiler to import the specified module and make it visible to consumers of this module. In this case, the colon (`:`) in the module name indicates that we're importing a module partition. The imported names don't include the full module name. For example, the `:Point` partition was declared as `export module BasicPlane.Figures:Point`. Yet here we're importing `:Point`. Because we're in the primary module interface file for the module `BasicPlane.Figures`, the module name is implied, and only the partition name is specified. -So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We'll do that next by creating a module implementation file. +So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We do that next by creating a module implementation file. ## Create a module unit implementation file @@ -217,7 +217,7 @@ Anything you declare within an implementation unit is only visible to the module ## Import the module -Now we'll make use of the module we've defined. Open the *`ModulesTutorial.cpp`* file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: +Now we make use of the module we've defined. Open the *`ModulesTutorial.cpp`* file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: ```cpp #include @@ -250,7 +250,7 @@ Let's now look in more detail at the various module files. ### Primary module interface -A module consists of one or more files. One of them defines the interface that importers will see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, the exported module interface unit doesn't specify a module partition. +A module consists of one or more files. One of them defines the interface that importers see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, the exported module interface unit doesn't specify a module partition. It has an *`.ixx`* extension by default. However, you can treat a source file with any extension as a module interface file. To do so, set the **Compile As** property in the **Advanced** tab for the source file's properties page to **Compile As Module (/interface)**: @@ -357,7 +357,7 @@ A module and the code that imports it must be compiled with the same compiler op - The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named *`BasicPlane.Figures.ixx`*. - The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, *`BasicPlane.Figures-Rectangle.ixx`* -If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler will look for them automatically based on the name of the module. The name of the compiled partition file (ending with an *`.ifc`* extension) is generated from the module name. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler will anticipate that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. +If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler looks for them automatically based on the name of the module. The name of the compiled partition file (ending with an *`.ifc`* extension) is generated from the module name. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler anticipates that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. You can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. @@ -371,7 +371,7 @@ Module partitions make it easier to logically factor a large module. They can be ## Summary -In this tutorial, you've been introduced to the basics of C++20 modules. You've created a primary module interface, defined a module partition, and built a module implementation file. +In this tutorial, you were introduced to the basics of C++20 modules. You've created a primary module interface, defined a module partition, and built a module implementation file. ## See also From 44757c73d8ade3b500b51e679c02098adb6e0106 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Wed, 12 Feb 2025 14:49:06 -0800 Subject: [PATCH 5/7] one more .ixx spot --- docs/cpp/modules-cpp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpp/modules-cpp.md b/docs/cpp/modules-cpp.md index 5e54689e96d..42d238f49a2 100644 --- a/docs/cpp/modules-cpp.md +++ b/docs/cpp/modules-cpp.md @@ -20,7 +20,7 @@ Starting with Visual Studio 2022 version 17.5, importing the Standard Library as A single-partition module is a module that consists of a single source file. The module interface and implementation are in the same file. -The following single-partition module example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. You can also place the definitions in one or more separate module implementation files, as shown in a later example, but this is an example of a single-partition module. +The following single-partition module example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is the default extension for module interface files in Visual Studio. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. In this example, the interface file contains both the function definition and the declaration. You can also place the definitions in one or more separate module implementation files, as shown in a later example, but this is an example of a single-partition module. The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier before `int f()` indicates that this function is visible when another program or module imports `Example`: From 12730210831657cecd6a06fa65d024251cf9a428 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Thu, 13 Feb 2025 10:37:34 -0800 Subject: [PATCH 6/7] typo --- docs/build/reference/experimental-module.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index 963d9a06cc3..6f0cb7d231c 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- # `/experimental:module` (Enable experimental module support) -Enables compiler support for an experimental form of C++ Standard modules. This option is obsolete in Visual Studio 2019 version 16.11 and later. +Enables compiler support for Microsoft's experimental form of C++ Standard modules. This option is obsolete in Visual Studio 2019 version 16.11 and later. ## Syntax @@ -15,13 +15,13 @@ Enables compiler support for an experimental form of C++ Standard modules. This ## Remarks -Although you can use this switch to use the older experimental named modules, we recommend that you use the the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). + This switch was for the time before the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md) was available. Although you can use this switch to use the older experimental named modules, we recommend that you use the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). -This compiler switch is available starting in Visual Studio 2015 Update 1. Ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C and C++ support in Visual Studio](../vscpp-step-0-installation.md). +This compiler became available starting in Visual Studio 2015 Update 1. Ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** in selected the VS Installer. It's available in the **Individual components** tab of the installer. Search for **experimental** to see the option. For more information, see [Install C and C++ support in Visual Studio](../vscpp-step-0-installation.md). | Version | Status | |---|---| -| Visual Studio 2015 Update 1 | `/experimental:module` is available. | +| Visual Studio 2015 Update 1 | `/experimental:module` introduced. | | Visual Studio 2019 version 16.10 | C++20 modules support is feature complete. | | Visual Studio 2019 16.11 and earlier | Enable experimental modules support using **`/experimental:module`** along with [`/std:c++latest`](std-specify-language-standard-version.md). | | Visual Studio 2019 version 16.11 and later | Modules support is enabled automatically with **`/std:c++20`** or later, or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. | From d014854ebf0d2f684003294d463dae570f77d17a Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Thu, 13 Feb 2025 10:50:23 -0800 Subject: [PATCH 7/7] edits --- docs/cpp/import-export-module.md | 4 ++-- docs/cpp/tutorial-named-modules-cpp.md | 22 +++++++++++----------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/cpp/import-export-module.md b/docs/cpp/import-export-module.md index 6275e350060..d04fc5f6d31 100644 --- a/docs/cpp/import-export-module.md +++ b/docs/cpp/import-export-module.md @@ -1,6 +1,6 @@ --- title: "module, import, export" -ms.date: 02/12/2025 +ms.date: 02/13/2025 f1_keywords: ["module_cpp", "import_cpp", "export_cpp"] helpviewer_keywords: ["modules [C++]", "modules [C++], import", "modules [C++], export"] description: Use import and export declarations to access and to publish types and functions defined in the specified module. @@ -19,7 +19,7 @@ module ModuleA; ## `export` -Use an **`export module`** declaration for the module's primary interface file, which should have an extension *`.ixx`* by default. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. +Use an **`export module`** declaration for the module's primary interface file, which has an extension *`.ixx`* by default. If you want to use a different extension, use the [/interface](../build/reference/interface.md) switch to compile it as a module interface. ```cpp export module ModuleA; diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index e1b3fe1d0a5..776ac6f114f 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -1,6 +1,6 @@ --- title: "Named modules tutorial in C++" -ms.date: 02/12/2025 +ms.date: 02/13/2025 ms.topic: "tutorial" author: "tylermsft" ms.author: "twhitney" @@ -24,7 +24,7 @@ This tutorial requires Visual Studio 2022 17.1.0 or later. ## What are C++ modules -Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and difficult to compose. They may compile differently depending on the order you include them in or on the macros that are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. +Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and may compile differently depending on the order you include them in or on the macros that are or aren't defined. They can slow compilation time because they're reprocessed for each source file that includes them. C++20 introduces *modules* as a modern approach to componentizing C++ programs. @@ -48,7 +48,7 @@ Your code can consume modules in the same project, or any referenced projects, a ## Create the project -As we build a simple project, we look at various aspects of modules. The project implements an API using a module instead of a header file. +The following project implements an API using a module instead of a header file. In Visual Studio 2022 or later, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. @@ -92,11 +92,11 @@ This name is also where the "named" in "named module" comes from. The files that We should talk about the API we'll implement for a moment before going further. It impacts the choices we make next. The API represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes such as `Rectangle`. -To illustrate some features of modules, we factor this API into pieces. One piece is the `Point` API. The other part is `Rectangle`. Imagine that this API will grow into something more complex. The division is useful for separating concerns or easing code maintenance. +To illustrate some features of modules, we factor this API into parts. One part is the `Point` API. The other part is `Rectangle`. Imagine that this API could grow into something more complex. The division is useful for separating concerns or easing code maintenance. So far, we've created the primary module interface that will expose this API. Let's now build the `Point` API. We want it to be part of this module. For reasons of logical organization, and potential build efficiency, we want to make the code for this part of the API a *module partition* file. -Module partitions are useful for dividing the module implementation into manageable pieces. A module partition file is a piece, or component, of a module. What makes it unique is that it can be treated as an individual piece of the module--but only within the module. Module partitions can't be consumed outside of a module. +Module partitions are useful for dividing the module implementation into manageable parts. A module partition file is part of a module. What makes it unique is that it can be treated as an individual parts of the module--but only within the module. Module partitions can't be consumed outside of a module. When you import a partition into the primary module, all its declarations become visible to the primary module regardless of whether they're exported. Partitions can be imported into any partition interface, primary module interface, or module unit that belongs to the named module. @@ -160,7 +160,7 @@ Names are made visible to consumers of a module in several ways: - Put the keyword `export` in front of each type, function, and so on, that you want to export. - If you put `export` in front of a namespace, for example `export namespace N { ... }`, everything defined within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. It's not available because that namespace declaration isn't prefaced by `export`, even though there's another namespace with the same name that is. -- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It is visible to other files that are part of the module, but not to importers of the module. +- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It's visible to other files that are part of the module, but not to importers of the module. - Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file. This section is visible only within the file. - To make an imported module or module partition visible, use `export import`. An example is shown in the next section. @@ -235,7 +235,7 @@ int main() } ``` -The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It should come after any `#include` directives. +The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It comes after any `#include` directives. The app then uses the types and functions from the module to output the area and width of the defined rectangle: @@ -298,7 +298,7 @@ For a more in-depth look at module syntax, see [Modules](modules-cpp.md). Module implementation units belong to a named module. The named module they belong to is indicated by the `module [module-name]` statement in the file. Module implementation units provide implementation details that, for code hygiene or other reasons, you don't want to put in the primary module interface or in a module partition file. -Module implementation units are useful for breaking up a large module into smaller pieces, which can result in faster build times. This technique is covered briefly in the [Best practices](#module-best-practices) section. +Module implementation units are useful for breaking up a large module into smaller parts, which can result in faster build times. This technique is covered briefly in the [Best practices](#module-best-practices) section. Module implementation unit files have a *`.cpp`* extension. The basic outline of a module implementation unit file is: @@ -314,7 +314,7 @@ module [module-name]; // required. Identifies which named module this implementa ### Module partition files -Module partitions provide a way to componentize a module into different pieces, or *partitions*. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. +Module partitions provide a way to componentize a module into different parts, or *partitions*. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. A partition has an interface file, and zero or more implementation files. A module partition shares ownership of all the declarations in the entire module. @@ -357,7 +357,7 @@ A module and the code that imports it must be compiled with the same compiler op - The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named *`BasicPlane.Figures.ixx`*. - The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, *`BasicPlane.Figures-Rectangle.ixx`* -If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler looks for them automatically based on the name of the module. The name of the compiled partition file (ending with an *`.ifc`* extension) is generated from the module name. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler anticipates that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. +If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler looks for them automatically based on the name of the module. The name of the compiled partition file is generated from the module name and ends in *`.ifc`*. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler anticipates that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. You can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. @@ -371,7 +371,7 @@ Module partitions make it easier to logically factor a large module. They can be ## Summary -In this tutorial, you were introduced to the basics of C++20 modules. You've created a primary module interface, defined a module partition, and built a module implementation file. +In this tutorial, you were introduced to the basics of C++20 modules by creating a primary module interface, defined a module partition, and built a module implementation file. ## See also