Merge pull request #4533 from corob-msft/docs/corob/vcsig-scandependencies-fix

Update /scanDependencies to add /std requirement for modules

Author: v-ccolin

docs/build/reference/scandependencies.md

@@ -1,7 +1,7 @@
 ---
 title: "/scanDependencies (List module and header unit dependencies per Standard)"
 description: "Reference guide to the /scanDependencies compiler option in Microsoft C++."
-ms.date: 05/19/2022
+ms.date: 09/21/2022
 author: "corob-msft"
 ms.author: "corob"
 f1_keywords: ["/scanDependencies"]
@@ -11,17 +11,6 @@ helpviewer_keywords: ["/scanDependencies compiler option", "/scanDependencies"]
 
 This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R4 Format for describing dependencies of source files`](https://wg21.link/P1689r4).
 
-The **`/scanDependencies`** compiler option identifies which modules and header units need to be compiled before you can compile the project that uses them. For instance, it lists `import <library>;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake.
-
-This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways:
-
-- The output uses the [`P1689R4`](https://wg21.link/P1689r4) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**.
-- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced.
-- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list.
-- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves.
-- Textually included header files such as `#include <file>` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option.
-- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built.
-
 ## Syntax
 
 > **`/scanDependencies-`**\
@@ -41,9 +30,20 @@ If the argument is a directory, the compiler generates source dependency files i
 
 ## Remarks
 
-**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2 preview 1. It's not enabled by default.
+The **`/scanDependencies`** compiler option identifies which dependencies, modules, and header units must be compiled before you can compile the project that uses them. For instance, it lists `import <library>;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake. To report module and header unit dependencies, you must also compile by using [`/std:c++20`](std-specify-language-standard-version.md) or later.
+
+This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways:
 
-When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results.
+- The output uses the [`P1689R4`](https://wg21.link/P1689r4) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**.
+- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced.
+- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list.
+- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves.
+- Textually included header files such as `#include <file>` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option.
+- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built.
+
+**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2. It's not enabled by default.
+
+When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results.
 
 When a non-fatal compiler error occurs, the dependency information still gets written to the output file.
 
@@ -53,7 +53,7 @@ For details on the format and schema used in the output JSON file, see [`P1689R4
 
 ### Examples
 
-Given the following sample code:
+Consider the following sample code:
 
 ```cpp
 //app.cpp:
@@ -69,9 +69,11 @@ import <iostream>;
 int main() {}
 ```
 
+You can use this command line to report dependencies in *`app.cpp`*:
+
 > `cl /std:c++latest /scanDependencies output.json app.cpp`
 
-This command line produces a JSON file *`output.json`* with content similar to:
+The compiler produces a JSON file, *`output.json`*, with content similar to:
 
 ```JSON
 {
@@ -114,16 +116,18 @@ No *`.ifc`* files are listed in the output because they weren't built. Unlike **
 
 ## To set this compiler option in Visual Studio
 
-You normally shouldn't set this option yourself in the Visual Studio development environment. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error.
+You normally shouldn't set the **`/scanDependencies`** option in the Visual Studio development environment. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error.
 
-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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md).
 
 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
 
-1. Modify the **Additional Options** property to add **`/scanDependencies -`** or **`/scanDependencies "pathname"`**, where `pathname` refers to a directory for output.
+1. Modify the **Additional Options** property to add *`/scanDependencies-`* or *`/scanDependencies "pathname"`*, where *`"pathname"`* refers to a directory for output.
 
 1. Choose **OK** to save your changes.
 
+To report module and header unit dependencies, you must also set the **Configuration Properties** > **General** > **C++ Language Standard** property to **ISO C++20 Standard** or later.
+
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCLinkerTool.AdditionalOptions%2A>.
@@ -134,4 +138,5 @@ You normally shouldn't set this option yourself in the Visual Studio development
 [MSVC compiler command-line syntax](compiler-command-line-syntax.md)\
 [`/sourceDependencies:directives`](sourcedependencies-directives.md)\
 [`/sourceDependencies`](sourcedependencies.md)\
+[`/std` (Specify language standard version)](std-specify-language-standard-version.md)\
 [`/translateInclude`](translateinclude.md)