...

Example: Using cpptesttrace with CMake build

...

For non-make based build systems, usage of cpptestscan and cpptesttrace is very similar to the examples shown above. Typically, a compiler is defined as a variable somewhere in the build scripts. To create a Build Data File from that build system using cpptestscan, prefix the original compiler executable with cpptestscan. To create a Build Data File from that build system using cpptesttrace, prefix whole build command line with cpptesttrace.

Importing Project Using Build Data File with the GUI Wizard

Anchor

...

Introduction

C/C++test ships with an extension for CMake that allows you to define C/C++test projects directly in the CMakeLists.txt build file, using the CMake syntax. The extension includes the cpptest_add_executable() CMake function for defining the C/C++test project, including the project location, structure, and content. As a result, the C/C++test project definition files (.project and .parasoft) and a build data file (.bdf) are automatically generated during the CMake build. When the build completes, you can import the C/C++test project files and the BDF into your workspace to perform analysis and testing.

Support for CMake integration consists of the following components:

• <CPPTEST_INSTALL_DIR>/integration/cmake/cmake/cpptest.cmake – the C/C++test extension for CMake you need to add to the CMakeFiles.txt build file to provide the C/C++test project definition.
• <CPPTEST_INSTALL_DIR>/integration/cmake/cmake/cpptest.templates/*.in – a set of C/C++test templates for automatically generated project definition files that allows you to highly customize the extension for CMake.

In addition, the <CPPTEST_INSTALL_DIR>/integration/cmake  directory inclues an example project to demonstrate integration with CMake using the C/C++test extention.

Requiremetns

• Linux 64-bit
• C/C++test Professional for Linux 64-bit
• CMake 3.10 or later

Workflow Overview

1. Add <INSTALL_DIR>/integration/cmake/cmake/cpptest.cmake to your CMakeLists.txt build file.
2. Use the cpptest_add_executable() function to define a target that represents your C/C++test project.
3. Run CMake  with the configure and build commands to generate C/C++test project configuration files.
4. Import the automatically generated C/C++test projects to your Eclipse workspace via the UI (Import> General> Existing Projects into Workspace) or command line (-import <ROOT_FOLDER_OR_PROJECT_FILE>).
5. Create test cases and configure stubs. See Test Creation and Execution for details.
6. Run unit tests.

If you store your test artifacts, such as test cases or stubs, in a source control system, do not check in the automatically generated project definition files or build data files (.bdf). These files should be generated every time your CMake project is build.

Defining the C/C++test Project

To enable CMake to automatically generate C/C++test project files, you must define a target that represents your C/C++test project in the cpptest_add_executable() function. At a minimum, you must must configure:

• the name of the target.
• all the source files you want to add to the C/C++test project.
• build options and dependencies (external libraries) using regular CMake functions, such as target_include_directories() or target_link_libraries().

The following options are available:

...

A target-specific C/C++test compiler identifier. To configure the same compiler for all your targets, specify the identifier in cpptest.cmake.

...

If specified, the the current target is excluded form the default all target.

...

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> ...
)

Example Integration with CMake

This section demonstates integration with CMake using the example project located in the <CPPTEST_INSTALL_DIR>/integration/cmake  directory.

1. Go to <CPPTEST_INSTALL_DIR>/integration/cmake.
2. If you use a compiler other than the default GNU GCC 9 (x64), replace the default compiler identifier gcc_9-64 with your compiler identifier in modules/mod1/CMakeLists.txt and cmake/cpptest.cmake.

3. Build the example project with the following commands:

   Code Block
   > cd <CPPTEST_INSTALL_DIR>/integration/cmake > mkdir build > cd build > cmake .. > make

   CMake will build the project and generate the C/C++test projects. The following CMakeLists.txt files define the C/C++test projects (with different project layout and configuration options):

   - app/CMakeLists.txt
   - modules/mod1/CMakeLists.txt
   - tests/cpptest_modules/CMakeLists.txt
4. Open an empty workspace in your IDE where C/C++test is installed.
5. Choose File> Import> General> Existing Projects into Workspace from the IDE menu and navigate to the the <CPPTEST_INSTALL_DIR>/integration/cmake directory to import the three automatically generated projects to your IDE.
6. Generate test cases with the builtin://Generate Unit Tests test configuration.
7. Execute test cases with the builtin://Run Unit Tests test configuration.

...

Once you have used cpptestscan or cpptesttrace to generate a build data file for code you want to test in C++test, you can use the Project Creation wizard to create a C++test project.

To create a project from a build data file:

...

• For details on the available project creation options and their impacts, see Working with C++test Projects

Importing project using Build Data File Importing project using Build Data File

Once you have used cpptestscan or cpptesttrace to generate a build data file for code you want to test in C++test, you can use the Project Creation wizard to create a C++test project.

To create a project from a build data file:

1. Open the wizard by choosing File> New> Project, select C++test> Create project from a build data file, then click Next. The wizard’s first page will display.
2. Complete the first wizard page, then click Next.
   • In the Build data file field, enter or browse to the location of the build data file that was previously created (as described in Using cpptestscan or cpptesttrace to Create a Build Data File).
   • In the Project location section, specify where you want the projects created. There are two possibilities: workspace and external location. If workspace is chosen, the projects will be created in subdirectories within the workspace location. If external location is chosen, single projects will be created directly in that location. If multiple projects are created, then subdirectories for each project will be created in the specified external location.
     • For details on the available project creation options and their impacts, see Working with C++test Projects
   • In the Compiler settings section, specify the compiler family. The other options will be set automatically.
     • To get a list of valid compiler family values, use the -list-compilers switch to cpptestcli
       
       Image Added
       
       
3. In the second wizard page, which displays a project tree with the projects that will be created, verify the project’s structure and content, making modifications as needed.
   • The first level lists all projects that will be created. To change the project’s name or link additional folders to the project, right-click the project name and choose the appropriate shortcut menu command.
   • The second level lists all folders that will be linked. To change a folder`s name or prevent it from being included in the project, right-click the folder name and choose the appropriate shortcut menu command.
   • Deeper in the tree, you will see all folders and files which are present in linked folders. A green marker is used to indicate files referenced in the .bdf file.
     
     Image Added
     
     
4. (Optional) In the third wizard page, set Path Variables if needed.
   • If you want Path Variables used in linked folders, check Use Path Variable to define linked folder locations (if applicable).
   • To use a pre-defined Path Variable, select it from the Path Variable list box.
   • To use a custom Path Variable, choose Custom from the Path Variable list box, then manually enter the Path Variable name and value in corresponding fields.
     
     Image Added
     
     

Click Finish. C++test will create the specified project(s) in the specified location. The project(s) will include all source files whose options were scanned, and project properties should be set up appropriately.

Creating a Project from the Command Line

Anchor
command_line command_line

You can also create a BDF-based projects in command line mode by using the -bdf <cpptestscan.bdf> switch to cpptestcli.

If you want to perform analysis (e.g., static analysis and/or test generation) immediately after the project is created, ensure that the cpptestcli command uses -config to invoke the preferred Test Configuration. For example:

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

If you simply want to create the project (without performing any analysis), omit  -config. For example:

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

Note that -config "util/CreateProjectOnly", which was previously used for creating a project without testing, is no longer used in the current version of C++test. The fake Test Configuration "util/CreateProjectOnly" is no longer supported.

You can define custom project settings in a plain text options file, which is passed to cpptestcli using the -localsettings switch. Settings can be specified in the options file as described in Local Settings (Options) Files.

Examples

The following examples demonstrate  how to create a C++test project from the command line using cpptestscan. They use C++test’s ATM example, which is available in the <INSTALL_DIR>/examples/ATM directory

The examples use a make-based build; however, a .bdf file can be produced from any build system.

Assumptions and Prerequisites

• The cpptestscan executable should be included on $PATH (it is located in C++test's installa-tion directory).
• The cpptestcli executable should be included on $PATH (it is located in C++test's installa-tion directory).
• g++ is assumed to be the original compiler executable.
• The workspace and .bdf file locations have to be entered in a format supported by the given shell/command prompt. For example:
  • /home/MyWorkspace on UNIX/Cygwin
  • c:\home\MyWorkspace on Windows
  • c:/home/MyWorkspace on Cygwin
• To create a project without performing any testing, omit -config
• To create and test the new project, use the appropriate test configuration (e.g. -config Must-HaveRules).
• A full project rebuild will be performed ("clean all") to ensure that all objects are built in the make run

Example 1 - Creating a C++test project in the workspace location with default settings

1. Create a build data file (.bdf) based on the original Makefile as follows:
   1. Go to the <INSTALL_DIR>/examples/ATM directory.
   2. Build the ATM project while prefixing the original compiler executable with the cpptestscan executable:
      > make CC="cpptestscan g++" clean all
   3. Note that a new data file (cpptestscan.bdf) was created in the <INSTALL_DIR>/examples/ATM directory.
2. Create a C++test project based on the build data file (.bdf)  as follows:
   1. Use C++test's CLI mode to create a new project in the /home/MyWorkspace workspace:
      > cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf
   2. Note that a new C++test project (ATM) was created in MyWorkspace location. It con-tains all the source files and build options of the original <INSTALL_DIR>/examples/ATM project.

Example 2 - Creating a C++test project in original project's location with "Visual C++ 7.1" set as the compiler and "myProject" set as the project name

1. Create a build data file (.bdf) based on the original Makefile as follows:
   1. Go to the <INSTALL_DIR>/examples/ATM directory.
   2. Build the ATM project while prefixing the original compiler executable with the cpptestscan executable:
      > make CC="cpptestscan --cpptestscanProjectName=myProject g++" clean all
   3. Note that a new data file (cpptestscan.bdf) was created in the <INSTALL_DIR>/examples/ATM directory. Notice that myProject was set as project name.
2. Create a C++test project based on the build data file (.bdf) as follows:
   • First, override the default settings:
     1. Create a plain text options file named opts.properties in <INSTALL_DIR>/examples/ATM.
     2. Set the compiler family to Visual C++ 7.1 by entering bdf.import.compiler.family=vc_7_1 into the opts.properties file.
     3. Change the destination project location to the location of the cpptestscan.bdf file (which is located in the original project's directory) by entering:
        bdf.import.location=BDF_LOC into opts.properties file
   • Next, use C++test's CLI mode to create a new project in the /home/MyWorkspace workspace:
     cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf -localsettings opts.properties
   • Finally, note that a New C++test project (myProject) was created in <INSTALL_DIR>/examples/ATM location,  containing all the source files and build options of the original <INSTALL_DIR>/examples/ATM project,  having Visual C++ 7.1 set as compiler family.

Notes:

• vc_7_1, which is listed among supported compilers, was used in this example. To use a custom compiler, you would need to specify its path in the C++test Preferences panel (Configurations> Custom directories> Custom compilers). See Configuring Testing with the Cross Compiler for details.
• The BDF_LOC variable was used as the project location; this refers to the cpptestscan.bdf file's location

The generated build data file can be then used to create a project from the GUI or from the command line.

Anchor
cmake_integration cmake_integration

Integrating C/C++test into a CMake Build

C/C++test ships with an extension for CMake that allows you to define C/C++test projects directly in the CMakeLists.txt build file, using the CMake syntax. The extension includes the cpptest_add_executable() CMake function for defining the C/C++test project, including the project location, structure, and content. As a result, the C/C++test project definition files (.project and .parasoft) and a build data file (.bdf) are automatically generated during the CMake build. When the build completes, you can import the C/C++test project files and the BDF into your workspace to perform analysis and testing.

Support for CMake integration consists of the following components:

• <CPPTEST_INSTALL_DIR>/integration/cmake/cmake/cpptest.cmake – the C/C++test extension for CMake you need to add to the CMakeFiles.txt build file to provide the C/C++test project definition.
• <CPPTEST_INSTALL_DIR>/integration/cmake/cmake/cpptest.templates/*.in – a set of C/C++test templates for automatically generated project definition files that allows you to highly customize the extension for CMake.

In addition, the <CPPTEST_INSTALL_DIR>/integration/cmake  directory includes an example project to demonstrate integration with CMake using the C/C++test extension.

Requirements

• Linux 64-bit
• C/C++test Professional for Linux 64-bit
• CMake 3.10 or later

Workflow Overview

1. Include <INSTALL_DIR>/integration/cmake/cmake/cpptest.cmake to your CMakeLists.txt build file.
2. Use the cpptest_add_executable() function to define a target that represents your C/C++test project (see Defining the C/C++test Project for details).
3. Run CMake  with the configure and build commands to generate C/C++test project configuration files.
4. Import the automatically generated C/C++test projects to your Eclipse workspace via the UI (Import> General> Existing Projects into Workspace) or command line (-import <ROOT_FOLDER_OR_PROJECT_FILE>).
5. Create test cases and configure stubs. See Test Creation and Execution for details.
6. Run unit tests.

If you store your test artifacts, such as test cases or stubs, in a source control system, do not check in the automatically generated project definition files or build data files (.bdf). These files should be generated every time your CMake project is built.

Anchor
cmake_target_options cmake_target_options

Defining the C/C++test Project

To enable CMake to automatically generate C/C++test project files, you must define a target that represents your C/C++test project with the cpptest_add_executable() function. At a minimum, you must must configure:

• the name of the target.
• all the source files you want to add to the C/C++test project.
• build options and dependencies (external libraries) using regular CMake functions, such as target_include_directories() or target_link_libraries().

The following options are available:

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> ...
)

Example Integration with CMake

This section demonstates integration with CMake using the example project located in the <CPPTEST_INSTALL_DIR>/integration/cmake  directory.

1. Go to <CPPTEST_INSTALL_DIR>/integration/cmake.
2. If you use a compiler other than the default GNU GCC 9 (x64), replace the default compiler identifier gcc_9-64 with your compiler identifier in modules/mod1/CMakeLists.txt and cmake/cpptest.cmake.

3. Build the example project with the following commands:

   Code Block
   > cd <CPPTEST_INSTALL_DIR>/integration/cmake > mkdir build > cd build > cmake .. > make

   CMake will build the project and generate the C/C++test projects. The following CMakeLists.txt files define the C/C++test projects (with different project layout and configuration options):

   - app/CMakeLists.txt
   - modules/mod1/CMakeLists.txt
   - tests/cpptest_modules/CMakeLists.txt
4. Open an empty workspace in your IDE where C/C++test is installed.
5. Choose File> Import> General> Existing Projects into Workspace from the IDE menu and navigate to the the <CPPTEST_INSTALL_DIR>/integration/cmake directory to import the three automatically generated projects to your IDE.
6. Generate test cases with the builtin://Generate Unit Tests test configuration.
7. Execute test cases with the builtin://Run Unit Tests test configuration

...

Click Finish. C++test will create the specified project(s) in the specified location. The project(s) will include all source files whose options were scanned, and project properties should be set up appropriately.

...

You can also create a BDF-based projects in command line mode by using the -bdf <cpptestscan.bdf> switch to cpptestcli.

If you want to perform analysis (e.g., static analysis and/or test generation) immediately after the project is created, ensure that the cpptestcli command uses -config to invoke the preferred Test Configuration. For example:

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

If you simply want to create the project (without performing any analysis), omit  -config. For example:

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

Note that -config "util/CreateProjectOnly", which was previously used for creating a project without testing, is no longer used in the current version of C++test. The fake Test Configuration "util/CreateProjectOnly" is no longer supported.

You can define custom project settings in a plain text options file, which is passed to cpptestcli using the -localsettings switch. Settings can be specified in the options file as described in Local Settings (Options) Files.

Examples

The following examples demonstrate  how to create a C++test project from the command line using cpptestscan. They use C++test’s ATM example, which is available in the <INSTALL_DIR>/examples/ATM directory

The examples use a make-based build; however, a .bdf file can be produced from any build system.

Assumptions and Prerequisites

• The cpptestscan executable should be included on $PATH (it is located in C++test's installa-tion directory).
• The cpptestcli executable should be included on $PATH (it is located in C++test's installa-tion directory).
• g++ is assumed to be the original compiler executable.
• The workspace and .bdf file locations have to be entered in a format supported by the given shell/command prompt. For example:
  • /home/MyWorkspace on UNIX/Cygwin
  • c:\home\MyWorkspace on Windows
  • c:/home/MyWorkspace on Cygwin
• To create a project without performing any testing, omit -config
• To create and test the new project, use the appropriate test configuration (e.g. -config Must-HaveRules).
• A full project rebuild will be performed ("clean all") to ensure that all objects are built in the make run

Example 1 - Creating a C++test project in the workspace location with default settings

1. Create a build data file (.bdf) based on the original Makefile as follows:
   1. Go to the <INSTALL_DIR>/examples/ATM directory.
   2. Build the ATM project while prefixing the original compiler executable with the cpptestscan executable:
      > make CC="cpptestscan g++" clean all
   3. Note that a new data file (cpptestscan.bdf) was created in the <INSTALL_DIR>/examples/ATM directory.
2. Create a C++test project based on the build data file (.bdf)  as follows:
   1. Use C++test's CLI mode to create a new project in the /home/MyWorkspace workspace:
      > cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf
   2. Note that a new C++test project (ATM) was created in MyWorkspace location. It con-tains all the source files and build options of the original <INSTALL_DIR>/examples/ATM project.

Example 2 - Creating a C++test project in original project's location with "Visual C++ 7.1" set as the compiler and "myProject" set as the project name

1. Create a build data file (.bdf) based on the original Makefile as follows:
   1. Go to the <INSTALL_DIR>/examples/ATM directory.
   2. Build the ATM project while prefixing the original compiler executable with the cpptestscan executable:
      > make CC="cpptestscan --cpptestscanProjectName=myProject g++" clean all
   3. Note that a new data file (cpptestscan.bdf) was created in the <INSTALL_DIR>/examples/ATM directory. Notice that myProject was set as project name.
2. Create a C++test project based on the build data file (.bdf) as follows:
   • First, override the default settings:
     1. Create a plain text options file named opts.properties in <INSTALL_DIR>/examples/ATM.
     2. Set the compiler family to Visual C++ 7.1 by entering bdf.import.compiler.family=vc_7_1 into the opts.properties file.
     3. Change the destination project location to the location of the cpptestscan.bdf file (which is located in the original project's directory) by entering:
        bdf.import.location=BDF_LOC into opts.properties file
   • Next, use C++test's CLI mode to create a new project in the /home/MyWorkspace workspace:
     cpptestcli -data /home/MyWorkspace -bdf cpptestscan.bdf -localsettings opts.properties
   • Finally, note that a New C++test project (myProject) was created in <INSTALL_DIR>/examples/ATM location,  containing all the source files and build options of the original <INSTALL_DIR>/examples/ATM project,  having Visual C++ 7.1 set as compiler family.

Notes:

• vc_7_1, which is listed among supported compilers, was used in this example. To use a custom compiler, you would need to specify its path in the C++test Preferences panel (Configurations> Custom directories> Custom compilers). See Configuring Testing with the Cross Compiler for details.
• The BDF_LOC variable was used as the project location; this refers to the cpptestscan.bdf file's location

...

1. .