build

Class: matlabtest.coder.TestCase
Namespace: matlabtest.coder

Generate C/C++ code in equivalence tests

Since R2023a

Syntax

buildResults = build(testCase,fcnName)

buildResults = build(___,Name=Value)

Description

buildResults = build(testCase,fcnName) generates C code using MATLAB^® for a MEX target from a function that requires no inputs, fcnName, in the equivalence test case testCase. In addition to generating the C code, build compiles the code and generates an executable.

buildResults = build(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes.

Input Arguments

testCase — Test case

matlabtest.coder.TestCase object

Test case, specified as a matlabtest.coder.TestCase object.

fcnName — Name of function to generate code for

string scalar | character vector

Name of function to generate code for, specified as a string scalar or character vector.

Example: "myAdd"

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: Inputs={1,2}

CodeGenerationArguments — Code generation options

cell array of string scalars | cell array of character vectors

Code generation options, specified as a cell array of string scalars or character vectors. Use values from the options (MATLAB Coder) input argument of the codegen (MATLAB Coder) function.

Example: CodeGenerationArguments={"-o","customMex"}

Configuration — Code generation build target type

"mex" (default) | "lib" | "dll" | coder.MEXCodeConfig object | coder.EmbeddedCodeConfig object

Code generation build target type, specified as "mex", "lib", "dll", or a coder.MexCodeConfig (MATLAB Coder) or coder.EmbeddedCodeConfig (MATLAB Coder) object.

Tip

Use a coder.MexCodeConfig (MATLAB Coder) or coder.EmbeddedCodeConfig (MATLAB Coder) object with this name-value argument to specify parameters such as the target language.

Inputs — Build-time inputs

cell array

Build-time inputs, specified as a cell array. Each element in the cell array corresponds to an input to the function.

Example: Inputs={1,2}

PreserveInFolder — Folder to preserve generated files in

string scalar | character vector

Folder to preserve generated files in, specified as a string scalar or character vector. The folder path can be relative or absolute. By default, the test case generates code in a temporary directory.

When you specify this name-value argument, MATLAB preserves the generated files regardless of the test result.

Note

When the equivalence test fails, MATLAB preserves the generated files regardless of whether or not you use this name-value argument.

Example: PreserveInFolder="equivalenceTests\artifacts"

Example: PreserveInFolder="C:\users\jdoe\MATLAB\equivalenceTests\artifacts"

Output Arguments

buildResults — Build results for generated C/C++ code in equivalence tests

matlabtest.coder.results.BuildResults object

Build results for generated C/C++ code in equivalence tests, returned as a matlabtest.coder.results.BuildResults object.

Examples

Generate C Code from Function with No Inputs and Test for Equivalence

This example shows how to generate C code from a MATLAB function that has no inputs and test for equivalence by using MATLAB Coder™.

The function helloWorld displays a string of text.

function y = helloWorld 
y = "Hello World!";
end

This class definition file defines an equivalence test case that inherits from matlabtest.coder.TestCase. The test case in the methods block defines a test case that:

1. Builds C code from the helloWorld function

2. Executes the C code with no inputs

3. Verifies the execution of the C code against the execution of the MATLAB function helloWorld

classdef tEquivalence < matlabtest.coder.TestCase
    methods (Test)
        function tHelloWorld(testCase)
            buildResults = build(testCase,"helloWorld");         
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

Run the tHelloWorld test.

runtests("tEquivalence", ...
    procedureName="tHelloWorld")

Running tHelloWorld
..
Done tHelloWorld
__________


ans = 
  TestResult with properties:

          Name: 'tEquivalence/tHelloWorld'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 2.8921
       Details: [1×1 struct]

Totals:
   1 Passed, 0 Failed, 0 Incomplete.
   2.8921 seconds testing time.

Generate and Test C Code for Equivalence

This example shows how to generate C code from a MATLAB function and test for equivalence by using MATLAB Coder.

The function myAdd takes two numbers as inputs, adds them together, and outputs the result.

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

This class definition file defines an equivalence test case that inherits from matlabtest.coder.TestCase. The test case in the methods block defines a test case that:

1. Builds C code from the myAdd function with inputs set to (0,0)

2. Executes the C code with inputs set to (1,2)

3. Verifies the execution of the C code against the execution of the MATLAB function myAdd with the same inputs and an absolute tolerance of 0.01

classdef tEquivalence< matlabtest.coder.TestCase
    methods (Test)
        function tMyAdd(testCase)
            buildResults = build(testCase,"myAdd", ...
                Inputs={0,0});         
            executionResults = execute(testCase,buildResults, ...
                Inputs={1,2});
            verifyExecutionMatchesMATLAB(testCase,executionResults, ...
                AbsTol=0.01)
        end
    end
end

Run the tMyAdd test.

runtests("tEquivalence", ...
    procedureName="tMyAdd")

Running tMyAdd
..
Done tMyAdd
__________


ans = 
  TestResult with properties:

          Name: 'tEquivalence/tMyAdd'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 2.6670
       Details: [1×1 struct]

Totals:
   1 Passed, 0 Failed, 0 Incomplete.
   2.667 seconds testing time.

Tips

• By default, the test case generates code in a temporary directory. To preserve the generated files, use the PreserveInFolder name-value argument.

Version History

Introduced in R2023a