llvm-cov - 发射覆盖率信息

概要

llvm-cov 命令 [参数…]

描述

llvm-cov 工具显示为发射 profile 数据的程序提供的代码覆盖率信息。它可以用于处理 gcov 风格的覆盖率或基于 clang 的 instrumentation 的 profiling。

如果程序以 gcov 的基本名称调用，它的行为将如同调用了 llvm-cov gcov 命令。否则，应该提供一个命令。

命令

• gcov

• show

• report

• export

GCOV 命令

概要

llvm-cov gcov [选项] 源文件

描述

llvm-cov gcov 工具读取代码覆盖率数据文件，并显示指定源文件的覆盖率信息。它兼容 GCC 4.2 版本的 gcov 工具，并且可能也兼容一些更高版本的 gcov。

要使用 llvm-cov gcov，你必须首先构建一个 instrumentation 版本的应用程序，它在运行时收集覆盖率数据。使用 -fprofile-arcs 和 -ftest-coverage 选项进行编译以添加 instrumentation。（或者，你可以使用 --coverage 选项，它包含了这两个其他选项。）

在你编译 instrumentation 代码时，将为每个目标文件生成一个 .gcno 数据文件。这些 .gcno 文件包含一半的覆盖率数据。另一半数据来自当你运行 instrumentation 程序时生成的 .gcda 文件，每个目标文件都有一个单独的 .gcda 文件。每次你运行程序时，执行计数都会累加到任何现有的 .gcda 文件中，因此如果你不希望包含旧文件的内容，请务必删除任何旧文件。

默认情况下，.gcda 文件写入到与目标文件相同的目录中，但是你可以通过设置 GCOV_PREFIX 和 GCOV_PREFIX_STRIP 环境变量来覆盖它。GCOV_PREFIX_STRIP 变量指定要从目标文件目录的绝对路径的开头删除的目录组件的数量。在剥离这些目录之后，将添加来自 GCOV_PREFIX 变量的前缀。这些环境变量允许你在无法访问原始目标文件目录的机器上运行 instrumentation 程序，但是你随后需要将 .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 <string>

要省略的源前缀。

-t, --stdout

打印到 stdout 而不是生成 .gcov 文件。摘要信息仍然显示。

-u, --unconditional-branches

在 –branch-probabilities 选项的输出中包含无条件分支。

-version

显示 llvm-cov 的版本。

-x, --hash-filenames

在命名覆盖率输出文件时使用文件名的 md5 哈希值。源文件名将以 ## 为后缀，后跟为其计算的 MD5 哈希值。

退出状态

如果 llvm-cov gcov 无法读取输入文件，则返回 1。否则，它以零退出。

SHOW 命令

概要

llvm-cov show [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

描述

llvm-cov show 命令使用 profile 数据 PROFILE 显示二进制文件 BIN… 的逐行覆盖率。它可以选择性地过滤，仅显示 SOURCE… 中列出的文件的覆盖率。

BIN 可以是可执行文件、目标文件、动态库或归档文件（thin 或其他）。

要使用 llvm-cov show，你需要一个使用 instrumentation 编译的程序，以发射 profile 和覆盖率数据。要使用 clang 构建这样的程序，请使用 -fprofile-instr-generate 和 -fcoverage-mapping 标志。如果使用 clang 驱动程序链接，请将 -fprofile-instr-generate 传递到链接阶段，以确保链接必要的运行时库。

覆盖率信息存储在构建的可执行文件或库本身中，这应该是你传递给 llvm-cov show 作为 BIN 参数的内容。profile 数据通过正常运行此 instrumentation 程序生成。当程序退出时，它将写出一个原始 profile 文件，通常称为 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>

指定一个符号反混淆器。这可以用于使报告更具可读性。可以多次指定此选项以向反混淆器提供参数（例如，C++ 的 -Xdemangler c++filt -Xdemangler -n）。反混淆器应从 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 查找 profile 中存在但命令行上未提供的任何对象的覆盖率映射。如果 debuginfod 已编译并配置了 DEBUGINFOD_URLS 环境变量，则默认为 true。

-debug-file-directory=<dir>

提供本地目录以搜索与 profile 中的二进制 ID 对应的对象（与 debuginfod 类似）。默认为系统 build ID 目录。

-check-binary-ids

如果无法为 profile 中存在的二进制 ID 找到对象文件，无论是在命令行上还是通过二进制 ID 查找，则失败。

REPORT 命令

概要

llvm-cov report [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

描述

llvm-cov report 命令使用 profile 数据 PROFILE 显示二进制文件 BIN… 的覆盖率摘要。它可以选择性地过滤，仅显示 SOURCE… 中列出的文件的覆盖率。

BIN 可以是可执行文件、目标文件、动态库或归档文件（thin 或其他）。

如果未提供源文件，则为覆盖率数据中的每个文件打印摘要行。如果提供了任何文件，则如果启用了 -show-functions 选项，则可以显示列出文件中每个函数的摘要。

有关编译程序以进行覆盖率测试和生成 profile 数据的信息，请参阅 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 从对象中查找覆盖率映射。对于 profile 中存在但命令行上未提供的二进制 ID，只要 debuginfod 已编译并配置了 DEBUGINFOD_URLS，就会默认尝试这样做。

-debug-file-directory=<dir>

提供一个目录以搜索与 profile 中的二进制 ID 对应的对象。

-check-binary-ids

如果无法为 profile 中存在的二进制 ID 找到对象文件，无论是在命令行上还是通过二进制 ID 查找，则失败。

EXPORT 命令

概要

llvm-cov export [选项] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

描述

llvm-cov export 命令以 JSON 或 lcov 跟踪文件格式导出二进制文件 BIN… 的覆盖率数据，使用 profile 数据 PROFILE。

当导出 JSON 时，将导出覆盖率数据的区域、函数、分支、扩展和摘要。当导出 lcov 跟踪文件时，将导出基于行的覆盖率、分支覆盖率和摘要。

导出的数据可以选择性地过滤，仅导出 SOURCE… 中列出的文件的覆盖率。

有关编译程序以进行覆盖率测试和生成 profile 数据的信息，请参阅 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 从对象中查找覆盖率映射。对于 profile 中存在但命令行上未提供的二进制 ID，只要 debuginfod 已编译并配置了 DEBUGINFOD_URLS，就会默认尝试这样做。

-debug-file-directory=<dir>

提供一个目录以搜索与 profile 中的二进制 ID 对应的对象。

-check-binary-ids

如果无法为 profile 中存在的二进制 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 读取，就像普通的二进制文件一样。