Configure Template Toolchains for Testing

R2026b

To build a Polyspace^® Platform project, you can select a template toolchain as the compilation toolchain for testing. Template toolchains are predefined toolchains that require only minimal configuration before they can be used for project build.

To use a template toolchain for testing, you select it for the option Compilation toolchain (Testing) and then configure it by providing the paths to the compiler executables on your system. You can also specify that the same toolchain be used for static analysis using Polyspace Bug Finder™ or Polyspace Code Prover™.

What Are Template Toolchains

Template toolchains are predefined, ready-to-use toolchain definitions that Polyspace ships for specific standard and cross-compilers. Unlike custom-registered toolchains, template toolchains do not require you to write a target registration file or create a toolchain definition from scratch. Instead, the toolchain structure is already defined and you only need to provide the location of the compiler executables on your system.

When you set the option Compilation toolchain (Static Analysis) (Polyspace Bug Finder) to Same as testing toolchain, the static analysis tools automatically derive the compiler information from the template toolchain that you selected for testing. This means you configure the toolchain once and use it for both dynamic testing and static analysis.

The internals of a template toolchain cannot be edited. To edit the internals of a template toolchain, duplicate it from the Manage Toolchains window to create an editable copy. The duplicated toolchain is a custom toolchain with environment variable references removed, allowing you to specify your own commands and paths.

Select and Configure Template Toolchain

Selecting a template toolchain is simpler than defining a toolchain from scratch because the toolchain structure, including compiler commands, linker commands, and build rules, is already predefined. You only need to provide the paths to the compiler executables on your machine.

If you create a project from a build command that invokes compiler executables corresponding to one of the supported template toolchains, the template toolchain is automatically configured with required path information.

To configure a template toolchain manually:

1. On the Projects pane, double-click the Configuration node of your project.

2. On the Build tab, select the Target and Compiler node.

3. For the option Compilation toolchain (Testing), select a template toolchain from the dropdown list. Template toolchains appear below a separator, after the host toolchains and any registered toolchains.

4. Next to the Compilation toolchain (Testing) option, click Edit toolchain options to open the Edit toolchain options dialog box.

5. Provide the required paths or setup information. The fields that appear in the dialog box depend on the type of template toolchain. See Types of Template Toolchains.

   The option Setup Command is common to all template toolchains and allows you to specify the path to a script (for instance, a batch file in Windows^®). This script is called prior to compiler invocation when you build a project using the toolchain.

6. Click OK.

7. After configuring a template toolchain, verify that the toolchain is correctly set up by clicking Test Connection. This action builds a simple test using the configured toolchain and confirms whether the configuration is successful.

The configuration values that you provide in the Edit toolchain options dialog box are saved at the build configuration level. Each build configuration can have its own toolchain variable values, which allows you to test with different compiler versions in different build configurations within the same project.

Selecting a template toolchain does not automatically change your Target board name (Testing). If you select a cross-compiler template toolchain and want to run tests on target, you must set the board separately.

Note

If you attempt to parse or build with a template toolchain that is not configured, you get an error. Make sure that you configure the required paths before building. For information on possible errors, see Errors When Using Template Toolchains.

Types of Template Toolchains

Template toolchains fall into two categories based on the type of compiler they represent. The configuration fields that you must provide differ for each category.

Standard Compilers

Standard compiler template toolchains correspond to commonly used host compilers. There are two styles of standard compiler toolchains:

• GCC and Clang-based toolchains (gnu, clang) — For these toolchains, you specify the full path to each build tool executable: the C compiler, C++ compiler, linker, archiver, and assembler. This is necessary because these compilers can have different executable names depending on the installation (for example, gcc, arm-none-eabi-gcc, or qcc).

  In the Edit toolchain options dialog box, you see these fields:

  Field	Description
  C Compiler path	Full path to the C compiler executable (required)
  C++ Compiler path	Full path to the C++ compiler executable
  C Linker path	Full path to the C linker executable (required)
  C++ Linker path	Full path to the C++ linker executable
  Archiver path	Full path to the archiver executable (required)
  Assembler path	Full path to the assembler executable

• Visual-based toolchains (visual) — For these toolchains, you specify a setup command that initializes the compiler environment, along with the compiler name. The setup command is typically the vcvarsall.bat script provided by Microsoft^® Visual Studio^®. Visual-based toolchains are supported only on Windows.

  In the Edit toolchain options dialog box, you see these fields:

  Field	Description
  Setup Command	Full path to the Visual Studio environment setup script, for example, C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvarsall.bat (required)
  Setup Command arguments	Arguments for the setup command, for example, x64
  C/C++ Compiler executable	Compiler executable name, for example, cl for the Microsoft compiler or icx for the Intel compiler
  Assembler executable	Assembler executable name, for example, ml.exe

Specialized Cross-Compilers

Specialized cross-compiler template toolchains correspond to embedded and cross-compilation toolchains such as Wind River^® Diab, IAR Embedded Workbench, ARM^®, Green Hills^®, Renesas^®, TASKING, Texas Instruments^®, and others. For these toolchains, the executable names are known and you only need to specify the folder that contains the compiler binaries.

Because these compilers support multiple target architectures, a separate template toolchain is provided for each compiler-target combination. For instance, the Diab compiler has separate template toolchains for diab - arm, diab - powerpc, diab - tricore, and so on.

In the Edit toolchain options dialog box, you see these fields:

Field	Description
Folder	Full path to the folder that contains the compiler and other build tool executables (required)
Setup Command	Full path to an optional setup script that runs before the build
Setup Command arguments	Arguments for the optional setup script

For the full list of available cross-compiler template toolchains and their supported targets, see Compilation toolchain (Testing).

Configure Template Toolchains Using System Environment Variables

Instead of configuring a template toolchain through the Edit toolchain options dialog box in each build configuration, you can set system environment variables to configure the toolchain at the system level. When you set system environment variables, the configuration applies to all projects and build configurations by default, and is also available when using Polyspace Test™ at the command line. Build configuration-level values, if specified, take precedence over system environment variables.

Each template toolchain uses a set of environment variables with a common prefix PS_<TC_KEY>_, where <TC_KEY> is derived from the compiler name by converting it to upper case. For example, the prefix for gnu is PS_GNU and the key for visual is PS_VISUAL.

Environment Variables for GCC and Clang-Based Toolchains

For GCC-based and Clang-based template toolchains, set these environment variables:

Environment Variable	Description
PS_<TC_KEY>_C_COMPILER	Full path to the C compiler executable (required)
PS_<TC_KEY>_CPP_COMPILER	Full path to the C++ compiler executable
PS_<TC_KEY>_C_LINKER	Full path to the C linker executable (required)
PS_<TC_KEY>_CPP_LINKER	Full path to the C++ linker executable
PS_<TC_KEY>_ARCHIVER	Full path to the archiver executable (required)
PS_<TC_KEY>_ASSEMBLER	Full path to the assembler executable

For example, to configure the gnu template toolchain on Linux^®, you can set the following:

PS_GNU_C_COMPILER=/usr/bin/gcc
PS_GNU_CPP_COMPILER=/usr/bin/g++
PS_GNU_C_LINKER=/usr/bin/gcc
PS_GNU_CPP_LINKER=/usr/bin/g++
PS_GNU_ARCHIVER=/usr/bin/ar
PS_GNU_ASSEMBLER=/usr/bin/as

The above indicate typical paths for a default GCC installation and might be different for your system.

Environment Variables for Visual-Based Toolchains

For Visual-based template toolchains, set these environment variables:

Environment Variable	Description
PS_<TC_KEY>_SETUP_COMMAND	Full path to the Visual Studio environment setup script (required)
PS_<TC_KEY>_SETUP_COMMAND_ARG	Arguments for the setup command, for example, x64
PS_<TC_KEY>_COMPILER_NAME	Compiler executable name, for example, cl or icx
PS_<TC_KEY>_ASSEMBLER	Full path to the assembler executable

For example, to configure the visual template toolchain on Windows, you can set:

PS_VISUAL_SETUP_COMMAND=C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvarsall.bat
PS_VISUAL_SETUP_COMMAND_ARG=x64
PS_VISUAL_COMPILER_NAME=cl

The above indicate typical paths for a default Microsoft Visual Studio installation and might be different for your system.

Environment Variables for Cross-Compiler Toolchains

For specialized cross-compiler template toolchains, set this environment variable:

Environment Variable	Description
PS_<TC_KEY>_<TARGET>_FOLDER	Full path to the folder that contains the compiler binaries (required)

For example, to configure the diab - arm template toolchain, you can set:

PS_DIAB_ARM_FOLDER=/opt/windriver/diab/7.0/bin

Errors When Using Template Toolchains

When using template toolchains, you might encounter these errors:

• If you attempt to parse or build with a template toolchain and the required paths or environment variables are not set, you get an error like the following:

  The compilation toolchain 'greenhills - arm' is not fully configured. The following required setting is missing: 'Folder'

  Make sure that you have configured the toolchain either through the Edit toolchain options dialog box or through system environment variables.

• If you select a cross-compiler template toolchain and the Target board name (Testing) is set to Host Computer, you get an error like the following when you try to parse code or build the project:

  The compilation toolchain 'greenhills - arm' uses a cross-compiler and cannot generate an executable for 'Host Computer'. 
  Select a target board that is compatible with this toolchain.

  Set the option Target board name (Testing) to a board that is compatible with the toolchain or to None. If you set the board to None, you can parse the source code in the project and build the project but cannot run the tests.