In this section:

Introduction

You can use the cpptestscan or cpptesttrace utility to create a C++test project that you would normally build using tools such as GNU make, CMake, and QMake. The utilities collect information from the build process of an existing code base that C++test can use to automatically create a project. You can also build a project and manually configure it using the information collected by the utilities.

...

Build Data File

...

(.bdf)

Build information, such as the working directory, command line options for the compilation, and link processes of the original build, are stored in a file called the build data file. The following example is a fragment from a build data file:

...

• Manually setting up 'Use options from the build data file' as the options source for the project and selecting appropriate build data file (see Creating a Project from the GUI).
• Using the GUI to automatically import a project. See Importing project using Build Data File with the GUI wizard.

• Using the command line to automatically import a project. See Importing a Project from the Command Line.

  Note
  title Note
  Required environment variables can also be stored in the build data file if the following apply: Your build system sets up the required environment variables for the compiler / linker to work correctly These variables are not available in the environment when run C++tests. See description of the '--cpptestscanEnvInOutput' option below.

Using cpptestscan or cpptesttrace to Create a Build Data File

Anchor
using_cpp using_cpp

...

--
cpptestscanOutputFile= 
<OUTPUT_FILE>

--
cpptesttraceOutputFile=
<OUTPUT_FILE>

Example: Modifying GNU Make Build Command to Using cpptestscan

Assuming that a make-based build in which the compiler variable is CXX and the original compiler is g++:

...

Example: Modifying GNU Make Build Command Using cpptesttrace

Assume that a regular make-based build is executed with:

...

Example: Modifying GNU Makefile to use cpptestscan

If your Makefile uses CXX as a variable for the compiler executable and is normally defined as CXX=g++, you can redefine the variable:

...

Example: Using cpptesttrace with CMake build

Assuming that you have a CMake-based build, you can produce a build data file using cpptesttrace:

...

A build data file will be generated in the location defined by the CPPTEST_SCAN_OUTPUT_FILE variable. If the varialbe is isn’t set, the build data file(s) will be generated in the Makefiles’ locations.

Example: Using cpptestscan with CMake build

All scripts and commands are bash-based – adapt them as needed for different shells.

...

1. Use CMake to re-generate make files with the 'cpptestscan' used as a compiler prefix. Make sure the ‘cpptestscan’ executable is available on the PATH.

   1. If original CMake command is cmake -G “Unix Makefiles” ../project_root, then you need to get rid of existing CMake cache and run cmake overriding compiler variables. The following example assumes 'gcc' is used as a C compiler and 'g++' as a C++ compiler executable:

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

   2. Look in the CMakeCache.txt file to see if CMAKE_*_COMPILER variables point to cpptestscan.
   3. If the make files are re-generated,  jump to step 5. Continue if cmake failed in the boot-strap phase because the compiler wasn’t recognized.

2. Prepare the cpptestscan wrapper scripts that will behave like a CMake compiler by creating the following BASH scripts. In this example, we assume 'gcc' is used as a C compiler and 'g++' as a C++ compiler executable:

   Code Block
   >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 $?

    

   
   

   • The first script invokes cpptestscan to extract options without running the compiler. The second script runs the actual compiler so that the entire script looks and acts like a compiler in order to be “accepted” by CMake.
3. Give the scripts executable attributes and place them in a common location so they are acces-sible to everyone who needs to scan make files. Make sure the cpptestscan and the scripts are available on the PATH.
4. Use CMake to re-generate make files with the scripts used as compilers by extending the original CMake command with options that re-generate make files from the prepared scripts.

   • Original CMake command is cmake -G “Unix Makefiles” ../project_root then you need to get rid of existing CMake cache and run cmake overriding compiler vari-ables. In the following example, we assume 'gcc' is used as a C compiler and 'g++' as a C++ compiler executable:

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

   • Look in the CMakeCache.txt file to see if CMAKE_*_COMPILER variables point to prepared wrappers.

5. Setup environment variables for cpptestscan; make sure to use an absolute path for the out-put BDF file:

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

6. Run the project build normally without overwriting any make variables. Build data files(s) will be generated in location defined by the CPPTEST_SCAN_OUTPUT_FILE variable or - if not set -in location of Makefiles.

Using cpptestscan or cpptestrace with other Build Systems

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

...

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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/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>/Examplesexamples/ATM location,  containing all the source files and build options of the original <INSTALL_DIR>/Examplesexamples/ATM project,  having Visual C++ 7.1 set as compiler family.

...