Skip to content

Commit e3f2db1

Browse files
author
Colin Robertson
authored
Merge pull request MicrosoftDocs#2461 from MicrosoftDocs/master637356983350785738
Repo sync for protected CLA branch
2 parents c5db076 + ccf8ab2 commit e3f2db1

19 files changed

Lines changed: 591 additions & 97 deletions

‎docs/build/reference/experimental-module.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,8 @@ cl /EHsc /MD /experimental:module /module:export /module:name ModuleName /module
3939

4040
## See also
4141

42+
[`/headerUnit` (Use header unit IFC)](headerunit.md)\
43+
[`/module:exportHeader` (Create header units)](module-exportheader.md)\
44+
[`/module:reference` (Use named module IFC)](module-reference.md)\
45+
[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)\
4246
[/Zc (Conformance)](zc-conformance.md)

‎docs/build/reference/headerunit.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: "/headerUnit (Use header unit IFC)"
3+
description: "Use the /headerUnit compiler option to specify an existing IFC header unit to import in the current compilation."
4+
ms.date: 09/13/2020
5+
f1_keywords: ["/headerUnit"]
6+
helpviewer_keywords: ["/headerUnit", "Use header unit IFC"]
7+
---
8+
# `/headerUnit` (Use header unit IFC)
9+
10+
Tells the compiler to translate `#include` directives for an importable header-name into an `import header-name;` directive, rather than use textual inclusion.
11+
12+
## Syntax
13+
14+
> **`/headerUnit`** *`header-filename`*=*`ifc-filename`*
15+
16+
### Arguments
17+
18+
*`header-filename`*\
19+
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.
20+
21+
*`ifc-filename`*\
22+
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.
23+
24+
## Remarks
25+
26+
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.
27+
28+
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`*.
29+
30+
### Examples
31+
32+
Given a project that references two header files and their header units, listed in this table:
33+
34+
| Header file | IFC file |
35+
|--|--|
36+
| *`C:\utils\util.h`* | *`C:\util.h.ifc`* |
37+
| *`C:\app\app.h`* | *`C:\app.h.ifc`* |
38+
39+
The compiler options to reference the header units for these particular header files might look like this example:
40+
41+
```CMD
42+
cl ... /experimental:module /translateInclude /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit C:\app\app.h=C:\app.h.ifc
43+
```
44+
45+
### To set this compiler option in the Visual Studio development environment
46+
47+
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).
48+
49+
1. Set the **Configuration** drop-down to **All Configurations**.
50+
51+
1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
52+
53+
1. Modify the **Additional Options** property to add the *`/headerUnit`* options and arguments. Then, choose **OK** or **Apply** to save your changes.
54+
55+
## See also
56+
57+
[`/experimental:module` (Enable module support)](experimental-module.md)\
58+
[`/module:exportHeader` (Create header units)](module-exportheader.md)\
59+
[`/module:reference` (Use named module IFC)](module-reference.md)\
60+
[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)\

‎docs/build/reference/module-exportheader.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "/module:exportHeader (Create header units)"
3+
description: "Use the /module:exportHeader compiler option to create module header units for the header-name or include files specified."
4+
ms.date: 09/13/2020
5+
f1_keywords: ["/module:exportHeader"]
6+
helpviewer_keywords: ["/module:exportHeader", "Create header units"]
7+
---
8+
# `/module:exportHeader` (Create header units)
9+
10+
Tells the compiler to create the header units specified by the input arguments. The compiler generates output in IFC (*`.ifc`*) files.
11+
12+
## Syntax
13+
14+
> **`/module:exportHeader`** *`header-name`* \[...]\
15+
> **`/module:exportHeader`** *`filename`* \[...]
16+
17+
### Arguments
18+
19+
*`header-name`*\
20+
The header file to export. The *`header-name`* argument must take the same form as an argument to an `#include` directive.
21+
22+
*`filename`*\
23+
The relative or absolute path to the header file to create a header unit from.
24+
25+
## Remarks
26+
27+
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.
28+
29+
One **`/module:exportHeader`** compiler option can specify as many header-name arguments as your build requires. You don't need to specify them separately.
30+
31+
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).
32+
33+
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).
34+
35+
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:
36+
37+
```cmd
38+
cl ... /experimental:module /module:exportHeader "<vector>"
39+
```
40+
41+
Building a local project header such as `"utils/util.h"` might look like:
42+
43+
```cmd
44+
cl ... /experimental:module /module:exportHeader """util/util.h"""
45+
```
46+
47+
The quoting rules in other command-line processors may differ.
48+
49+
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.
50+
51+
**`/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.
52+
53+
### Examples
54+
55+
Given headers `"C:\util\util.h"` and `"C:\app\app.h"`, you can export them as *`header-name`* arguments by using this command:
56+
57+
```cmd
58+
cl /IC:\ /experimental:module /module:exportHeader """util/util.h""" """app/app.h""" /FoC:\obj
59+
```
60+
61+
You can export them as *`filename`* arguments by using this command:
62+
63+
```cmd
64+
cl /IC:\ /experimental:module /module:exportHeader C:\util\util.h C:\app\app.h /FoC:\obj
65+
```
66+
67+
### To set this compiler option in the Visual Studio development environment
68+
69+
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).
70+
71+
1. Set the **Configuration** drop-down to **All Configurations**.
72+
73+
1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
74+
75+
1. Modify the **Additional Options** property to add the *`/module:exportHeader`* option and any arguments. Then, choose **OK** or **Apply** to save your changes.
76+
77+
## See also
78+
79+
[`/experimental:module` (Enable module support)](experimental-module.md)\
80+
[`/headerUnit` (Use header unit IFC)](headerunit.md)\
81+
[`/module:reference` (Use named module IFC)](module-reference.md)\
82+
[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)

‎docs/build/reference/module-reference.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: "/module:reference (Use named module IFC)"
3+
description: "Use the /module:reference compiler option to create module header units for the header-name or include files specified."
4+
ms.date: 09/13/2020
5+
f1_keywords: ["/module:reference"]
6+
helpviewer_keywords: ["/module:reference", "Use named module IFC"]
7+
---
8+
# `/module:reference` (Use named module IFC)
9+
10+
Tells the compiler to use an existing IFC (*`.ifc`*) for the current compilation.
11+
12+
## Syntax
13+
14+
> **`/module:reference`** *`module-name=filename`*\
15+
> **`/module:reference`** *`filename`*
16+
17+
### Arguments
18+
19+
*`filename`*\
20+
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.
21+
22+
*`module-name`*\
23+
A valid name of an exported primary module interface unit name or full module partition name.
24+
25+
## Remarks
26+
27+
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.
28+
29+
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.
30+
31+
The *`module-name`* must be a valid primary module interface unit name or full module partition name. Examples of primary module interface names include:
32+
33+
- `M`
34+
- `M.N.O`
35+
- `MyModule`
36+
- `my_module`
37+
38+
Examples of full module partition names include:
39+
40+
- `M:P`
41+
- `M.N.O:P.Q`
42+
- `MyModule:Algorithms`
43+
- `my_module:algorithms`
44+
45+
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:
46+
47+
```cmd
48+
cl ... /experimental:module /module:reference m.ifc /module:reference m=n.ifc
49+
```
50+
51+
In the case above, if the compiler sees `import m;` then *`m.ifc`* doesn't get searched.
52+
53+
### Examples
54+
55+
Given three modules as listed in this table:
56+
57+
| Module | IFC file |
58+
|--|--|
59+
| *`M`* | *`m.ifc`* |
60+
| *`M:Part1`* | *`m-part1.ifc`* |
61+
| *`Core.Networking`* | *`Networking.ifc`* |
62+
63+
The reference options using a *`filename`* argument could look like:
64+
65+
```cmd
66+
cl ... /experimental:module /module:reference m.ifc /module:reference m-part.ifc /module:reference Networking.ifc
67+
```
68+
69+
The reference options using *`module-name=filename`* could look like:
70+
71+
```cmd
72+
cl ... /experimental:module /module:reference m=m.ifc /module:reference M:Part1=m-part.ifc /module:reference Core.Networking=Networking.ifc
73+
```
74+
75+
### To set this compiler option in the Visual Studio development environment
76+
77+
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).
78+
79+
1. Set the **Configuration** drop-down to **All Configurations**.
80+
81+
1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
82+
83+
1. Modify the **Additional Options** property to add the *`/module:reference`* option and its arguments. Then, choose **OK** or **Apply** to save your changes.
84+
85+
## See also
86+
87+
[`/experimental:module` (Enable module support)](experimental-module.md)\
88+
[`/headerUnit` (Use header unit IFC)](headerunit.md)\
89+
[`/module:exportHeader` (Create header units)](module-exportheader.md)\
90+
[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)

‎docs/build/reference/std-specify-language-standard-version.md‎

Lines changed: 50 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,29 @@
11
---
22
title: "/std (Specify Language Standard Version)"
3-
ms.date: "06/04/2020"
4-
f1_keywords: ["/std", "-std", "VC.Project.VCCLCompilerTool.CppLanguageStandard"]
3+
description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler."
4+
ms.date: 09/11/2020
5+
f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c11", "/std:c17", "VC.Project.VCCLCompilerTool.CppLanguageStandard"]
56
ms.assetid: 0acb74ba-1aa8-4c05-b96c-682988dc19bd
67
---
78
# `/std` (Specify Language Standard Version)
89

9-
Enable supported C++ language features from the specified version of the C++ language standard.
10+
Enable supported C and C++ language features from the specified version of the C or C++ language standard.
1011

1112
## Syntax
1213

1314
> **`/std:c++14`**\
1415
> **`/std:c++17`**\
15-
> **`/std:c++latest`**
16+
> **`/std:c++latest`**\
17+
> **`/std:c11`**\
18+
> **`/std:c17`**
1619
1720
## Remarks
1821

19-
The **`/std`** option is available in Visual Studio 2017 and later. It's used to control the version-specific ISO C++ programming language standard features enabled during compilation of your code. This option allows you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard. By default, **`/std:c++14`** is specified, which disables language and standard library features found in later versions of the C++ language standard. Use **`/std:c++17`** to enable C++17 standard-specific features and behavior. To explicitly enable the currently implemented compiler and standard library features proposed for the next draft standard, use **`/std:c++latest`**. All C++20 features require **`/std:c++latest`**; when the implementation is complete, a new **`/std:c++20`** option will be enabled.
22+
The **`/std`** option is available in Visual Studio 2017 and later. It's used to control the version-specific ISO C or C++ programming language standard features enabled during compilation of your code. This option allows you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard.
23+
24+
### C++ standards support
25+
26+
By default, **`/std:c++14`** is specified, which disables language and standard library features found in later versions of the C++ language standard. Use **`/std:c++17`** to enable C++17 standard-specific features and behavior. To explicitly enable the currently implemented compiler and standard library features proposed for the next draft standard, use **`/std:c++latest`**. All C++20 features require **`/std:c++latest`**; when the implementation is complete, a new **`/std:c++20`** option will be enabled.
2027

2128
The default **`/std:c++14`** option enables the set of C++14 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are changed or new in more recent versions of the language standard. It doesn't disable some C++17 features already implemented in previous releases of the MSVC compiler. To avoid breaking changes for users who have already taken dependencies on the features available in or before Visual Studio 2015 Update 2, these features remain enabled when the **`/std:c++14`** option is specified:
2229

@@ -46,13 +53,50 @@ The **`/std:c++14`** and **`/std:c++latest`** options are available beginning in
4653
> [!NOTE]
4754
> Depending on the MSVC compiler version or update level, C++17 features may not be fully implemented or fully conforming when you specify the **`/std:c++17`** options. For an overview of C++ language conformance in Visual C++ by release version, see [Microsoft C++ language conformance table](../../overview/visual-cpp-language-conformance.md).
4855
56+
### C standards support
57+
58+
By default, when code is compiled as C, the MSVC compiler doesn't conform to a particular C standard. It implements ANSI C89 with several Microsoft extensions, some of which are part of ISO C99. Some Microsoft extensions can be disabled by using the [`/Za`](za-ze-disable-language-extensions.md) compiler option, but others remain in effect. It isn't possible to specify strict C89 conformance.
59+
60+
Starting in Visual Studio 2019 version 16.8, you may specify **`/std:c11`** or **`/std:c17`** for code compiled as C. These options specify conformance modes that correspond with ISO C11 and ISO C17. Because the new preprocessor is needed to support these standards, the **`/std:c11`** and **`/std:c17`** compiler options set the [`/Zc:preprocessor`](zc-preprocessor.md) option automatically. If you want to use the traditional (legacy) preprocessor for C11 or C17, you must set the **`/Zc:preprocessor-`** compiler option explicitly. Setting the **`/Zc:preprocessor-`** option may lead to unexpected behavior, and isn't recommended.
61+
62+
> [!NOTE]
63+
> At the time of release, the latest Windows SDK and UCRT libraries do not yet support C11 and C17 code. A pre-release version of the Windows SDK and UCRT is required. For more information and installation instructions, see [Install C11 and C17 support in Visual Studio](../../overview/install-c17-support.md).
64+
65+
When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the required features of C11 and C17. The compiler options enable support for these functionalities:
66+
67+
- **`_Pragma`**
68+
69+
- **`restrict`**
70+
71+
- **`_Noreturn`** and \<stdnoreturn.h>
72+
73+
- **`_Alignas`**, **`_Alignof`** and \<stdalign.h>
74+
75+
- **`_Generic`** and \<tgmath.h>
76+
77+
- **`_Static_assert`**
78+
79+
The IDE uses C settings for IntelliSense and code highlighting when your source files have a *`.c`* file extension, or when you specify the [`/TC`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. Currently, IntelliSense highlighting is only available for keywords, and not the macros introduced by the standard headers.
80+
81+
Since C17 is largely a bug fix release of ISO C11, MSVC support for C11 already includes all the relevant defect reports. At present, there are no differences between the C11 and C17 versions except for the `__STDC_VERSION__` macro. It expands to `201112L` for C11, and `201710L` for C17.
82+
83+
The compiler doesn't support any optional features of ISO C11. Several of these optional features of C11 were required features of C99 that MSVC hasn't implemented for architectural reasons. You can use the feature test macros such as `__STDC_NO_VLA__` to detect compiler support levels for individual features. For more information about C-specific predefined macros, see [Predefined macros](../../preprocessor/predefined-macros.md).
84+
85+
- There's no conforming multithreading, atomic, or complex number support in the Visual Studio 2019 version 16.8 release.
86+
87+
- `aligned_alloc` support is missing, because of the Windows heap implementation. The alternative is to use [`_aligned_malloc`](../../c-runtime-library/reference/aligned-malloc.md).
88+
89+
- DR 400 support is currently unimplemented for `realloc`, because this change would break the ABI.
90+
91+
- Variable length array (VLA) support isn't planned. Variable length arrays are often less efficient than comparable fixed sized arrays. They're also inefficient compared to equivalent heap memory allocations, when safely and securely implemented. VLAs provide attack vectors comparable to `gets()`, which is deprecated and planned for removal.
92+
4993
### To set this compiler option in the Visual Studio development environment
5094

5195
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).
5296

5397
1. Select **Configuration Properties**, **C/C++**, **Language**.
5498

55-
1. In **C++ Language Standard**, choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes.
99+
1. In **C++ Language Standard** (or for C, **C Language Standard**), choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes.
56100

57101
## See also
58102

0 commit comments

Comments
 (0)