章节目录：

前言

C/C++test 的多指标覆盖率分析允许在执行 C/C++test 外部的独立应用程序或库时监控代码覆盖率。

C/C++test 附带一个独立的覆盖率包，包含以下组件：

• <INSTALL_DIR>/bin/cpptestcc - 一个集成到您的构建流程中的覆盖率工具，用于应用程序插桩以收集原始覆盖率数据。
  
• <INSTALL_DIR>/bin/engine/coverage/runtime - 需要与插桩的应用程序集成的覆盖率运行时库。

1. 通过将 cpptestcc 工具集成到构建中来进行应用程序插桩。
2. 执行插桩的代码并收集原始覆盖率数据。
3. 使用内建测试配置将原始覆盖率数据导入 C/C++test 可在 C/C++test 中查看覆盖率。

cpptestcc 快速入门

1. 将路径添加到 <INSTALL_DIR>/bin  PATH 系统变量，使 cpptestcc 工具能够执行。

2. 更新编译命令，使之包含 cpptestcc 可执行文件作为编译器命令的前缀，通过 -- 进行分隔。 例如：
   

   原始编译命令行

   cc -I app/includes -D defines -c source.cpp

   更新后的编译命令行
   

   cpptestcc -compiler gcc_9-64 -line-coverage -- cc -I app/includes -D defines -c source.cpp

   cpptestcc 工具至少要求在命令行配置以下参数：

   - 编译器标识符： -compiler <COMPILER_ID>

   - 覆盖率指标（例如，-decision-coverage）

   有关其他选项的信息，请参阅 cpptestcc 命令行参考。


3. 使用 C/C++test 附带的预建覆盖率运行时库的路径更新链接器命令，将该库添加到您的应用程序中。例如：
   

   原始命令行
   

   lxx -L app/lib app/source.o somelib.lib -o app.exe

   更新后的命令行
   

   lxx -L app/lib app/source.o somelib.lib [INSTALL_DIR]/bin/engine/coverage/runtime/lib/cpptest.lib -o app.exe

   重要提示

   如果覆盖率运行时库作为共享（动态加载）库链接，则必须确保在启动插桩的应用程序时可以加载该库。这通常需要将 <INSTALL_DIR>/bin/engine/coverage/runtime/bin 添加到 PATH 环境变量（Windows）或 <INSTALL_DIR>/bin/engine/coverage/runtime/lib  LD_LIBRARY_PATH 环境变量中（Linux）。

   C/C++test 为原生 Windows 和 Linux 应用程序提供了预建的覆盖率运行时库。对于跨平台和嵌入式测试，该运行时库需要从 <INSTALL_DIR>/bin/engine/coverage/runtime 的源文件中构建。 详细信息请参阅覆盖率运行时库。
   

4. 构建应用程序。进行代码插桩时，cpptestcc 会创建 .cpptest/cpptestcc 文件夹，存储重要的覆盖率相关数据（“覆盖率映射”）。默认情况下，该文件夹位于当前编译的工作目录中。可以使用 -workspace <path> 选项更改默认位置；详细信息请参阅 cpptestcc 命令行参考。 
   
5. 运行应用程序。覆盖率数据（“覆盖率日志”）将存储在 cpptest_results.clog 文件中。
   
6. 在安装了 C/C++test 的 IDE 中，创建一个包含应用程序所有源文件的新项目。
   确保这些文件和所有路径都保持不变。
   
7. 选中项目，从 IDE 菜单选择 Parasoft> 测试配置> Utilitie> Load Application Coverage 导入覆盖率数据（详细信息请参阅导入覆盖率数据）。
   
8. 查看覆盖率信息（请参阅查看覆盖率信息）。

导入覆盖率数据

Load Application Coverage 测试配置假设 .cpptest/cpptestcc 文件夹和 cpptest_results.clog 文件存储在默认位置。要自定义该位置，需在测试配置中配置以下执行细节（执行> 常规> 执行细节）：
- Coverage map files root location - default: ${project_loc}/.cpptest/cpptestcc
- Coverage log files - default: ${project_loc}/*.clog

默认情况下，Load Application Coverage 测试配置会尝试加载有关支持的所有覆盖率指标的信息。要自定义支持的覆盖率指标列表，可前往执行> 常规> 执行细节> 插桩模式> 插桩功能> C/C++ 代码覆盖率指标，然后选择需要报告的指标。

我们建议与编译命令行中为 cpptestcc 工具启用的指标保持一致。

收集 CMake 项目的应用程序覆盖率

C/C++test 附带一个 CMake 扩展，允许将 C/C++test 的代码覆盖率分析直接集成到您的 CMake 项目中。该扩展会自动修改编译器/链接器命令行，在构建项目时使用 cpptestcc 覆盖率工具。因此，在运行插桩的应用程序或执行功能测试或单元测试后，会创建一个 C/C++test·覆盖率日志文件（.clog）。该覆盖率日志文件之后可用于生成完整的代码覆盖率报告。

CMake 集成支持包含：

• <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake 扩展 - 需要添加到您的 CMakeFiles.txt 构建文件中的 CMake C/C++test 扩展文件。
• <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest.templates/* 中的模板 - 用于生成 C/C++test（Eclipse）项目的 C/C++test 一套模板。
• CPPTEST_COVERAGE=ON 和 CPPTEST_HOME=<CPPTEST_INSTALL_DIR> 选项 - 该扩展提供的选项，可在使用 CMake 构建应用程序时激活扩展。
• cpptest_coverage_report 目标 - 该扩展提供的目标，使用 .clog 文件作为输入来生成覆盖率报告。

此外，<CPPTEST_INSTALL_DIR>/examples/Timer 目录包含一个演示 CMake 项目代码覆盖率收集的示例项目。

要求

• 带有 Unix Makefiles 或 Ninja 生成器的 CMake 3.10 或更高版本

附加前提条件：

• 必须执行应用程序的完整构建才能收集 CMake 项目的代码覆盖率。不支持增量构建。
• 在 Windows 中，您的 CMake 项目和工具链需要配置为使用带正斜杠或反斜杠的 Windows 路径（例如，c:/folder/source.cpp 或 c:\folder\source.cpp）。Windows 不支持 Unix 风格的路径（例如，/c/folder/source.cpp）。

工作流程概要

1. 将 <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake 和 <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest.templates/* 复制到 CMake 项目中。

2. 在 cpptest-coverage.cmake 文件中查看覆盖率配置详细信息并根据需要更新选项。  至少需要确保使用 CPPTEST_COMPILER_ID 选项指定的编译器配置与您的编译器匹配。有关可用选项的信息，请参阅自定义 CMake 的覆盖率扩展。

3. 将 cpptest-coverage.cmake 扩展添加到您的 CMakeLists.txt 主构建文件中。概扩展必须放在所有构建目标定义之前，以确保自动修改编译器/链接器命令行。

4. 在配置和构建 CMake 项目时，使用 CPPTEST_COVERAGE and CPPTEST_HOME 选项激活扩展：

   > cmake -DCPPTEST_COVERAGE=ON -DCPPTEST_HOME=<CPPTEST_INSTALL_DIR> ..

   默认情况下，C/C++test 的覆盖率数据文件将在 <CMAKE_SOURCE_DIR>/../cpptest-coverage/<CMAKE_PROJECT_NAME>/.cpptest 中创建。

5. 运行应用程序或执行功能或单元测试。
   默认情况下，C/C++test 覆盖率日志文件（.clog）将在 <CMAKE_SOURCE_DIR>/../cpptest-coverage/<CMAKE_PROJECT_NAME>/<CMAKE_PROJECT_NAME>.clog 中创建。

6. 运行 cpptest_coverage_report 辅助目标以生成覆盖率报告：

   > make cpptest_coverage_report

   C/C++test 目标将创建：
   - 一个可以直接在 IDE 中打开的工作空间：<CMAKE_SOURCE_DIR>/../cpptest-coverage
   - 一个位于该工作空间中的 C/C++test（Eclipse）项目：<CMAKE_SOURCE_DIR>/../cpptest-coverage/<CMAKE_PROJECT_NAME>
   - 位于 reports 目录的覆盖率报： <CMAKE_SOURCE_DIR>/../cpptest-coverage/<CMAKE_PROJECT_NAME>/reports

   我们建议使用 cpptest_coverage_report 目标生成覆盖率报告。或者，也可以用 C/C++test 的 Load Application Coverage 测试配置，根据从 <CMAKE_SOURCE_DIR>/../cpptest-coverage/<CMAKE_PROJECT_NAME> 中收集的覆盖率数据生成报告。详细信息请参阅导入覆盖率数据。

自定义 CMake 的覆盖率扩展

要自定义该 C/C++test 扩展的覆盖率收集功能，应打开复制到您的 CMake 项目中的 cpptest-coverage.cmake 文件并修改 C/C++test 选项。 

此外，您可能需要查看：

• cpptest_coverage_report 目标的定义，该目标指定用于生成覆盖率报告的 cpptestcli 的参数。
• # Build C/C++test coverage runtime library 部分，其中包含配置 C/C++test 的运行时库（该库由覆盖率扩展自动构建）的配置。
• CPPTEST_LINKER_FLAGS 选项，该选项定义了如何链接 C/C++test·覆盖率运行时。

覆盖率扩展与 CMake 的集成示例

该部分演示如何使用 C/C++test 的 CMake 覆盖率扩展收集 <CPPTEST_INSTALL_DIR>/examples/Timer 目录中示例项目的覆盖率数据。Timer 项目经配置使用 <CPPTEST_INSTALL_DIR>/integration/cmake 中提供的 cpptest-coverage.cmake 扩展。

收集示例项目覆盖率的步骤：

1. 如果您使用的编译器不是默认的 GNU GCC 9 (x64)，应在 <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake 中修改CPPTEST_COMPILER_ID 以匹配您的编译器。

2. 构建示例项目：
   

   > cd <CPPTEST_INSTALL_DIR>/examples/Timer
   > mkdir build
   > cd build
   > cmake -DCPPTEST_COVERAGE=ON -DCPPTEST_HOME=<CPPTEST_INSTALL_DIR> ..
   > make

3. 运行应用程序：
   

   > ./timer

4. 生成覆盖率报告：
   

   > make cpptest_coverage_report

   报告将在 <CPPTEST_INSTALL_DIR>/examples/cpptest-coverage/Timer/reports 中生成。

5. （可选）启动 C/C++test GUI，打开<CPPTEST_INSTALL_DIR>/examples/cpptest-coverage 工作空间，在 IDE 中查看覆盖率详细信息。
   

收集 MSBuild 项目的应用程序覆盖率

您可以使用 C/C++test 附带的脚本快速配置 MSBuild 项目以集成覆盖率分析。此脚本支持 Visual Studio 和 Cmake 生成的 MSBuild 项目。该脚本创建目标 .vcxproj 文件的备份并修改，从而在所有构建目标上启用所需的 Parasoft 功能。

C/C++test 有一个 Python 脚本启动器，用于运行包含的工具，可以在以下位置找到：

<CPPTEST_INSTALL_DIR>/bin/engine/bin/cpptestpy.exe

<CPPTEST_INSTALL_DIR>/integration/msbuild/msbuild_cpptest.py

收集 MSBuild 项目覆盖率的步骤：

1. 设置环境变量。

请确保未在 = 后面使用双引号，否则会导致不正确的字符串解释。 

1. 1. 设置 CPPTEST_INSTALL_DIR 变量。

      set CPPTEST_HOME=<CPPTEST_INSTALL_DIR>

   2. 设置 PATH 变量。

      set PATH=%PATH%;%CPPTEST_HOME\bin\engine\coverage\runtime\bin

2. （仅限 Cmake）使用 Cmake 生成 MSBuild 文件。 

   cd <PROJECT_DIR>
   mkdir build
   cd build
   cmake ..

3. 运行集成脚本。 

   <cpptestpy.exe> <msbuild_cpptest.py> -c -f project.vcxproj

4. 使用 MSBuild 构建项目。

   msbuild -t:Rebuild project.sln

5.  要收集覆盖率，需进入构建目录并运行该项目。

   cd x64\Debug
   project.exe

   包含覆盖率信息的 .clog 文件将在您当前的工作目录中生成。
   文件默认命名为 cpptest_results.clog。

6. 生成覆盖率报告。

   cpptestcli.exe \
   -data ../workspace \
   -bdf cpptestscan.bdf \
   -property bdf.import.location=BDF_LOC \
   -config "builtin://Load Application Coverage"

cpptestcc 命令行参考

您可以运行以下命令将可用选项打印到控制台中： cpptestcc -help

可使用以下选项：

<project root>
 + external_libs
 + src
 + include

<project root> 
<sourcefiles>.cpp 
<headerfiles>.hpp

while(1) {} // no decision / branch
if(false) {} // no decision / branch

覆盖率运行时库

覆盖率运行时库是源代码插桩用来在应用程序运行时发出覆盖率信息的辅助函数和服务的集合。没有该库就无法链接已插桩的应用程序。根据被测项目的类型，运行时库可以通过多种方式链接到最终的可测试二进制文件。

除了为插桩的代码提供基本服务外，该库还用于使代码覆盖率解决方案适应特定的开发环境，例如支持被测嵌入式设备和开发主机之间覆盖率结果的非标准传输。

预建版本和自定义构建

C/C++test 配备了运行时库的预建版本，适合在安装了 C/C++test 的平台上使用。在大多数情况下，从原生开发的应用中收集代码覆盖率信息可以使用预建版本的运行时库。

所有开发跨平台应用程序的用户都需要使用合适的交叉编译器和链接器准备覆盖率运行时库的自定义构建。代码覆盖率运行时库的源代码与 C/C++test 一起提供。

覆盖率运行时库自定义构建的准备过程通常受限于覆盖率运行时库源代码的编译。在某些情况下，您可能需要安装一些源代码片段，以使代码覆盖率适应特定的开发平台。该过程在以下部分说明。

使用预建的运行时库

C/C++test 包含以下二进制文件：

Windows（x86 和 x86-64） 

如果您需要以非现成解决方案的形式使用运行时库，则可以准备一个符合特定开发环境要求的覆盖率运行时库的自定义构建。更多详细信息，请参阅自定义运行时库。

与链接器命令行集成

将覆盖率运行时库与被测应用程序链接过程集成通常需要修改链接器命令行，在某些情况下，还需要修改执行环境。该部分介绍如何在使用 C/C++test 提供的预建版本时修改链接过程。

Windows Cygwin GNU GCC 编译器的静态库：

1. 在构建脚本中找到链接器命令行
2. 修改构建脚本，从而在链接器命令行中某处指定覆盖率运行时库——最好在所有目标文件之后。

Microsoft Visual C++ 编译器的动态链接库：

1. 在构建脚本中找到链接器命令行

2. 修改构建脚本，从而在链接器命令行中某处指定覆盖率运行时库——最好在所有目标文件之后。例如：

   $(LXX) $(PRODUCT_OBJ) $(OFLAG_EXE)$(PROJ_EXECUTABLE) $(LXXFLAGS) $(SYSLIB) $(EXECUTABLE_LIB_LXX_OPTS) <INSTALL_DIR>/bin/engine/coverage/runtime/lib/cpptest.lib

3. 确保将 lib 目录的路径添加到 PATH 环境变量，以便在启动被测程序时能够定位该库。也可以考虑将 cpptest.dll（或 cpptest64.dll）文件复制到与可执行文件所在的目录，或者复制到在被测应用程序启动期间为动态链接库扫描的其他位置。

Linux GNU GCC 编译器的共享库：

1. 在构建脚本中找到链接器命令行

2. 修改构建脚本，从而在链接器命令行中某处指定覆盖率运行时库——最好在所有目标文件之后。例如：

   $(LXX) $(PRODUCT_OBJ) $(OFLAG_EXE)$(PROJ_EXECUTABLE) $(LXXFLAGS) $(SYSLIB) $(EXECUTABLE_LIB_LXX_OPTS) -L <INSTALL_DIR>/bin/engine/coverage/runtime/lib -lcpptest

   请注意是否已添加 -L 和 -lcpptest 选项。

3. 确保将 lib 目录的路径添加到 LD_LIBRARY_PATH 环境变量中，允许被测可执行文件找到共享库的路径。

自定义运行时库

出现以下情况时，可能需要自定义运行时库：

• 需要不同形式的二进制文件
• 启用用于结果传输的非默认通信通道
• 安装用于结果传输的通信通道的自定义实现
• 启用多线程应用程序的非默认支持
• 安装多线程应用程序支持的自定义实现
• 多个插桩的二进制文件写入同一个覆盖率日志文件

库源代码结构

运行时库源代码随 C/C++test 一起提供，位于 [INSTALL_DIR]/bin/engine/coverage/runtime 目录中。下表提供了该结构的描述： 

切换通信通道支持

运行时库支持通过各种通信通道收集数据。使用的通信通道取决于开发环境。在大多数情况下，可以将结果存储在一个或多个文件中，但在其他情况下则可能需要使用 TCP/IP 套接字或 RS232 传输。在 cpptest.c 库源文件编译过程中，可以设置专用的宏值来启用特定的通信通道。将 -D<MACRO> 添加到编译命令行中设置该值。下表提供了通信通道控制宏的完整列表：  

如果使用提供的 Makefile 构建覆盖率运行时库，则可以使用 [INSTALL_DIR]/bin/engine/coverage/runtime/channel 目录中提供的其中一个 make 配置文件。

安装自定义通信通道的支持

如果没有适合您的开发环境的通信通道实现，则可以提供自定义实现。以下说明描述了如何自定义运行时库，使其使用通信通道的自定义实现： 

1. 复制 [INSTALL_DIR]/bin/engine/coverage/runtime/src/cpptest.c 并打开文件进行编辑。

2. 找到 1.14“Custom Communication Implementation”部分。
   Custom Communication Implementation 部分包含四种不同方法的空模板：

   函数	说明
   void cpptestInitializeStream(void)	该函数负责初始化通信通道，例如创建并连接套接字或初始化 UART 设备。
   void cpptestFinalizeStream(void)	该函数负责终止通信通道。例如，它可能负责关闭 TCP/IP 套接字。
   int cpptestSendData(const char *data, unsigned size)	该函数负责从数据缓冲区发送大小字节。
   void cpptestFlushData(void)	该函数负责清除数据。它的含义取决于特定的传输类型。该函数在一些实现中的应用可能受限，在这种情况下，该函数应该留空。

3. 为符合您的环境要求的方法提供实现。
4. 编译 cpptest.c 时，将以下宏定义添加到编译命令行：
   -DCPPTEST_CUSTOM_COMMUNICATION
5. 如果生成的目标文件无法满足要求，您可以根据需要进一步处理该文件（例如，创建共享库）。

切换多线程 API 支持

运行时库包含对多线程应用程序的支持。支持 POSIX、Windows 和 VxWorks API。您可以在 cpptest.c 编译时通过将 -D<MACRO> 添加到编译命令行来启用对特定多线程 API 的支持。下表提供了多线程 API 支持控制宏的完整列表：

安装自定义线程 API 的支持

如果将 C/C++test 的覆盖率引擎与不使用支持的多线程 API 的多线程应用程序使用，您可以自定义运行时库，从而与您的多线程 API 一起使用。需要完成以下步骤：

1. 复制 [INSTALL_DIR]/bin/engine/coverage/runtime/src/cpptest.c 并打开文件进行编辑。

2. 找到 2.5“Custom Multithreading Implementation”部分。
   Custom Multithreading Implementation 部分包含两种不同方法的空模板：

   函数	说明
   static int cpptestLock(void)	该函数确保覆盖率工具运行时库内部的同步操作。如果一个线程锁定了对运行时库服务的访问，这意味着一个原子操作正在进行，其他线程不可以使用运行时库服务。锁定释放后，其他线程才可以使用运行时库服务
   static int cpptestUnlock(void)	解除对运行时库服务的锁定。

3. 为符合您的环境需求的方法提供实现。

4. 编译 cpptest.c 时，将以下宏添加到编译命令行：
   -DCPPTEST_CUSTOM_THREADS

5. 如果生成的目标文件无法满足要求，您可以根据需要进一步处理该文件（例如，创建共享库）。

多个插桩的二进制文件写入同一个覆盖率日志文件

当同一个覆盖率日志文件（.clog）被并行运行的多个插桩的二进制文件使用时，需要在运行时库中启用多进程支持。

要启用多进程支持，编译 cpptest.c 时将以下宏添加到编译命令行：
"-DCPPTEST_MULTI_PROCESSES_LOG=1"

构建运行时库

C/C++test 附带了一个简单的 Makefile（请参阅库源代码结构），可简化构建运行时库的过程。然而，在多数情况下不需要提供的 make 文件，因为源代码已经针对构建过程进行了优化。唯一一个始终需要执行的步骤是编译主要的 cpptest.c 源文件。对所产生的目标文件的任何额外处理都取决于特定的开发环境及要求，例如将运行时库作为共享库提供。

使用提供的 Makefile 构建运行时库

1. 复制 <INSTALL_DIR>/bin/engine/coverage/runtime 到本地目录。

2. 如果需要修改编译标志（例如，添加交叉编译器或定义来执行运行时库重新配置），应在目标子目录中提供一个新的 make 配置文件。为了方便起见，您可以复制一个现有的目标配置文件，然后修改其内容以满足您的需要。

3. 调用以下命令行创建包含单个对象 cpptest.<OBJ_EXT> 的 build 子目录，可用于链接插桩的应用程序。

   make TARGET_CFG=<target config file name> CHANNEL_FILE=<channel config file name>

   您的命令行可能类似于：

   make TARGET_CFG=gcc-static.mk CHANNEL_FILE=channel/unix-socket.mk

   或者，您可以提供通道类型：

   make TARGET_CFG=gcc-static.mk CHANNEL_TYPE=unix-socket

4. 如果需要通过共享库、动态链接库或任何其他类型的二进制文件链接覆盖率运行时库，则需要自定义 Makefile 或设置自定义构建。

运行时库用户构建

要设置覆盖率运行时库的用户构建，请执行以下步骤：

1. 将 <INSTALL_DIR>/bin/engine/coverage/runtime/src/cpptest.c 中的 cpptest.c 文件复制到您的首选位置。

2. 根据自定义运行时库中的说明引入所需自定义设置。
3. 设置您需要的构建系统（例如， IAR Embedded Workbench 项目或任何其他类型的源代码构建器）。

4. 修改编译标志以包含编译器的 include 标志（通常使用 -I），并使用以下值：-I <INSTALL_DIR>/bin/engine/coverage/runtime/include

5. 添加所需的配置定义（通常使用 -D）例如：
   -DCPPTEST_FILE_COMMUNICATION -DCPPTEST_NO_THREADS
6. 调用命令运行构建器（例如，在 IDE 中选择构建命令）。
7. 找到生成的目标文件，并使用该文件链接插桩的应用程序。

代码覆盖率故障排查

cpptestcc -disable-auto-recovery-mode [. . .]

cpptestcc -coverage-data-variants [. ..]