polyspace.target Class

Namespace: polyspace

(Python) Manage host compilers or manage hardware targets for running C/C++ tests using Polyspace Test

Since R2026a

Description

This Python^® class allows you to manage host compilers, and register, unregister or configure hardware targets for building and running tests authored using Polyspace^® Test™.

Creation

Syntax

compilers = polyspace.target.getHostCompilers()

currentCompiler = polyspace.target.getCurrentHostCompiler()

polyspace.target.setHostCompiler(hostCompilerName)

polyspace.target.registerFromFile(targetRegistrationFile)

polyspace.target.unregisterFromFile(targetUnregistrationFile)

polyspace.target.removeComponent("Toolchain", toolchainName)

polyspace.target.removeComponent("Processor", processorName)

polyspace.target.removeComponent("Board", boardName)

toolchains = polyspace.target.getToolchainNames()

processors = polyspace.target.getProcessorNames()

boards = polyspace.target.getBoardNames()

board = polyspace.target.getBoard(boardName)

polyspace.target.checkTargetPackage(checkGroup, toolchainName, boardName)

Description

Manage Host Compilers

compilers = polyspace.target.getHostCompilers() returns all supported host compilers. For more information on host compilers, see Specify C/C++ Compilers for Testing in Polyspace Platform User Interface.

currentCompiler = polyspace.target.getCurrentHostCompiler() returns the currently active host compiler.

polyspace.target.setHostCompiler(hostCompilerName) sets hostCompilerName as the compiler to be used for host compilation.

Register and Unregister Targets

polyspace.target.registerFromFile(targetRegistrationFile) registers an execution target using the custom target registration file targetRegistrationFile. Once a target is registered, you can use board and toolchain names from the target.

polyspace.target.unregisterFromFile(targetUnregistrationFile) unregisters components in a previously registered target using the custom target unregistration file <targetUnregistrationFile>.

Remove Targets

polyspace.target.removeComponent("Toolchain", toolchainName) removes a previously registered toolchain toolchainName and all associated components.

polyspace.target.removeComponent("Processor", processorName) removes a previously registered processor processorName and all associated components.

polyspace.target.removeComponent("Board", boardName) removes a previously registered board boardName and all associated components.

Get Registered Targets

toolchains = polyspace.target.getToolchainNames() returns the names of all currently registered toolchains as a list of strings.

processors = polyspace.target.getProcessorNames() returns the names of all currently registered processors as a list of strings.

boards = polyspace.target.getBoardNames() returns the names of all currently registered boards as a list of strings.

Configure Targets

board = polyspace.target.getBoard(boardName) returns a polyspace.target.Board object that can be used to set configurable properties of a board. To set a property propertyName of an object myBoard to the value propertyValue, use the syntax myBoard.Properties["propertyName"]=propertyValue.

Check Targets

polyspace.target.checkTargetPackage(checkGroup, toolchainName, boardName) runs a group of checks checkGroup on the target package indicated by toolchainName and boardName.

Input Arguments

Manage Host Compilers

hostCompilerName — Name of host compiler

string

Name of host compiler. For more information on host compilers, see Specify C/C++ Compilers for Testing in Polyspace Platform User Interface.

To get the names of all compilers supported as host compilers, use the command:

hostCompilers = polyspace.target.getHostCompilers()

This returns the supported host compilers as a list of polyspace.target.HostCompiler objects with properties Name and ShortName. Use the ShortName property of an object to set the corresponding host compiler as active, for instance:

polyspace.target.setHostCompiler(hostCompilers[0].ShortName)

Register and Unregister Targets

targetRegistrationFile — MATLAB^® file for target registration

string

Path to MATLAB file for custom target registration.

For more information on writing the target registration file, see Create Target Registration Packages for C/C++ Test Execution on Targets.

targetUnregistrationFile — MATLAB file for target unregistration

string

Path to MATLAB file for custom target unregistration.

For more information on writing the target unregistration file, see Create Target Registration Packages for C/C++ Test Execution on Targets.

Configure, Check, or Remove Targets

toolchainName — Name of toolchain

string

Name of previously registered toolchain.

To get the names of all registered toolchains, use the command:

toolchains = polyspace.target.getToolchainNames()

boardName — Name of board

string

Name of previously registered board.

To get the names of all registered boards, use the command:

boards = polyspace.target.getBoardNames()

processorName — Name of processor

string

Name of previously registered processor.

To get the names of all registered processors, use the command:

processors = polyspace.target.getProcessorNames()

checkGroup — Group of checks

polyspace.target.TargetPackageChecks object

Group of checks to run on a target, specified as a polyspace.target.TargetPackageChecks enumeration using one of these values:

• polyspace.target.TargetPackageChecks.TOOLCHAIN – Build a simple source file using the toolchain specified in the target and check if the build leads to errors.

• polyspace.target.TargetPackageChecks.BOARD – Run a simple addition application on the board specified in the target, get the execution results, and check if the results of the addition are as expected.

• polyspace.target.TargetPackageChecks.BOARD_USING_PSTUNIT – Build a simple source and xUnit test file using the toolchain and board information specified in the target, run the resulting application on the target, and check if the build leads to errors.

• polyspace.target.TargetPackageChecks.ALL – Run all previous checks.

Output Arguments

Manage Host Compilers

compilers — List of host compilers

List of polyspace.target.HostCompiler objects

Supported host compilers, returned as a list of polyspace.target.HostCompiler objects. Each object in the list has these properties.

Name	Value	Description
Name	str value	Full name of compiler. Example: "Microsoft Visual C++ 2017 v15.0"
ShortName	str value	Short name of compiler. To set a compiler as active host compiler, specify the short name with the function polyspace.target.setHostCompiler(). Example: "MSVC2017"

currentCompiler — Currently active host compiler

polyspace.target.HostCompiler object

Currently active host compiler, returned as a polyspace.target.HostCompiler object with properties Name and ShortName. For more information on the properties, see compilers.

Get Registered Targets

boards — Currently available boards

List of strings

Currently available boards returned as a list of strings.

toolchains — Currently available toolchains

List of strings

Currently available toolchains returned as a list of strings.

processors — Currently available processors

List of strings

Currently available processors returned as a list of strings.

board — Board with configurable properties

polyspace.target.Board object

Board with configurable properties, returned as a polyspace.target.Board object with these properties:

Name	Value	Description
Name	str value	Name of board
Properties	polyspace.target.BoardPropertiesMap object	Map of configurable properties of the board to their respective values. Suppose you are connecting to a hardware board using a TCP/IP connection and want to specify the IP address and port number that the board is using. You can get the board object and specify these properties as follows: board = polyspace.target.getBoard("myBoard") board.Properties["IPAddress"] = "192.168.1.123" board.Properties["Port"] = "8080"

Examples

Change Host Compiler

This example shows how to set a host compiler for building tests on your computer using Polyspace Test. Suppose your current host compiler is set to MinGW and you want to change the compiler to Microsoft^® Visual C++^® 2019. You can change the host compiler using the polyspace.target class.

Prior to starting the example, make sure you can import the polyspace.target module on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace.

1. Import the required module:

   import polyspace.target
   

2. Find the host compiler that is currently used for building tests.

   currentCompiler = polyspace.target.getCurrentHostCompiler()
   print(currentCompiler)

   You can see the following compiler name:

   {
       Name: 'MinGW64'
       ShortName: 'MinGW64'
   }

3. Find all compilers that can be used as host compilers. If the Name property of the compiler contains the strings Visual and 2019, set the compiler as host compiler using its ShortName property.

   compilers = polyspace.target.getHostCompilers()
   for idx, obj in enumerate(compilers):
       if "Visual" in obj.Name and "2019" in obj.Name:
           polyspace.target.setHostCompiler(obj.ShortName)

4. Find the current host compiler again.

   currentCompiler = polyspace.target.getCurrentHostCompiler()
   print(currentCompiler)

   This time, you can see the changed compiler name:

   {
       Name: 'Microsoft Visual C++ 2019 v16.0'
       ShortName: 'MSVC2019'
   }

Add Target and Build Tests on Target

This example shows how to register a target board and toolchain in Polyspace Test and then build and run tests using the registered target.

Prior to starting the example:

• Make sure you can import the polyspace.project, polyspace.test and polyspace.target modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace.

• If you are running the scripts in Linux^®, set the environment variable LD_LIBRARY_PATH to <polyspaceroot>\bin\<arch>, where <polyspaceroot> is the Polyspace installation folder and the subfolder name <arch> corresponds to your Linux installation, for instance, glnxa64 for 64-bit x86-based Linux.

1. Import the required modules:

   import polyspace.project
   import polyspace.test
   import polyspace.target
   import os
   

2. Register the target defined in a target registration file customPackage.m:

   registrationFile = os.path.join(
       polyspace.__install_path__,
       "polyspace",
       "examples",
       "doc_pstest",
       "execute_on_target",
       "customPackage.m"
   )
   polyspace.target.registerFromFile(registrationFile)

   The target registration file specifies a board with name myTarget and a toolchain with name myToolchain. You can set this board and toolchain in a project build configuration to build tests using the toolchain and run them on the board.

3. Create a new project and add a file factorial.c to the project:

   proj = polyspace.project.Project("myProj")
   proj.Code.Files.add(exampleSourceFile)
   

   The file contains a C function factorial() with the signature

   long long factorial (int n);

4. Set the board and toolchain in the active build configuration of the project to the names of the board and toolchain registered earlier:

   proj.ActiveBuildConfiguration.Board = "myTarget"
   proj.ActiveBuildConfiguration.Toolchain = "myToolchain"

5. Parse the source code in the project and write a test for the factorial() function in the file:

   codeInfo = polyspace.project.parseCode(proj)
   suite = proj.TestSuites.create("factorialSuite")
   test = suite.TestCases.create("factorialTest")
   funcToTest = codeInfo.getFunctionBySignature("long long factorial(int)")
   testStep = test.TestSteps.createTabular("factorialTwo", funcToTest)
   testStep.Inputs["n"].Value = "2"
   testStep.Assessments["pst_call_out"].Value = "2"

6. Build and run the test on the target and print the number of passing suites:

   testRes = polyspace.test.run(proj)
   print(testRes.SuitesPassed)

7. Unregister the target using the file customPackageRemove.m:

   unregistrationFile = os.path.join(
       polyspace.__install_path__,
       "polyspace",
       "examples",
       "doc_pstest",
       "execute_on_target",
       "customPackageRemove.m"
   )
   polyspace.target.unregisterFromFile(unregistrationFile)

Version History

Introduced in R2026a