章节目录：

前言

要使用已有的构建系统自动创建项目，C/C++test 需要有关代码库构建过程的信息。若要向 C/C++test 提供必要的信息，可以运行C/C++test附带的 cpptestscan 或 cpptesttrace 工具创建一个 C/C++test 项目，而该项目通常需要使用 GNU make、CMake 或 Qmake 等构建工具才能构建。这些工具会输出一个构建数据文件，包含 C/C++test 所需的构建信息（详细信息请参阅关于构建数据文件（.bdf））。或者，您可以先构建一个项目，然后使用上述工具收集的信息手动进行配置。

如果使用 Cmake，也可以直接在 Cmake 构建文件中定义 C/C++test 项目。这样您就可以在使用 Cmake 构建期间自动生成 C/C++test 项目，而无需运行 cpptestscan 或 cpptesttrace。详细信息请参阅将 C/C++test 集成到 Cmake 构建中。

您还可以使用 C/C++test 项目创建向导导入 CMake JSON 构建定义文件。有关该项目创建方法的更多信息，请参阅使用 GUI 向导导入构建数据文件的项目。

关于构建数据文件（.bdf）

构建信息（如工作目录、编译的命令行选项以及原始构建的链接进程）存储在构建数据文件中。以下示例来自构建数据文件的一部分：

------- cpptestscan v. 9.4.x.x -------
working_dir=/home/place/project/hypnos/pscom
project_name=pscom
arg=g++
arg=-c
arg=src/io/Path.cc
arg=-Iinclude
arg=-I.
arg=-o
arg=/home/place/project/hypnos/product/pscom/shared/io/Path.o

构建数据文件可以用作有关项目源文件、编译器可执行文件、编译器选项、链接器可执行文件以及用于构建项目的选项的信息来源。有三种方法可以使用构建数据文件创建项目：

• 手动设置 '使用构建数据文件中的选项' 作为项目的选项源，并选择相应的构建数据文件（请参阅从 GUI 创建项目）。

• 使用 GUI 自动导入项目。请参阅使用 GUI 向导导入构建数据文件的项目。

  注意

  如果满足以下条件，也可以将所需的环境变量存储在构建数据文件中：

  • 您的构建系统设置了编译器/链接器正常工作所需的环境变量
  • 运行 C++test 时，这些变量在环境中不可用。

  请参阅下文对 '--cpptestscanEnvInOutput' 选项的说明。

使用 cpptestscan 或 cpptesttrace 创建构建数据文件

cpptestscan 和 cpptesttrace 可执行文件随 C/C++test 一起提供 <INSTALL_DIR>/bin  目录。它们从现有代码库的构建过程中收集信息，用这些信息生成构建数据文件，并将有关每个执行的信息添加到文件中。

cpptestscan 工具在正常构建期间用作编译器和/或链接器的包装器。要对现有构建使用 cpptestscan，应将 cpptestscan 用作现有构建的编译器/链接器可执行文件的前缀来构建代码库。具体可以通过两种方式完成：

• 修改构建命令行，将 cpptestscan 用作编译器/链接器可执行文件的包装器
• 如果不想（或不能）在命令行重写编译器变量，可在实际的 make 文件或构建脚本中插入 cpptestscan。

要对现有构建使用 cpptesttrace，应将 cpptesttrace 用作整个构建命令的前缀。cpptesttrace 将跟踪构建期间执行的编译器和链接器进程，并将它们存储在构建数据文件中。

在以上两种情况下，您都需要将 C++test 安装目录添加到 PATH 环境变量中或指定任一工具的完整路径。

有关 cpptestscan 和 cpptesttrace 的更多选项汇总在下面的表中。可以直接或通过环境变量设置 cpptestscan 命令的选项。通过更改命令行中的前缀，大多数选项都可以应用于 cpptestscan 或 cpptesttrace。

cpptestscan 基本用法：

cpptestscan [options] [compile/link command]
cpptestscan --cpptestscanHelp

cpptesttrace 基本用法：

cpptesttrace [options] [build command]
cpptesttrace --cpptesttraceHelp

示例：将 GNU Make Build 命令修改为使用 cpptestscan

假设基于 make 的构建中编译器变量为 CXX，原始编译器为 g++：

      make -f </path/to/makefile> <make target> [user-specific options] CXX="cpptestscan --cpptestscanOutputFile=/path/to/name.bdf --cpptestscanProjectName=<projectname> g++"

这将按常规方式构建代码，并在指定的目录中生成一个构建数据文件（name.bdf）。

示例：将 GNU Make Build 命令修改为使用 cpptesttrace

假设使用以下方法执行常规的基于 make 的构建：

     make clean all

您可以使用以下命令行：

     cpptesttrace --cpptesttraceOutputFile=/path/to/name.bdf --cpptesttraceProjectName=<projectname> make clean all

这将按常规方式构建代码，并在指定的目录中生成一个构建数据文件（name.bdf）。

示例：将 GNU Makefile 修改为使用 cpptestscan

如果 Makefile 使用 CXX 作为编译器可执行文件的变量，并且正常定义为 CXX=g++，则可以重新定义该变量：

     ifeq ($(BUILD_MODE), PARASOFT_CPPTEST)
     CXX="/usr/local/parasoft/cpptestscan --cpptestscanOutputFile=<selected_location>/MyProject.bdf --cpptestscanProjectName=MyProject g++"
     else
     CXX=g++
     endif

接下来，按常规方式运行构建并为 make 指定一个额外的 BUILD_MODE 变量：

     make BUILD_MODE=PARASOFT_CPPTEST

将构建代码并创建构建数据文件（MyProject.bdf）。然后，生成的构建数据文件可以用于在 GUI 或命令行创建项目。

示例：在 CMake 构建中使用 cpptesttrace

假设您有一个基于 CMake 的构建，可以使用 cpptesttrace 生成一个构建数据文件：

1. 运行原始的 CMake 命令，使用 CMake 生成 make 文件。例如：

   cmake -G "Unix Makefiles" ../project_root

2. 设置 cpptestscan 的环境变量，确保为输出文件使用绝对路径：

   export CPPTEST_SCAN_PROJECT_NAME=my_project
   export CPPTEST_SCAN_OUTPUT_FILE=$PROJ_ROOT/cpptestscan.bdf

3. 确保 cpptesttrace 可执行文件在 PATH 中。
4. 正常运行项目构建，但将 cpptesttrace 用作包装器。例如，如果常规构建命令为 make clean all 与 'cpptesttrace'，则该命令将变成 cpptesttrace make clean all

将在 CPPTEST_SCAN_OUTPUT_FILE 变量定义的位置生成构建数据文件。如果未设置变量，将在 Makefiles 的位置生成构建数据文件。

示例：在 CMake 构建中使用 cpptestscan

所有脚本和命令都是基于 bash - 可根据不同 shell 的需要进行调整。

如果是基于 CMake 的构建，则执行以下操作以使用 cpptestscan 生成构建数据文件：

1. 使用 CMake 重新生成 make 文件，将 'cpptestscan' 用作编译器前缀。确保在 PATH 中提供 'cpptestscan' 可执行文件。

   1. 如果原始 CMake 命令是 cmake -G “Unix Makefiles” ../project_root，那么您需要清除现有的 CMake 缓存并运行 cmake 重写编译器变量。以下示例假设 'gcc' 用作 C 编译器，'g++' 用作 C++ 编译器可执行文件：

      rm CMakeCache.txt
      CC="cpptestscan gcc" CXX="cpptestscan g++" cmake -G "Unix Makefiles" ../project_root

   2. 在 CMakeCache.txt 文件中查看 CMAKE_*_COMPILER 变量是否指向 cpptestscan。
   3. 如果重新生成了 make 文件，请直接执行步骤 5。如果由于未识别编译器导致 cmake 在引导阶段失败，请继续。

2. 通过创建以下 BASH 脚本，准备像 CMake 编译器一样运行的 cpptestscan 包装器脚本。在本例中，我们假设 'gcc' 用作 C 编译器，'g++' 用作 C++ 编译器可执行文件：

   >cat cpptest_gcc.sh
   #!/bin/bash
   cpptestscan gcc --cpptestscanRunOrigCmd=no $* > /dev/null 2>&1 gcc $*
   exit $?
   
   >cat cpptest_g++.sh
   #!/bin/bash
   cpptestscan g++ --cpptestscanRunOrigCmd=no $* > /dev/null 2>&1 g++ $*
   exit $?

   
   

   • 第一个脚本调用 cpptestscan 在不运行编译器的情况下提取选项。第二个脚本运行实际的编译器，以便整个脚本的行为和表现都像编译器一样，从而被 CMake“接受”。
3. 为脚本提供可执行属性，并将它们放在一个公共位置，这样每个需要扫描 make 文件的人都可以访问。确保 cpptestscan 和脚本在 PATH 中。
4. 通过用准备的脚本重新生成 make 文件的选项扩展原始 CMake 命令，使用作为编译器的脚本来用 CMake 重新生成 make 文件。

   • 原始 CMake 命令是 cmake -G “Unix Makefiles” ../project_root，那么您需要清除现有的 CMake 缓存并运行 cmake 重写编译器变量。在以下例中，我们假设 'gcc' 用作 C 编译器，'g++' 用作 C++ 编译器可执行文件：

     rm CMakeCache.txt
     cmake -G "Unix Makefiles" -D CMAKE_C_COMPILER=cpptest_gcc.sh -D CMAKE_CXX_COMPILER=cpptest_g++.sh ../project_root

   • 在 CMakeCache.txt 文件中查看 CMAKE_*_COMPILER 变量是否指向准备的包装器。

5. 设置 cpptestscan 的环境变量；确保为输出 BDF 文件使用绝对路径：

   export CPPTEST_SCAN_PROJECT_NAME=my_project
   export CPPTEST_SCAN_OUTPUT_FILE=$PROJ_ROOT/cpptestscan.bdf

6. 正常运行项目生成，不覆盖任何 make 变量。构建数据文件将在 CPPTEST_SCAN_OUTPUT_FILE 变量定义的位置生成，未设置的情况下将在 Makefiles 的位置生成。

在其他构建系统中使用 cpptestscan 或 cpptestrace

对于不基于 make 的构建系统，cpptestscan 和 cpptesttrace 的使用与上面的示例非常相似。通常，编译器被定义为构建脚本中的变量。要使用 cpptestscan 从相应构建系统创建构建数据文件，应在原始编译器可执行文件前添加 cpptestscan。要使用 cpptesttrace 从相应构建系统创建构建数据文件，应在整个构建命令行前加上 cpptesttrace。

通过 GUI 向导使用构建数据文件导入项目

您可以使用项目创建向导导入 BDF 或 CMake 构建定义文件，这将会创建一个 C++test 项目。

从构建数据/定义文件创建项目的步骤：

1. 选择文件> 新建> 项目并选择 C++test> 创建来自构建数据文件 (.bdf/.json) 的项目。 
   
2. 点击下一步并浏览构建数据/定义文件。
3. 指定项目的位置。启用使用工作空间位置项目位置选项将在工作空间位置的子目录中创建项目。启用使用外部位置将直接在指定位置创建一个项目。如果是创建多个项目，将在指定的外部位置创建每个项目的子目录。有关可用项目创建选项及其影响的详细信息，请参阅使用 C++test 项目
4. 指定项目的编译器设置。可以手动配置设置或指定编译器系列并点击自动检测来自动配置。您可以通过运行 cpptestcli 并使用 -list-compilers 选项来查看支持的编译器列表。
   
5. 点击下一步，验证项目的结构和内容，并根据需要进行修改。 
    
   1. 第一个层级列出了将创建的所有项目。若要更改项目名称或将其他文件夹链接到项目，可右键点击项目名称，然后选择相应的快捷菜单命令。
   2. 第二个层级列出了将链接的所有文件夹。要更改文件夹的名称或避免将其包含在项目中，可右键点击文件夹名称并选择相应的快捷菜单命令。
   3. 在树结构更深层级中，将看到链接文件夹中的所有文件夹和文件。绿色标记用于指示 .bdf 文件中引用的文件。
6. 点击完成，完成向导设置，或点击下一步设置路径变量（可选）。如果设置路径变量：
   1. 启用使用 PATH 变量来定义链接文件夹的位置 (如果适用) 选项，在链接的文件夹中使用路径变量，并从 PATH 变量列表菜单中选择一个预定义的路径变量或自定义的路径变量。如果选择自定义的路径变量，应在相应字段中手动输入路径变量名称和值。
   2. 点击完成，C++test 将在指定位置创建指定项目。该项目将包括已扫描选项的所有源文件，并且应正确设置项目属性
      
      

通过命令行创建项目

您还可以在命令行模式下运行 cpptestcli 时使用 -bdf <cpptestscan.bdf>来创建基于 BDF 的项目。

如果要在创建项目后立即执行分析（例如，静态分析和/或测试生成），应确保 cpptestcli 命令使用 -config 来调用首选测试配置。例如：

cpptestcli -data "</path/to/workspace>" -resource "<projectname>" -config "team://Team Configuration"  -settings "</path/to/name.properties>" -bdf  "</path/to/name.bdf>"

如果您只是想创建项目（不执行任何分析），可省略 -config。例如：

cpptestcli -data "</path/to/workspace>" -resource "<projectname>" -settings "</path/to/name.properties>" -bdf  "</path/to/name.bdf>"

请注意，-config "util/CreateProjectOnly" 之前用于创建项目而不进行测试，在当前的 C/C++test 版本中已不再使用。不再支持测试配置“util/CreateProjectOnly”。

您可以在纯文本选项文件中定义自定义项目设置，这些设置将通过 -settings 选项传递给 cpptestcli。可以根据设置（选项）文件中的说明在选项文件中指定设置。

示例

以下示例演示如何在命令行使用 cpptestscan 创建 C/C++test 项目。实例中使用与 C/C++test 一起提供的 ATM 示例项目（<INSTALL_DIR>/examples）。

这些示例使用基于 make 的构建；但是，可以通过任何构建系统生成 .bdf 文件。

假设与前提条件

• 必须将 cpptestscan 可执行文件添加到 PATH 环境变量中：

  <INSTALL_DIR>/bin/cpptestscan 

• 必须将 cpptestcli 可执行文件添加到 PATH 环境变量中： <INSTALL_DIR>/cpptestcli

• g++ 被视为原始编译器可执行文件。
• 工作空间和 .bdf 文件位置必须以指定 shell/命令提示符支持的格式输入。例如：
  • /home/MyWorkspace on UNIX/Cygwin
  • c:\home\MyWorkspace on Windows
  • c:/home/MyWorkspace on Cygwin
• 若要在不执行任何测试的情况下创建项目，应省略 -config
• 要创建和测试新项目，应使用相应的测试配置（例如，-config Must-HaveRules）。
• 将执行完整的项目重建（“clean all”）来确保所有对象都构建到 make 运行中

示例 1 - 使用默认设置在工作空间位置创建 C++test 项目

1. 基于原始 Makefile 创建构建数据文件（.bdf）：
   1. 前往 <INSTALL_DIR>/examples/ATM 目录。
   2. 构建 ATM 项目，同时在原始编译器可执行文件前添加 cpptestscan 可执行文件前缀：
      > make CC="cpptestscan g++" clean all
   3. 注意，在 <INSTALL_DIR>/examples/ATM 目录中创建了一个新的数据文件 （cpptestscan.bdf）。
2. 基于构建数据文件（.bdf）创建 C/C++test 项目：
   1. 使用 C/C++test 的 CLI 模式在 /home/MyWorkspace 工作空间创建一个新项目：
      > cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf
   2. 注意，在 MyWorkspace 位置创建了一个新的 C++test 项目（ATM）。它包含原始 <INSTALL_DIR>/examples/ATM 项目的所有源文件和构建选项。

示例 2 - 在原始项目的位置创建一个 C++test 项目，将“Visual C++7.1”设置为编译器，将“myProject”设置为项目名称

1. 基于原始 Makefile 创建构建数据文件（.bdf）：
   1. 前往 <INSTALL_DIR>/examples/ATM 目录。
   2. 构建 ATM 项目，同时在原始编译器可执行文件前添加 cpptestscan 可执行文件前缀：
      > make CC="cpptestscan --cpptestscanProjectName=myProject g++" clean all
   3. 注意，在 <INSTALL_DIR>/examples/ATM 目录中创建了一个新的数据文件 （cpptestscan.bdf）。注意，myProject 已设置为项目名称。
2. 基于构建数据文件（.bdf）创建 C/C++test 项目：
   • 首先，重写默认设置：
     1. 在 <INSTALL_DIR>/examples/ATM 创建一个名为 opts.properties 的纯文本选项文件。
     2. 在 opts.properties 文件中输入 bdf.import.compiler.family=vc_7_1，将编译器系列设置为 Visual C++ 7.1。
     3. 在 opts.properties 文件中输入：
        bdf.import.location=BDF_LOC，将目标项目位置更改为 cpptestscan.bdf 文件的位置（位于原始项目目录中）
   • 接下来，使用 C++test 的 CLI模式 在 /home/MyWorkspace workspace:
     cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf -settings opts.properties 中创建一个新项目
   • 最后，可以发现，在 <INSTALL_DIR>/examples/ATM 位置创建了一个新的 C++test 项目（myProject），其中包含 <INSTALL_DIR>/examples/ATM 原始项目的所有源文件和构建选项，并且将 Visual C++7.1 设置为编译器系列。

注意：

• 此示例中使用了支持的编译器列表中的 vc_7_1。如需使用自定义编译器，可在 C++test 首选项面板中指定路径（配置> 自定义目录> 自定义编译器）。详细信息请参阅使用交叉编译器配置测试。
• BDF_LOC 变量用作项目位置；该位置指的是 cpptestscan.bdf 文件的位置

生成的构建数据文件之后可用于在 GUI 或命令行创建项目。

将 C/C++test 集成到 CMake 构建中

C/C++test 提供了一个 CMake 扩展，您可以直接在 CMakeLists.txt 构建文件中使用 CMake 语法定义 C/C++test 项目。该扩展包含用于定义 C/C++test 项目的 cpptest_add_executable() CMake 函数，包括定义项目位置、结构和内容。因此，C/C++test 项目定义文件（.project 和 .parasoft）与构建数据文件（.bdf）在 CMake 构建期间自动生成。构建完成后，您可以将 C/C++test 项目文件和 BDF 导入工作空间以执行分析和测试。

对 CMake 集成的支持由以下组件组成：

• <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-project.cmake - 您需要添加到 CMakeFiles.txt 构建文件中以提供 C/C++test 项目定义的 CMake C/C++test 扩展。
• <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest.templates/*.in - 一组用于自动生成的项目定义文件的 C/C++test 模板，允许您高度自定义 CMake 的扩展。

此外，<CPPTEST_INSTALL_DIR>/examples/CMakeProject 目录包含一个使用 C/C++test 扩展与 CMake 集成的示例项目。

要求

• CMake 3.10或更高版本

工作流程概要

1. 在 CMakeLists.txt 构建文件中包含 <INSTALL_DIR>/integration/cmake/cpptest-project.cmake。
2. 使用 cpptest_add_executable() 函数来定义代表您的 C/C++test 项目的目标（详细信息请参阅定义 C/C++test 项目）。
3. 使用 CPPTEST_PROJECT=ON 变量激活 C/C++test 扩展并使用 configure 和 build 命令运行 CMake 来生成 C/C++test 项目配置文件。
4. 通过 UI 或命令行（-import <ROOT_FOLDER_OR_PROJECT_FILE>）将自动生成的 C/C++test 项目导入到您的 Eclipse 工作空间中（导入> 常规> 现有项目到工作空间中）。
5. 创建测试用例并配置桩函数。详细信息请参阅测试创建和执行。
6. 运行单元测试。

如果您的测试工件（如测试用例或桩函数）存储在源码控制系统中，请勿签入自动生成的项目定义文件或构建数据文件（.bdf）。这些文件应该在每次构建 CMake 项目时生成。

定义 C/C++test 项目

要让 CMake 自动生成 C/C++test 项目文件，必须使用 cpptest_add_executable() 函数定义一个代表您的 C/C++test 项目的目标。至少需要配置：

• 目标的名称。
• 要添加到 C/C++test 项目中的所有源文件。
• 使用常规 CMake 函数的构建选项和依赖项（外部库），例如 target_include_directories() 或 target_link_libraries()。

可选择以下选项：

cpptest_add_executable(
<target_name>
[CPPTEST_COMPILER_ID <compiler_id>]
[CPPTEST_PROJECT_NAME <test_project_name>]
[CPPTEST_PROJECT_LOC <test_project_location>]
[CPPTEST_PROJECT_FOLDERS <name1=location1> <name2=location2> ...]
[EXCLUDE_FROM_ALL]
SOURCES <src1.cpp> <src2.cpp> ... | TARGETS <target1> <target2> ...
)

与 CMake 集成的示例

该部分展示了使用 <CPPTEST_INSTALL_DIR>/examples/CMakeProject 目录中的示例项目与 CMake 集成的步骤。

1. 前往 <CPPTEST_INSTALL_DIR>/examples/CMakeProject。
2. 如果您使用的编译器不是默认的 GNU GCC 9 (x64)，应在 modules/mod1/CMakeLists.txt 和 <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-project.cmake 中将默认的编译器标识符 gcc_9-64 替换为您的编译器标识符。

3. 使用以下命令构建示例项目：

   > cd <CPPTEST_INSTALL_DIR>/examples/CMakeProject
   > mkdir build
   > cd build
   > cmake -DCPPTEST_PROJECT=ON ..
   > make

   CMake 将构建该项目并生成 C/C++test 项目。以下 CMakeLists.txt 文件定义了 C/C++test 项目（具有不同的项目布局和配置选项）：

   - app/CMakeLists.txt
   - modules/mod1/CMakeLists.txt
   - tests/cpptest_modules/CMakeLists.txt
4. 在安装 C/C++test 的 IDE 中打开一个空的工作空间。
5. 从 IDE 菜单中选择文件> 导入> 常规> 现有项目到工作空间中并找到 <CPPTEST_INSTALL_DIR>/examples/CMakeProject 目录，将三个自动生成的项目导入到 IDE 中。
6. 使用 builtin://Generate Unit Tests 测试配置生成测试用例。
7. 使用 builtin://Run Unit Tests 测试配置执行测试用例。