通过

/scanDependencies（以标准形式列出模块依赖项）

  • 项目

此编译器选项生成一个 JSON 文件，该文件根据 C++ 标准建议 P1689R5 Format for describing dependencies of source files 列出模块和标头单元依赖项。

语法

/scanDependencies-
/scanDependencies filename
/scanDependencies directory

参数

-
如果提供单个短划线，则编译器会将源依赖项 JSON 发出到 stdout 或发出到重定向了编译器输出的位置。

filename
编译器会将源依赖项输出写入指定文件名，其中可能包括相对路径或绝对路径。 如果文件不存在，则创建该文件。

directory
如果参数是目录，编译器会在指定的目录中生成源依赖项文件。 该目录必须存在，否则会将参数视为 filename。 输出文件名基于输入文件的全名，并使用追加的 .module.json 扩展名。 例如，如果提供给编译器的文件是 main.cpp，则生成的输出文件名为 main.cpp.module.json。

备注

/scanDependencies 编译器选项标识必须编译哪些依赖项、模块和标头单元，然后才能编译使用这些内容的项目。 例如，它列出 import <library>; 或 import "library"; 作为标头单元依赖项，以及 import name; 作为模块依赖项。 目的是通过生成工具（如 CMake）以通用格式提供此信息。 若要报告模块和标头单元依赖项，还必须使用 /std:c++20 或更高版本进行编译。

此命令行选项类似于 /sourceDependencies:directives 和 /sourceDependencies，但在以下方面有所不同：

  • 输出使用 P1689R5 架构，而不是由 /sourceDependencies:directives 生成的特定于 Microsoft 的架构。
  • 与 /sourceDependencies 不同，编译器不生成已编译的输出。 而是扫描文件来获取模块指令。 不生成编译的代码、模块或标头单元。
  • 输出 JSON 文件不会列出导入的模块和导入的标头单元（.ifc 文件），因为此选项仅扫描项目文件。 因此，没有要列出的生成模块或标头单元。
  • 仅列出直接导入的模块或标头单元。 它不列出导入的模块或标头单元本身的依赖项。
  • 除非使用 /translateInclude 选项转换为标头单元，否则以文本方式包含的头文件（例如 #include <file> 或 #include "file"）不会列为依赖项。
  • /scanDependencies 应该在生成 .ifc 文件之前使用。

/scanDependencies 自 Visual Studio 2022 版本 17.2 起可用。 默认情况下不启用此功能。

指定 /MP（使用多个进程生成）编译器选项时，建议将 /scanDependencies 与目录参数配合使用。 如果提供单个文件名参数，编译器的两个实例可能会尝试同时打开此输出文件，导致错误。 将 /MP 与 /scanDependencies- 配合使用以将输出发送到 stdout 可能会导致交错的结果。

发生非致命编译器错误时，依赖项信息仍会写入输出文件。

所有文件路径都在输出中显示为绝对路径。

有关输出 JSON 文件中使用的格式和架构的详细信息，请参阅 P1689R5 第 6 部分。

示例

请考虑以下示例代码：

//app.cpp:
#include <vector>

import other.module;
import std.core;

import "t.h";

import <iostream>;

int main() {}

可使用此命令行报告 app.cpp 中的依赖项：

cl /std:c++latest /scanDependencies output.json app.cpp

编译器会生成内容如下所示的 JSON 文件 output.json：

{
    "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
                }
            ]
        }
    ]
}

我们已使用 ... 缩写报告的路径。 报表包含绝对路径。 报告的路径取决于编译器找到依赖项的位置。 如果结果在意料之外，可能需要检查项目的包含路径设置。

输出中未列出任何 .ifc 文件，因为它们未生成。 与 /sourceDependencies 不同，编译器在指定 /scanDependencies 时不会生成已编译的输出，因此不会生成已编译的模块或标头单元以供导入。

在 Visual Studio 中设置此编译器选项

通常不应在 Visual Studio 开发环境中设置 /scanDependencies 选项。 设置此选项时，编译器不会生成对象文件，这会使链接步骤失败并报告错误。

  1. 打开项目的“属性页” 对话框。 有关详细信息，请参阅设置编译器和生成属性。

  2. 选择“配置属性”>“C/C++”>“命令行”属性页。

  3. 修改“其他选项”属性以添加 /scanDependencies- 或 /scanDependencies "pathname"，其中 "pathname" 是指用于输出的目录。

  4. 选择“确定”以保存更改 。

若要报告模块和标头单元依赖项，还必须将“配置属性”>“常规”>“C++ 语言标准”属性设置为 ISO C++20 Standard 或更高版本。

以编程方式设置此编译器选项

另请参阅

MSVC 编译器选项
MSVC 编译器命令行语法
/sourceDependencies:directives
/sourceDependencies
/std（指定语言标准版本）
/translateInclude