/sourceDependencies:directives(列出模块和标头单元依赖项)

此命令行选项扫描源文件及其 #include 语句,以生成可列出模块导出和导入情况的 JSON 文件。 生成系统可以使用此信息来确定模块和标头单元的生成顺序。

此选项与 /sourceDependencies 的不同之处包括以下方面:

  • 编译器不生成已编译的输出。 不生成编译的代码、模块或标头单元。 而是扫描文件来获取模块指令。
  • JSON 格式不同于 /sourceDependencies 生成的格式。 /sourceDependencies 选项旨在与其他生成工具(如 CMake)配合使用。
  • 输出 JSON 文件不会列出导入的模块和导入的标头单元(.ifc 文件),因为此选项会扫描项目文件,而不进行编译。 因此,没有要列出的内置模块或标头单元。
  • 仅列出直接导入的模块或标头单元。 它不列出导入的模块或标头单元本身的依赖项。
  • 不列出头文件依赖项。 即,不列出 #include <file>#include "file" 依赖项。
  • /sourceDependencies:directives 应该在生成 .ifc 文件之前使用。
  • /sourceDependencies 使编译器报告已用于特定翻译单元的所有文件,例如 #includes.pch 文件、.ifc 文件等,而 /sourceDependencies:directives [file1] 会扫描指定的源文件并报告所有 importexport 语句。 /sourceDependencies 可以与 /sourceDependencies:directives 配合使用。

语法

/sourceDependencies:directives-
/sourceDependencies:directives filename
/sourceDependencies:directives directory

参数

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

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

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

注解

/sourceDependencies:directives 自 Visual Studio 2019 版本 16.10 起可用。

指定 /MP(使用多个进程生成)编译器选项时,建议将 /sourceDependencies:directives 与目录参数配合使用。 此选项使编译器为每个源文件输出一个单独的 *.module.json 文件。 如果提供单个文件名参数,编译器的两个实例可能会尝试同时打开此输出文件,导致错误。 将 /MP/sourceDependencies:directives- 配合使用以将输出发送到 stdout 可能会导致交错的结果。

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

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

此开关可与 /translateInclude 配合使用。

示例

给定以下示例代码:

//main.cpp:
#include <vector>

import m;
import std.core;

import <utility>;

import "t.h";

int main() {}

以下命令行:

cl /std:c++latest /translateInclude /sourceDependencies:directives output.json main.cpp

生成的 JSON 文件 output.json 类似于:

{
   "Version":"1.1",
   "Data":{
      "Source":"C:\\a\\b\\main.cpp",
      "ProvidedModule":"",
      "ImportedModules":[
         "m",
         "std.core"
      ],
      "ImportedHeaderUnits":[
         "C:\\...\\utility",
         "C:\\a\\b\\t.h"
      ]
   }
}

为简洁起见,上一示例使用 ... 来缩写报告的路径。 报表包含绝对路径。 报告的路径取决于编译器找到依赖项的位置。 如果结果意外,可能需要检查项目的 include 路径设置。

ProvidedModule 列出导出的模块或模块分区名称。

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

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

通常不应自行在 Visual Studio 开发环境中设置此选项。 它由生成系统设置。

另请参阅

/translateInclude
C++ header-units.json 参考
MSVC 编译器选项
MSVC 编译器命令行语法
/scanDependencies(以标准形式列出模块依赖项)
/sourceDependencies(列出所有源级依赖项)