Edit

/scanDependencies (List module dependencies in standard form)

  • Article

This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal P1689R5 Format for describing dependencies of source files.

Syntax

/scanDependencies-
/scanDependencies filename
/scanDependencies directory

Arguments

-
If the single dash is provided, then the compiler emits the source dependencies JSON to stdout, or to where compiler output is redirected.

filename
The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist.

directory
If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a filename. The output file name is based on the full name of the input file, with an appended .module.json extension. For example, if the file provided to the compiler is main.cpp, the generated output filename is main.cpp.module.json.

Remarks

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 or later.

This command-line option is similar to /sourceDependencies:directives and /sourceDependencies, but differs in the following ways:

  • The output uses the P1689R5 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 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) 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.

All file paths appear as absolute paths in the output.

For details on the format and schema used in the output JSON file, see P1689R5 section 6.

Examples

Consider the following sample code:

//app.cpp:
#include <vector>

import other.module;
import std.core;

import "t.h";

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

The compiler produces a JSON file, output.json, with content similar to:

{
    "version": 1,
    "revision": 0,
    "rules": [
        {
            "primary-output": "app.obj",
            "outputs": [
                "C:\\Users\\username\\source\\repos\\app\\app"
            ],
            "requires": [
                {
                    "logical-name": "other.module"
                },
                {
                    "logical-name": "std.core"
                },
                {
                    "logical-name": "t.h",
                    "source-path": "C:\\Users\\username\\source\\repos\\app\\app\\t.h",
                    "lookup-method": "include-quote",
                    "unique-on-source-path": true
                },
                {
                    "logical-name": "iostream",
                    "source-path": "C:\\Program Files\\...\\include\\iostream",
                    "lookup-method": "include-angle",
                    "unique-on-source-path": true
                }
            ]
        }
    ]
}

We've used ... to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings.

No .ifc files are listed in the output because they weren't built. Unlike /sourceDependencies, the compiler doesn't produce compiled output when /scanDependencies is specified, so no compiled modules or header units are produced to import.

To set this compiler option in Visual Studio

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 more information, see Set compiler and build properties.

  2. Select the Configuration Properties > C/C++ > Command Line property page.

  3. Modify the Additional Options property to add /scanDependencies- or /scanDependencies "pathname", where "pathname" refers to a directory for output.

  4. 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 also

MSVC compiler options
MSVC compiler command-line syntax
/sourceDependencies:directives
/sourceDependencies
/std (Specify language standard version)
/translateInclude