Choose an Approach for Equivalence Testing Generated C++ Code - MATLAB & Simulink (original) (raw)

Main Content

You can write equivalence tests that use MATLAB® Coder™ to generate and test C++ code from MATLAB source code. Testing generated C++ code for equivalence with MATLAB source code can help mitigate unexpected behavior when you deploy the generated C++ code.

Alternatively, you can write equivalence tests that useMATLAB Compiler SDK™ to generate and test deployable C++ shared libraries from MATLAB source code (since R2024b). Conducting equivalence testing for deployable C++ shared libraries can help mitigate unexpected behavior when you deploy the C++ shared library in a C++ application.

This table compares the benefits of writing equivalence tests that generate C++ code and deployable C++ shared libraries.

Generate and Test C++ Code

To generate C++ code from MATLAB source code and test for equivalence:

1. Define a test class that inherits from the matlabtest.coder.TestCase class.
2. Create a test in the test class.
3. In the test, generate the C++ code by using the build method. Specify the language to use in the generated code as C++ by specifying the CodeGenerationArguments as{"-lang:c++"}.
4. Execute the C++ code by using the execute method.
5. Qualify the result by comparing the execution of the C++ code to the execution of the MATLAB source code by using methods such as verifyExecutionMatchesMATLAB. For more information, see Table of Qualifications for Equivalence Tests.
6. Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

Suppose that you want to generate code for a function called myAdd, which adds two inputs and outputs the result:

function y = myAdd(a,b) %#codegen y = a + b; end

This equivalence test builds C++ code for a MEX target with inputs set to (1,2). The test executes the C code with the same inputs used to build the code and verifies that the execution matches the MATLAB execution of the function.

classdef tEquivalenceCpp < matlabtest.coder.TestCase methods (Test)
function tMyAddCpp(testCase)
buildResults = build(testCase,"myAdd.m", ... CodeGenerationArguments={"-lang:c++"},Inputs={1,2}); executionResults = execute(testCase,buildResults); verifyExecutionMatchesMATLAB(testCase,executionResults); end end end

For more information, see Generate C/C++ Code and Test for Equivalence.

To collect coverage for the generated C++ code, configure the tests to generate a static library and use SIL or PIL verification. For more information about running the test, collecting coverage, and viewing the coverage results, see Collect Coverage for Generated C/C++ Code in Equivalence Tests.

Generate and Test C++ Code Using Multiple Entry-Point Functions or Functions with Multiple Signatures

You can generate C++ code from multiple entry-point functions or for functions that have multiple signatures. To generate code in these situations and test for equivalence with the MATLAB source code:

1. Define a test class that inherits from the matlab.unittest.TestCase class.
2. Create a test in the test class.
3. In the test, import the matlabtest.coder.MATLABCoderTester interface and the matlabtest.constraints.ExecutionMatchesMATLAB constraint.
4. Specify the language to use in the generated code as C++ by using thecoder.config (MATLAB Coder) function to create a coder.MexCodeConfig (MATLAB Coder) or coder.EmbeddedCodeConfig (MATLAB Coder) object, referred to as a code generation configuration parameter object. Specify the TargetLang property of the object as "C++".
5. Construct an instance of the matlabtest.coder.MATLABCoderTester class for your build type and provide one of the functions and build-time inputs by using one of these methods:
   • matlabtest.coder.MATLABCoderTester.forDLLCoderConfiguration
   • matlabtest.coder.MATLABCoderTester.forLIBCoderConfiguration
   • matlabtest.coder.MATLABCoderTester.forMEXCoderConfiguration
     Pass the code generation configuration parameter object to the equivalence test class constructor by using theConfiguration name-value argument.
6. Add additional functions or function signatures by using the addEntryPointFunction method.
7. Generate the C++ code by using the build method.
8. Execute the C++ code by using the execute method.
9. Qualify the result against the MATLAB execution of the function with the same inputs by using theverifyThat method and thematlabtest.constraints.ExecutionMatchesMATLAB constraint.
10. Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

This SIL equivalence test builds C++ code as a static library, and executes the code with inputs set to (1,2). The test verifies that the execution matches the MATLAB execution of the function.

classdef tFormalEquivalenceCpp < matlab.unittest.TestCase methods(Test) function tMyAddCpp(testCase) import matlabtest.coder.MATLABCoderTester import matlabtest.constraints.ExecutionMatchesMATLAB

        config = coder.config("lib","ecoder",true);
        config.TargetLang = "C++";
        tester = MATLABCoderTester.forLIBCoderConfiguration( ...
            "myAdd.m",Inputs={0,0},Configuration=config);
        
        build(tester,testCase);
        execute(tester,testCase,Inputs={1,2});
        verifyThat(testCase,tester, ...
            ExecutionMatchesMATLAB);          
    end
end

end

For more information, see Equivalence Test C/C++ Code for Multiple Entry-Point Functions and Function Signatures.

To collect coverage for the generated C++ code, configure the tests to generate a static library and use SIL or PIL verification. For more information about running the test, collecting coverage, and viewing the coverage results, see Collect Coverage for Generated C/C++ Code in Equivalence Tests.

Generate and Test Deployable C++ Shared Libraries

Since R2024b

To generate deployable C++ shared libraries and test for equivalence with the MATLAB source code:

1. Define a test class that inherits from the matlabtest.compiler.TestCase class.
2. Create a test in the test class.
3. Generate the deployable C++ shared library by using the build method. Specify the artifactType argument as"cppSharedLibrary".
4. Execute the deployed C++ shared library by using the execute method.
5. Qualify the result by comparing the execution of the deployed code artifact to the execution of the MATLAB source code by using methods such as verifyExecutionMatchesMATLAB. For more information, see Table of Qualifications for Equivalence Tests.
6. Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

classdef tEquivalenceCppSharedLibrary < matlabtest.compiler.TestCase methods (Test) function cppSimple(testCase) func = which("myAdd.m"); buildResults = build(testCase,func,"cppSharedLibrary"); executionResults = execute(testCase,buildResults,{1,2}); verifyExecutionMatchesMATLAB(testCase,executionResults); end end end

For more information, see Generate Deployed Code Artifacts and Test for Equivalence.

See Also

Classes

• matlabtest.coder.TestCase | matlabtest.coder.MATLABCoderTester | matlabtest.compiler.TestCase

Topics

• Generate C/C++ Code and Test for Equivalence
• Collect Coverage for Generated C/C++ Code in Equivalence Tests
• Equivalence Test C/C++ Code for Multiple Entry-Point Functions and Function Signatures
• Generate Deployed Code Artifacts and Test for Equivalence