Merge pull request #3141 from corob-msft/docs/corob/16-8-modules

ttorble · web-flow · commit 2ca63d4479e0 · 2020-09-14T08:22:11.000+01:00
VS 16.8 Add commands for modules
diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md
@@ -39,4 +39,8 @@ cl /EHsc /MD /experimental:module /module:export /module:name ModuleName /module
 
 ## See also
 
+[`/headerUnit` (Use header unit IFC)](headerunit.md)\
+[`/module:exportHeader` (Create header units)](module-exportheader.md)\
+[`/module:reference` (Use named module IFC)](module-reference.md)\
+[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)\
 [/Zc (Conformance)](zc-conformance.md)
diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md
@@ -0,0 +1,60 @@
+---
+title: "/headerUnit (Use header unit IFC)"
+description: "Use the /headerUnit compiler option to specify an existing IFC header unit to import in the current compilation."
+ms.date: 09/13/2020
+f1_keywords: ["/headerUnit"]
+helpviewer_keywords: ["/headerUnit", "Use header unit IFC"]
+---
+# `/headerUnit` (Use header unit IFC)
+
+Tells the compiler to translate `#include` directives for an importable header-name into an `import header-name;` directive, rather than use textual inclusion.
+
+## Syntax
+
+> **`/headerUnit`** *`header-filename`*=*`ifc-filename`*
+
+### Arguments
+
+*`header-filename`*\
+The name of a file that the compiler resolves a `header-name` to. During `import header-name ;` the compiler resolves `header-name` to some file on disk. Use *`header-filename`* to specify that file. Once matched, the compiler opens the corresponding IFC named by *`ifc-filename`* for import.
+
+*`ifc-filename`*\
+The name of a file that contains *IFC data*, prebuilt module information. To import more than one header unit, include a separate **`/headerUnit`** option for each file.
+
+## Remarks
+
+The **`/headerUnit`** compiler option requires you enable experimental modules support by use of the [`/experimental:module`](experimental-module.md) compiler option, along with the [/std:c++latest](std-specify-language-standard-version.md) option. This option is available starting in Visual Studio 2019 version 16.8.
+
+The compiler can't map a single *`header-name`* to multiple IFC files. While mapping multiple *`header-name`* arguments to a single IFC is possible, we don't recommend it. The contents of the IFC get imported as if it was only the header specified by *`header-name`*.
+
+### Examples
+
+Given a project that references two header files and their header units, listed in this table:
+
+| Header file | IFC file |
+|--|--|
+| *`C:\utils\util.h`* | *`C:\util.h.ifc`* |
+| *`C:\app\app.h`* | *`C:\app.h.ifc`* |
+
+The compiler options to reference the header units for these particular header files might look like this example:
+
+```CMD
+cl ... /experimental:module /translateInclude /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit C:\app\app.h=C:\app.h.ifc
+```
+
+### 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++** > **Command Line** property page.
+
+1. Modify the **Additional Options** property to add the *`/headerUnit`* options and arguments. Then, choose **OK** or **Apply** to save your changes.
+
+## See also
+
+[`/experimental:module` (Enable module support)](experimental-module.md)\
+[`/module:exportHeader` (Create header units)](module-exportheader.md)\
+[`/module:reference` (Use named module IFC)](module-reference.md)\
+[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)\
diff --git a/docs/build/reference/module-exportheader.md b/docs/build/reference/module-exportheader.md
@@ -0,0 +1,82 @@
+---
+title: "/module:exportHeader (Create header units)"
+description: "Use the /module:exportHeader compiler option to create module header units for the header-name or include files specified."
+ms.date: 09/13/2020
+f1_keywords: ["/module:exportHeader"]
+helpviewer_keywords: ["/module:exportHeader", "Create header units"]
+---
+# `/module:exportHeader` (Create header units)
+
+Tells the compiler to create the header units specified by the input arguments. The compiler generates output in IFC (*`.ifc`*) files.
+
+## Syntax
+
+> **`/module:exportHeader`** *`header-name`* \[...]\
+> **`/module:exportHeader`** *`filename`* \[...]
+
+### Arguments
+
+*`header-name`*\
+The header file to export. The *`header-name`* argument must take the same form as an argument to an `#include` directive.
+
+*`filename`*\
+The relative or absolute path to the header file to create a header unit from.
+
+## Remarks
+
+The **`/module:exportHeader`** compiler option requires you enable experimental modules support by use of the [`/experimental:module`](experimental-module.md) compiler option, along with the [/std:c++latest](std-specify-language-standard-version.md) option. This option is available starting in Visual Studio 2019 version 16.8.
+
+One **`/module:exportHeader`** compiler option can specify as many header-name arguments as your build requires. You don't need to specify them separately.
+
+By default, the compiler doesn't produce an object file when a header unit is compiled. To produce an object file, specify the **`/Fo`** compiler option. For more information, see [`/Fo` (Object File Name)](fo-object-file-name.md).
+
+The compiler resolves a *`header-name`* based on the include directory search order, including any you specify. For more information, see [`/I` (Additional include directories)](i-additional-include-directories.md).
+
+The argument *`header-name`* must be specified the same way it would appear in source. The argument is sensitive to quoting rules and to `<` and `>` operators on the command line. The properly escaped command to build a header unit such as `<vector>` using the VS2019 command prompt might look like:
+
+```cmd
+cl ... /experimental:module /module:exportHeader "<vector>"
+```
+
+Building a local project header such as `"utils/util.h"` might look like:
+
+```cmd
+cl ... /experimental:module /module:exportHeader """util/util.h"""
+```
+
+The quoting rules in other command-line processors may differ.
+
+When using the *`header-name`* form of **`/module:exportHeader`**, you may find it's helpful to use the complementary option **`/module:showResolvedHeader`**. The **`/module:showResolvedHeader`** option prints an absolute path to the file the *`header-name`* argument resolves to.
+
+**`/module:exportHeader`** can handle multiple inputs at once even under **`/MP`**. We recommended you use **`/module:output <directory>`** to create a separate IFC file for each compilation.
+
+### Examples
+
+Given headers `"C:\util\util.h"` and `"C:\app\app.h"`, you can export them as *`header-name`* arguments by using this command:
+
+```cmd
+cl /IC:\ /experimental:module /module:exportHeader """util/util.h""" """app/app.h""" /FoC:\obj
+```
+
+You can export them as *`filename`* arguments by using this command:
+
+```cmd
+cl /IC:\ /experimental:module /module:exportHeader C:\util\util.h C:\app\app.h /FoC:\obj
+```
+
+### 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++** > **Command Line** property page.
+
+1. Modify the **Additional Options** property to add the *`/module:exportHeader`* option and any arguments. Then, choose **OK** or **Apply** to save your changes.
+
+## See also
+
+[`/experimental:module` (Enable module support)](experimental-module.md)\
+[`/headerUnit` (Use header unit IFC)](headerunit.md)\
+[`/module:reference` (Use named module IFC)](module-reference.md)\
+[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)
diff --git a/docs/build/reference/module-reference.md b/docs/build/reference/module-reference.md
@@ -0,0 +1,90 @@
+---
+title: "/module:reference (Use named module IFC)"
+description: "Use the /module:reference compiler option to create module header units for the header-name or include files specified."
+ms.date: 09/13/2020
+f1_keywords: ["/module:reference"]
+helpviewer_keywords: ["/module:reference", "Use named module IFC"]
+---
+# `/module:reference` (Use named module IFC)
+
+Tells the compiler to use an existing IFC (*`.ifc`*) for the current compilation.
+
+## Syntax
+
+> **`/module:reference`** *`module-name=filename`*\
+> **`/module:reference`** *`filename`*
+
+### Arguments
+
+*`filename`*\
+The name of a file that contains *IFC data*, prebuilt module information. To import more than one module, include a separate **`/module:reference`** option for each file.
+
+*`module-name`*\
+A valid name of an exported primary module interface unit name or full module partition name.
+
+## Remarks
+
+The **`/module:reference`** compiler option requires you enable experimental modules support by use of the [`/experimental:module`](experimental-module.md) compiler option, along with the [/std:c++latest](std-specify-language-standard-version.md) option. This option is available starting in Visual Studio 2019 version 16.8.
+
+If the **`/module:reference`** argument is a *`filename`* without a *`module-name`*, the file gets opened at runtime to verify the *`filename`* argument names a specific import. It can result in slower runtime performance in scenarios that have many **`/module:reference`** arguments.
+
+The *`module-name`* must be a valid primary module interface unit name or full module partition name. Examples of primary module interface names include:
+
+- `M`
+- `M.N.O`
+- `MyModule`
+- `my_module`
+
+Examples of full module partition names include:
+
+- `M:P`
+- `M.N.O:P.Q`
+- `MyModule:Algorithms`
+- `my_module:algorithms`
+
+If a module reference is created using a *`module-name`*, other modules on the command line don't get searched if the compiler encounters an import of that name. For example, given this command line:
+
+```cmd
+cl ... /experimental:module /module:reference m.ifc /module:reference m=n.ifc
+```
+
+In the case above, if the compiler sees `import m;` then *`m.ifc`* doesn't get searched.
+
+### Examples
+
+Given three modules as listed in this table:
+
+| Module | IFC file |
+|--|--|
+| *`M`* | *`m.ifc`* |
+| *`M:Part1`* | *`m-part1.ifc`* |
+| *`Core.Networking`* | *`Networking.ifc`* |
+
+The reference options using a *`filename`* argument could look like:
+
+```cmd
+cl ... /experimental:module /module:reference m.ifc /module:reference m-part.ifc /module:reference Networking.ifc
+```
+
+The reference options using *`module-name=filename`* could look like:
+
+```cmd
+cl ... /experimental:module /module:reference m=m.ifc /module:reference M:Part1=m-part.ifc /module:reference Core.Networking=Networking.ifc
+```
+
+### 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++** > **Command Line** property page.
+
+1. Modify the **Additional Options** property to add the *`/module:reference`* option and its arguments. Then, choose **OK** or **Apply** to save your changes.
+
+## See also
+
+[`/experimental:module` (Enable module support)](experimental-module.md)\
+[`/headerUnit` (Use header unit IFC)](headerunit.md)\
+[`/module:exportHeader` (Create header units)](module-exportheader.md)\
+[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)
diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md
@@ -0,0 +1,73 @@
+---
+title: "/translateInclude (Translate include directives into import directives)"
+description: "Use the /translateInclude compiler option to translate #include directives for an importable header-name into an import header-name directive."
+ms.date: 09/13/2020
+f1_keywords: ["/translateInclude"]
+helpviewer_keywords: ["/translateInclude", "Translate include directives into import directives"]
+---
+# `/translateInclude` (Translate include directives into import directives)
+
+Tells the compiler to translate `#include` directives for an importable header-name into an `import header-name;` directive, rather than use textual inclusion.
+
+## Syntax
+
+> **`/translateInclude`**
+
+## Remarks
+
+The **`/translateInclude`** compiler option requires you enable experimental modules support by use of the [`/experimental:module`](experimental-module.md) compiler option, along with the [/std:c++latest](std-specify-language-standard-version.md) option. This option is available starting in Visual Studio 2019 version 16.8.
+
+The **`/translateInclude`** option effectively makes the following transformation, where the example `<vector>` is an importable header unit:
+
+```cpp
+#include <vector>
+```
+
+The compiler replaces this directive with:
+
+```cpp
+import <vector> ;
+```
+
+In MSVC an importable header unit is one named by a **`/headerUnit`** reference. For more information, see [`/headerUnit` (Use header unit IFC)](headerunit.md).
+
+### Examples
+
+Given a project that references two header files and their header units, listed in this table:
+
+| Header file | IFC file |
+|--|--|
+| *`C:\utils\util.h`* | *`C:\util.h.ifc`* |
+| *`C:\app\app.h`* | *`C:\app.h.ifc`* |
+
+And a source *`.cpp`* file that includes the headers,
+
+```cpp
+#include "utils/util.h"
+#include "app/app.h"
+
+int main() { }
+```
+
+The **`/translateInclude`** option allows the compiler to import the header units instead of compile the headers again. Here's an example command line that translates the include directives for *`util.h`* and *`app.h`* into imports of the header units instead:
+
+```CMD
+cl /IC:\ /experimental:module /translateInclude /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit C:\app\app.h=C:\app.h.ifc
+```
+
+### 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++** > **Command Line** property page.
+
+1. Modify the **Additional Options** property to add the *`/translateInclude`* option. Then, choose **OK** or **Apply** to save your changes.
+
+## See also
+
+[`/experimental:module` (Enable module support)](experimental-module.md)\
+[`/headerUnit` (Use header unit IFC)](headerunit.md).\
+[`/module:exportHeader` (Create header units)](module-exportheader.md)\
+[`/module:reference` (Use named module IFC)](module-reference.md)
diff --git a/docs/build/toc.yml b/docs/build/toc.yml
@@ -583,6 +583,8 @@
                   href: ../build/reference/gz-enable-stack-frame-run-time-error-checking.md
                 - name: /H (Restrict length of external names)
                   href: ../build/reference/h-restrict-length-of-external-names.md
+                - name: /headerUnit (Use header unit IFC)
+                  href: ../build/reference/headerunit.md
                 - name: /HELP (Compiler command-line help)
                   href: ../build/reference/help-compiler-command-line-help.md
                 - name: /homeparams (Copy register parameters to stack)
@@ -603,6 +605,10 @@
                   href: ../build/reference/ln-create-msil-module.md
                 - name: /MD, /MT, /LD (Use Run-time library)
                   href: ../build/reference/md-mt-ld-use-run-time-library.md
+                - name: /module:exportHeader (Create header units)
+                  href: ../build/reference/module-exportheader.md
+                - name: /module:reference (Use named module IFC)
+                  href: ../build/reference/module-reference.md
                 - name: /MP (Build with multiple processes)
                   href: ../build/reference/mp-build-with-multiple-processes.md
                 - name: /nologo (Suppress startup banner) (C/C++)
@@ -675,6 +681,8 @@
                   href: ../build/reference/std-specify-language-standard-version.md
                 - name: /Tc, /Tp, /TC, /TP (Specify source file type)
                   href: ../build/reference/tc-tp-tc-tp-specify-source-file-type.md
+                - name: /translateInclude (Translate include directives into import directives)
+                  href: ../build/reference/translateinclude.md
                 - name: /U, /u (Undefine symbols)
                   href: ../build/reference/u-u-undefine-symbols.md
                 - name: /utf-8 (Set source and executable character sets to UTF-8)
