llvm-cov - 生成代码覆盖率信息¶
概要¶
llvm-cov 命令 [参数…]
描述¶
llvm-cov 工具显示已插入以发出配置文件数据的程序的代码覆盖率信息。它可用于处理 gcov 样式的覆盖率或 clang 基于插桩的分析。
如果程序使用 gcov 作为基本名称调用，则其行为将如同调用了 llvm-cov gcov 命令一样。否则，应提供一个命令。
命令¶
GCOV 命令¶
概要¶
llvm-cov gcov [选项] 源文件
描述¶
llvm-cov gcov 工具读取代码覆盖率数据文件并显示指定源文件的覆盖率信息。它与版本 4.2 的 GCC 中的 gcov 工具兼容，也可能与 gcov 的某些更高版本兼容。
要使用 llvm-cov gcov，必须首先构建应用程序的已插入版本，该版本在运行时收集覆盖率数据。使用 -fprofile-arcs 和 -ftest-coverage 选项进行编译以添加插桩。（或者，您可以使用 --coverage 选项，其中包含这两个其他选项。）
在编译已插入代码时，将为每个目标文件生成一个 .gcno 数据文件。这些 .gcno 文件包含覆盖率数据的一半。数据的另一半来自 .gcda 文件，这些文件是在运行已插入程序时生成的，每个目标文件都有一个单独的 .gcda 文件。每次运行程序时，执行计数都会累加到任何现有的 .gcda 文件中，因此，如果您不希望包含其内容，请确保删除所有旧文件。
.gcda 文件默认写入与目标文件相同的目录中，但您可以通过设置 GCOV_PREFIX 和 GCOV_PREFIX_STRIP 环境变量来覆盖此行为。GCOV_PREFIX_STRIP 变量指定要从目标文件目录的绝对路径开头删除的目录组件数量。删除这些目录后，将添加来自 GCOV_PREFIX 变量的前缀。这些环境变量允许您在原始目标文件目录不可访问的机器上运行已插入程序，但随后您需要将 .gcda 文件复制回 llvm-cov gcov 预期找到它们的目 标文件目录。
生成覆盖率数据文件后，对要检查覆盖率结果的每个主源文件运行 llvm-cov gcov。这应该在您之前运行编译器的同一目录中运行。指定源文件的结果将写入一个以 .gcov 后缀命名的文件。还会为主源文件包含的每个文件创建一个单独的输出文件，并在其文件名后也添加 .gcov 后缀。
.gcov 输出文件的基本内容是源文件的副本，在每一行之前都添加了执行计数和行号。如果一行不包含任何可执行代码，则执行计数显示为 -。如果一行包含代码，但该代码从未执行过，则计数显示为 #####。
选项¶
- -a, --all-blocks¶
显示所有基本块。如果一行源代码有多个块，则此选项会导致 llvm-cov 显示每个块的计数，而不仅仅是整行的单个计数。
- -b, --branch-probabilities¶
显示条件分支概率和分支信息的摘要。
- -c, --branch-counts¶
显示分支计数而不是概率（需要 -b）。
- -m, --demangled-names¶
解混淆函数名称。
- -f, --function-summaries¶
显示每个函数的覆盖率摘要，而不仅仅是整个源文件的单个摘要。
- --help¶
显示可用选项（更多选项请使用 –help-hidden）。
- -l, --long-file-names¶
对于主源文件包含的文件的覆盖率输出，在输出文件名之前添加主文件名，后跟
##作为前缀。这可以与 –preserve-paths 选项结合使用，以便为主文件和包含文件都使用完整路径。
- -n, --no-output¶
不输出任何
.gcov文件。摘要信息仍将显示。
- -o <DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>¶
在 DIR 中或基于 FILE 的路径中查找对象。如果您指定特定的目标文件，则覆盖率数据文件预计具有相同的基本名称，以及
.gcno和.gcda扩展名。如果您指定一个目录，则预计这些文件位于该目录中，并且与源文件具有相同的基本名称。
- -p, --preserve-paths¶
在命名覆盖率输出文件时保留路径组件。除了源文件名外，还包括该文件路径中的目录。目录由
#字符分隔，其中删除了.目录，并将..目录替换为^字符。与 –long-file-names 选项一起使用时，这适用于主文件名和包含文件名。
- -r¶
仅转储具有相对路径或具有
-s指定的前缀的绝对路径的文件。
- -s <字符串>¶
要省略的源前缀。
- -t, --stdout¶
打印到标准输出，而不是生成
.gcov文件。
- -u, --unconditional-branches¶
在 –branch-probabilities 选项的输出中包含无条件分支。
- -version¶
显示 llvm-cov 的版本。
- -x, --hash-filenames¶
在命名覆盖率输出文件时使用文件名的 md5 哈希值。源文件名将后缀为
##后跟为其计算的 MD5 哈希值。
退出状态¶
llvm-cov gcov 如果无法读取输入文件，则返回 1。否则，它将以零退出。
显示命令¶
概要¶
llvm-cov show [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…
描述¶
llvm-cov show 命令使用概要数据 PROFILE 显示二进制文件 BIN… 的逐行覆盖率。可以选择将其过滤为仅显示 SOURCE… 中列出的文件的覆盖率。
BIN 可以是可执行文件、目标文件、动态库或存档（瘦或其他）。
要使用 llvm-cov show，您需要一个使用检测来发出概要和覆盖率数据的编译程序。要使用 clang 构建这样的程序，请使用 -fprofile-instr-generate 和 -fcoverage-mapping 标记。如果与 clang 驱动程序链接，请将 -fprofile-instr-generate 传递到链接阶段以确保链接必要的运行时库。
覆盖率信息存储在构建的可执行文件或库本身中，这就是您应该作为 BIN 参数传递给 llvm-cov show 的内容。概要数据是通过正常运行此检测程序生成的。当程序退出时，它将写出一个原始概要文件，通常称为 default.profraw，可以使用 llvm-profdata merge 工具将其转换为适合 PROFILE 参数的格式。
选项¶
- -show-branches=<VIEW>¶
以计数或百分比的形式显示分支条件的覆盖率。支持的视图为：“count”、“percent”。
- -show-mcdc¶
显示每个适用的布尔表达式的修改条件/决策覆盖率 (MC/DC)。
- -show-line-counts¶
显示每行的执行次数。默认为 true，除非使用了其他
-show选项。
- -show-expansions¶
在源文件的显示中内联扩展包含，例如预处理器宏或文本包含。默认为 false。
- -show-instantiations¶
对于多次实例化的源区域，例如
C++中的模板，除了组合摘要外，还分别显示每个实例化。默认为 true。
- -show-regions¶
通过显示一个指向区域开始处的字符的插入符号来显示每个区域的执行次数。默认为 false。
- -show-line-counts-or-regions¶
如果一行上只有一个区域，则显示每行的执行次数，但如果一行上有多个区域，则显示各个区域。默认为 false。
- -show-directory-coverage¶
在每个包含至少一个具有顶级索引显示聚合的源文件的目录中生成索引文件。默认为 false。
- -use-color¶
启用或禁用彩色输出。默认情况下，这是自动检测的。
- -arch=[*NAMES*]¶
指定架构列表，以便列表中的第 N 个条目对应于指定的第 N 个二进制文件。如果覆盖的对象是通用二进制文件，则指定要使用的架构。指定通用二进制文件中未包含的架构或使用与非通用二进制文件不匹配的架构都是错误的。
- -name=<NAME>¶
仅显示具有给定名称的函数的代码覆盖率。
- -name-allowlist=<FILE>¶
仅显示给定文件中列出的函数的代码覆盖率。文件中的每一行都应以 allowlist_fun: 开头，后跟要接受的函数的名称。此名称可以是通配符表达式。
- -name-regex=<PATTERN>¶
仅显示与给定正则表达式匹配的函数的代码覆盖率。
- -ignore-filename-regex=<PATTERN>¶
跳过文件路径与给定正则表达式匹配的源代码文件。
- -format=<FORMAT>¶
使用指定的输出格式。支持的格式为：“text”、“html”。
- -tab-size=<TABSIZE>¶
在准备报表时用 <TABSIZE> 个空格替换制表符。目前，这仅适用于 html 格式。
- -output-dir=PATH¶
指定一个目录以将覆盖率报表写入其中。如果目录不存在，则创建它。在函数视图模式下使用（即当 -name 或 -name-regex 用于选择特定函数时），报表将写入 PATH/functions.EXTENSION。在文件视图模式下，每个文件的报表都将写入 PATH/REL_PATH_TO_FILE.EXTENSION。
- -Xdemangler=<TOOL>|<TOOL-OPTION>¶
指定一个符号反汇编器。这可以用来使报表更易于阅读。此选项可以多次指定以向反汇编器提供参数（例如 -Xdemangler c++filt -Xdemangler -n 用于 C++）。反汇编器预计会从 stdin 读取一个以换行符分隔的符号列表，并向 stdout 写入一个相同长度的以换行符分隔的列表。
- -num-threads=N, -j=N¶
使用 N 个线程写入文件报表（仅在指定 -output-dir 时适用）。当 N=0 时，llvm-cov 会自动检测要使用的适当线程数。这是默认值。
- -compilation-dir=<dir>¶
用作相对覆盖率映射路径的基础的目录。仅当二进制文件已使用 -fcoverage-prefix-map -fcoverage-compilation-dir 或 -ffile-compilation-dir 中的一个进行编译时适用。
- -line-coverage-gt=<N>¶
仅显示行覆盖率大于给定阈值的函数的代码覆盖率。
- -line-coverage-lt=<N>¶
仅显示行覆盖率小于给定阈值的函数的代码覆盖率。
- -region-coverage-gt=<N>¶
仅显示区域覆盖率大于给定阈值的函数的代码覆盖率。
- -region-coverage-lt=<N>¶
仅显示区域覆盖率小于给定阈值的函数的代码覆盖率。
- -path-equivalence=<from>,<to>¶
将覆盖率数据中的路径映射到本地源文件路径。这允许您在一台机器上生成覆盖率数据，然后在另一台机器上使用 llvm-cov，而这台机器上的文件位于不同的路径上。可以传递多个 -path-equivalence 参数来指定不同的映射。每个参数都包含一个源路径 <from> 及其对应的本地路径 <to>。映射将按照指定的顺序应用。如果多个映射可以应用于单个路径，则使用遇到的第一个映射。
- -coverage-watermark=<high>,<low>¶
为 html 格式输出中的覆盖率设置高低水位线。这允许您根据需要设置覆盖率的高低水位线，覆盖率 >= high 时显示绿色，覆盖率 < low 时显示红色，其他情况显示黄色。high 和 low 都应介于 0-100 之间，且 high > low。
- -debuginfod¶
使用 debuginfod 来查找配置文件中存在但在命令行上给定的任何对象中不存在的二进制 ID 的覆盖率映射。如果编译了 debuginfod 并在 DEBUGINFOD_URLS 环境变量中进行了配置，则默认为 true。
- -debug-file-directory=<dir>¶
提供本地目录以搜索与配置文件中二进制 ID 对应的对象（与 debuginfod 一样）。默认为系统构建 ID 目录。
- -check-binary-ids¶
如果在配置文件中找不到二进制 ID 对应的对象文件，无论是在命令行上还是通过二进制 ID 查找，都将失败。
REPORT 命令¶
概要¶
llvm-cov report [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…
描述¶
llvm-cov report 命令显示使用配置文件数据 PROFILE 的二进制文件 BIN… 的覆盖率摘要。可以选择将其过滤为仅显示列出在 SOURCE… 中的文件的覆盖率。
BIN 可以是可执行文件、目标文件、动态库或存档（瘦或其他）。
如果没有提供源文件，则会为覆盖率数据中的每个文件打印一条摘要行。如果提供了任何文件，则如果启用了 -show-functions 选项，则可以为列出文件中每个函数显示摘要。
有关编译用于覆盖率的程序和生成配置文件数据的更多信息，请参阅 SHOW 命令。
选项¶
- -use-color[=VALUE]¶
启用或禁用彩色输出。默认情况下，这是自动检测的。
- -arch=<name>¶
如果覆盖的二进制文件是通用二进制文件，请选择要使用的体系结构。指定通用二进制文件中未包含的体系结构或使用与非通用二进制文件不匹配的体系结构都是错误的。
- -show-region-summary¶
显示所有区域的统计信息。默认为 true。
- -show-branch-summary¶
显示所有分支条件的统计信息。默认为 true。
- -show-mcdc-summary¶
显示 MC/DC 统计信息。默认为 false。
- -show-functions¶
显示每个函数的覆盖率摘要。默认为 false。
- -show-instantiation-summary¶
显示所有函数实例化的统计信息。默认为 false。
- -ignore-filename-regex=<PATTERN>¶
跳过文件路径与给定正则表达式匹配的源代码文件。
- -compilation-dir=<dir>¶
用作相对覆盖率映射路径的基础的目录。仅当二进制文件已使用 -fcoverage-prefix-map -fcoverage-compilation-dir 或 -ffile-compilation-dir 中的一个进行编译时适用。
- -debuginfod¶
尝试使用 debuginfod 从对象查找覆盖率映射。对于配置文件中存在但在命令行上未提供的二进制 ID，默认情况下会尝试此操作，只要编译了 debuginfod 并在 DEBUGINFOD_URLS 中进行了配置即可。
- -debug-file-directory=<dir>¶
提供一个目录来搜索与配置文件中二进制 ID 对应的对象。
- -check-binary-ids¶
如果在配置文件中找不到二进制 ID 对应的对象文件，无论是在命令行上还是通过二进制 ID 查找，都将失败。
EXPORT 命令¶
概要¶
llvm-cov export [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…
描述¶
llvm-cov export 命令使用配置文件数据 PROFILE 以 JSON 或 lcov 跟踪文件格式导出二进制文件 BIN… 的覆盖率数据。
导出 JSON 时，将导出覆盖率数据的区域、函数、分支、扩展和摘要。导出 lcov 跟踪文件时，将导出基于行的覆盖率、分支覆盖率和摘要。
导出的数据可以选择性地过滤为仅导出列出在 SOURCE… 中的文件的覆盖率。
有关编译用于覆盖率的程序和生成配置文件数据的更多信息，请参阅 SHOW 命令。
选项¶
- -arch=<name>¶
如果覆盖的二进制文件是通用二进制文件，请选择要使用的体系结构。指定通用二进制文件中未包含的体系结构或使用与非通用二进制文件不匹配的体系结构都是错误的。
- -format=<FORMAT>¶
使用指定的输出格式。支持的格式为：“text”（JSON），“lcov”。
- -summary-only¶
仅导出覆盖率数据中每个文件的摘要信息。此模式不会导出较小单元（如单个函数或区域）的覆盖率信息。结果将包含与 llvm-cov report 命令生成的相同信息，但以 JSON 或 lcov 格式而不是文本格式呈现。
- -ignore-filename-regex=<PATTERN>¶
跳过文件路径与给定正则表达式匹配的源代码文件。
- -skip-expansions¶
跳过导出宏展开覆盖率数据。
- -skip-functions¶
跳过导出每个函数的覆盖率数据。
- -num-threads=N, -j=N¶
使用 N 个线程导出覆盖率数据。当 N=0 时，llvm-cov 会自动检测要使用的适当线程数。这是默认值。
- -compilation-dir=<dir>¶
用作相对覆盖率映射路径的基础的目录。仅当二进制文件已使用 -fcoverage-prefix-map -fcoverage-compilation-dir 或 -ffile-compilation-dir 中的一个进行编译时适用。
- -debuginfod¶
尝试使用 debuginfod 从对象查找覆盖率映射。对于配置文件中存在但在命令行上未提供的二进制 ID，默认情况下会尝试此操作，只要编译了 debuginfod 并在 DEBUGINFOD_URLS 中进行了配置即可。
- -debug-file-directory=<dir>¶
提供一个目录来搜索与配置文件中二进制 ID 对应的对象。
- -check-binary-ids¶
如果在配置文件中找不到二进制 ID 对应的对象文件，无论是在命令行上还是通过二进制 ID 查找，都将失败。
CONVERT-FOR-TESTING 命令¶
警告
此命令仅供正在开发 llvm-cov 的 LLVM 开发人员使用。
概要¶
llvm-cov convert-for-testing BIN -o OUT
描述¶
llvm-cov convert-for-testing 命令用于测试 llvm-cov 本身。它可以从二进制文件 BIN 中提取所有代码覆盖率数据到文件 OUT 中，从而减小测试文件的大小。输出文件通常带有 .covmapping 扩展名。
.covmapping 文件可以像普通二进制文件一样被 llvm-cov 读取。