cmreport – 代码覆盖率报告生成

cmreport 是一个工具，可以从一个 instrument 数据库（一个 .csmes 文件）生成文本、HTML、XML 或 CSV 报告。它生成的报告与 CoverageBrowser 生成的报告完全相同（见 报告生成）。

最简单的用例是从单个 instrument 数据库生成 HTML 报告。如果文件名为 project.csmes，我们可以编写

$ cmreport --csmes=project.csmes --html=report

此命令将创建一个名为 report.html 的文件和一个名为 report_html 的目录。文件 report.html 是报告的主页，可以用浏览器打开，而 report_html 包含所有其他文件。大多数其他命令行选项只是修改了这样的报告的内容。

语法

cmreport -m <csmes_file> ...

选项

• -m <filename> | --csmes=<filename>: 设置主 .csmes 文件名称（必须）。
• -p <filename> | --patch=<filename>: 启用补丁/差异文件分析。<filename> 是一个使用 统一差异 格式的文件（见 差异文件生成）。文件必须包含 .csmes 文件覆盖目录树中的文件与同一目录树的修改版本之间的差异。补丁报告可以以 CSV 和 HTML 格式生成。

  使用 --section 选项（见 HTML 或 CSV 报告的选项）可以选择显示报告的哪些部分。

• --source-type=<argument>: 用于分析的数据源类型。可能的值
  • preprocessed: 分析预处理的代码。
  • original: 分析原始源代码。在此模式下忽略 C 宏。
• -l <number> | --level=<number>: 设置代码覆盖率级别。<number> 必须是一个大于 0 的整数。
• --max-threads=<数字>：用于报表计算的线程的最大数量。默认情况下，线程数量与系统中的CPU数量相同。
• --stat：将全局覆盖率统计信息打印到标准输出。
• --max-lines-per-page=<数字>：HTML表中每页的最大行数。
• @<路径>：从位于<路径>的文件中读取命令行选项，并将其插入到本选项的位置。选项文件是每行一个选项的文本文件。忽略前导和尾随空白以及空行。

文件选择选项

以下选项指定在报表中显示的源文件。

• --include-file-abs-regex=<正则表达式>：将与正则表达式<正则表达式>匹配的源文件包含在报表中。
• --exclude-file-abs-regex=<正则表达式>：将与正则表达式<正则表达式>匹配的源文件从报表中排除。
• --include-file-abs-wildcard=<通配符>：将匹配通配符模式<通配符>的源文件包含在报表中。
• --exclude-file-abs-wildcard=<通配符>：将匹配通配符模式<通配符>的源文件从报表中排除。
• --sources-without-instrumentation：包含带有插桩但不包含任何要覆盖的代码的源文件。

如果有两个或更多选项匹配文件，则最后一个选项决定是否包含或排除。有关正则表达式和通配符语法的语法，请参阅使用通配符或正则表达式进行过滤。

执行选择选项

以下选项指定报表中发生的执行。

• -s <正则表达式> | --select=<正则表达式>：使用正则表达式选择执行。如果未使用，则隐式选择所有执行。
• -d <正则表达式> | --deselect=<正则表达式>：使用正则表达式取消选择执行。
• --deselect-to-check：取消选择状态为CHECK_MANUALLY的所有执行。
• --select-passed：选择状态为PASSED的所有执行。
• --deselect-passed：取消选择状态为PASSED的所有执行。
• --select-failed：选择状态为FAILED的所有执行。
• --deselect-failed：取消选择状态为FAILED的所有执行。
• --select-unknown：选择未知状态的所有执行。
• --deselect-unknown：取消选择未知状态的所有执行。
• --executions-reference-from-csmes=<参数>：选择指定<参数>的.csmes文件中存在的所有执行。

版本比较

使用以下选项，可以比较两个版本的覆盖率。

• -mr <文件名> | --csmes-reference=<文件名>：设置<文件名>的.csmes参考文件。使用此选项，cmreport比较两个软件版本。
• --release-comparison=<参数>：比较两个软件版本时的比较模式。可能的值
  • none：仅显示两个软件版本之间的差异。
  • modified_functions：仅显示修改函数的覆盖率。
  • unmodified_functions：仅显示相同函数的覆盖率。
• -sr <正则表达式> | --select-reference=<正则表达式>：使用正则表达式选择参考执行。此选项激活执行比较。
• -dd <正则表达式> | --deselect-reference=<正则表达式>：使用正则表达式取消选择参考执行。此选项激活执行比较。
• --deselect-to-check-reference: 取消选中全部具有 CHECK_MANUALLY 状态的参考执行。
• --select-passed-reference: 选中全部具有 PASSED 状态的参考执行。
• --deselect-passed-reference: 取消选中全部具有 PASSED 状态的参考执行。
• --select-failed-reference: 选中全部具有 FAILED 状态的参考执行。
• --deselect-failed-reference: 取消选中全部具有 FAILED 状态的参考执行。
• --select-unknown-reference: 选中所有状态未知的参考执行。
• --deselect-unknown-reference: 取消选中所有状态未知的参考执行。

HTML 或 CSV 报告选项

命令行参数

• -h <filename> | --html=<filename>: 生成多页面上 HTML 报告。

  报告包括一个文件 <file_name>.html，指向报告的索引文件，以及一个目录 <file_name>_html，其中包含报告中的所有其他文件。

  如果 <filename> 以 .html 结尾，则忽略扩展名，因此不会生成以双 html 结尾的文件名或目录。

• --html-single=<filename>: 作为文件 <filename> 生成单个 HTML 报告。

  如果 <filename> 不以 .html 结尾，将自动添加。

• --csv-excel=<filename>: 生成 CSV 报告。

  报告格式用于 Excel 和 OpenOffice。如果 <filename> 不以 .csv 结尾，将自动添加。

• --title=<string>: 设置报告的标题。
• --execution-level=<number>: 设置所需的代码覆盖率级别为 <number>。

  只有在至少执行 <number> 次的情况下，才会将代码段计入生成的报告中。默认级别为 1。

• --section=<section_name>: 选择生成的报告的章节。此选项可以重复使用以选择多种章节类型。如果没有选择任何内容，cmreport 将自动生成所有相关章节。

  以下章节是可能的

  • global: 全局统计
  • function: 函数统计
  • function-tree: 带统计的功能树
  • class: 类/命名空间统计
  • execution: 执行统计
  • source: 源文件统计
  • source-tree: 带统计的源树
  • directory: 目录文件统计
  • manually-validated: 手动验证的代码片段
  • unexecuted: 未执行的代码片段
  • dead-code: 死代码片段
  • executed: 执行的代码片段

  如果使用 --patch 选项，则还有以下章节是可能的。

  • patch-execution-statistic: 补丁的全局执行统计
  • patch-source-statistic: 补丁的全局源代码统计
  • patch-execution: 受补丁影响的执行
  • patch-source: 标注的补丁文件
  • patch-source-instrumented: 仅针对已加固文件的标注补丁文件

  有关这些章节的内容，请参阅 补丁分析。默认情况下，如果没有设置 --section 选项，它们都会出现在报告中。

• --coverage-mcc: 报告多个条件代码覆盖率测量。
• --coverage-mcdc: 报告MC/DC覆盖率测量。
• --coverage-condition: 报告条件覆盖率测量。
• --coverage-decision: 报告决策覆盖率测量。
• -b | --coverage-statement-block: 报告语句（代码块）覆盖率测量。
• --line-coverage: 报告行覆盖率测量。
• --function-coverage: 报告函数覆盖率测量。
• --coverage-line: 报告行覆盖率测量（等同于 --line-coverage）。
• --coverage-function: 报告函数覆盖率测量（等同于 --function-coverage）。
• -t | --test-coverage: 测试计数模式
• -D | --debug: 调试标志
• --no-line-metrics: 不报告eLOC（有效代码行数）指标。
• --no-mccabe-metrics: 不报告McCabe（或圈复杂度）指标。
• --mccabe-group-case-metrics: 以合并的case形式报告McCabe指标（或圈复杂度）。
• --mccabe-condensed-switches-metrics: 以压缩的switch形式报告McCabe指标（或圈复杂度）。

仅限于HTML的选项

• --css=<filename>: CSS样式表
• --icon=<filename>: 图标
• --global-threshold-low-medium=<num>: 全局阈值设置
• --global-threshold-medium-high=<num>: 全局阈值设置
• --source-threshold-low-medium=<num>: 源/目录阈值设置
• --source-threshold-medium-high=<num>: 源/目录阈值设置
• --function-threshold-low-medium=<num>: 函数、类或命名空间阈值设置
• --function-threshold-medium-high=<num>: 函数、类或命名空间阈值设置

仅限于CSV的选项

• --csv-field-separator=<char>: CSV文件的字段分隔符
• --csv-comma=<char>: CSV文件中用于浮点数的分隔符（逗号或点）

文本报告选项

命令行参数

• -t <filename> | --text=<filename>: 文本报告输出文件名
• --format-executed=<argument>: 代码片段执行的行格式
• --format-unexecuted=<argument>: 代码片段未执行的行格式
• --format-manually=<argument>: 手动验证的代码片段的行格式
• --format-dead-code=<argument>: 不可执行代码片段的行格式

以下为支持的转义序列

• %f: 绝对源代码文件名
• %r: 相对于当前构建目录的源代码文件名
• %l: 行号
• %c: 列号
• %m: 说明
• %t: 源代码片段
• %e: 运行插件的测试列表

可以将输出文件设置为空字符串（即：--text=），在这种情况下使用控制台的默认输出。

EMMA-XML报告选项

生成EMMA XML格式的报告时使用以下选项

• --emma=<filename>: 生成EMMA-XML报告。 <filename>是生成的XML文件名。
• --emma-source-pattern=<argument>: EMMA-XML报告的源文件模式。
• --emma-package-pattern=<argument>: EMMA-XML报告的包名模式。

模式有以下格式

• %f：文件名（不含路径）
• %b：不含路径和扩展名的文件名
• %e：文件扩展名
• %p：文件路径（不含文件名）
• %P：绝对文件路径（不含文件名）

JUnit 报告选项

命令行参数

• -j <filename> | --junit=<filename>：生成 JUnit 报告

JUnit 报告不包含任何代码覆盖率信息。报告仅列出执行过的测试、它们的状态（通过或失败）和它们的注释。

Coberatura 报告选项

要生成 Coberatura 报告，您需要指定以下选项中的前两个或最后一个：

• --cobertura=<file>：生成 Coberatura-XML 报告。<file> 是生成的输出文件路径。
• --cobertura-azure-devops：为 Azure DevOps 生成 Coberatura-XML 报告。
• --cobertura-manual-validation-hits=<int>：对于手动验证，在 Coberatura-XML 报告中设置行覆盖率命中数。
• --cobertura-source=<directory>：生成 Coberatura-XML 报告时，源代码的根目录。

  此选项在存在 --cobertura 时是必需的；否则没有意义。

• --sonarqube-project=<path>：为 SonarQube 项目生成 Coberatura-XML 报告。

  <path> 是 sonar-project.properties 文件的路径。项目的根目录从这个文件的位置确定。然后从其内容中提取输出 XML 文件的路径。这是 sonar.cxx.coverage.reportPath、sonar.cxx.coverage.itReportPath 或 sonar.cxx.coverage.overallReportPath 属性的值。设置这些属性中的任何一个都有相同的效果。

  注意： 为了读取 Cobertura-XML 报告，SonarQube 需要一个第三方插件，这个插件可能不是每个安装中都可用。您可以使用下面的 SonarQube 报告选项，它根据 SonarQube 的通用测试覆盖率格式生成报告。

SonarQube 报告选项

以下选项用于生成 SonarQube-XML 报告

• --sonarqube=<file>：生成 SonarQube-XML 报告。<file> 是生成的输出文件路径。
• --sonarqube-report=<file>：等同于 --sonarqube。它提供向后兼容性。
• --sonarqube-source=<directory>：生成 SonarQube-XML 报告时，源代码的根目录。它用于确定报告中源文件的相对路径。

  当存在 --sonarqube 或 --sonarqube-report 时，此选项是必需的；否则没有意义。

• --sonarqube-manual-validation：将手动验证包含在 SonarQube-XML 报告中的行覆盖率。