Create Sample Code to Call Exported Function

Using MATLAB^® Compiler SDK™, you can generate and modify sample MATLAB files, which are compiled into C++, .NET, Java^®, or Python^® code. The generated sample code demonstrates how to call a MATLAB exported function in the target language. You can use samples to implement your own application or to test the compiled artifact.

For each MATLAB sample file you include during packaging, a sample application in the target language is generated in a folder named samples. These samples are also included in the installer. The sample code calls your exported function using the same inputs and outputs as in the corresponding MATLAB sample file.

You can choose not to include sample files before packaging. If you write your own code in the target language, you can move it to the appropriate directory once the MATLAB functions are packaged.

The following target types support sample generation:

• C++ shared library

• Java package

• .NET assembly

• Python package

Create Sample Files Using Compiler Apps

When you use a compiler app for a supported target language, such as Python Package Compiler, you can either write your own sample MATLAB script or generate a script using the sample file creation feature.

To upload a MATLAB script you have already written, click Add existing sample in the Samples section.

To generate a new MATLAB sample file, click Create new sample. This opens up a MATLAB script for you to edit.

The generated sample script calls your MATLAB function with arguments set to zero, which you should modify as necessary based on the intended behavior of your function. After packaging, the generated sample code calls your exported function using the same arguments as in the sample MATLAB script.

Caution

Sample file code should not require user interaction. If the MATLAB function requires input arguments, you must provide specific values for the arguments in the function call.

Include Sample Files Using Command Line

If you have already created a MATLAB sample file, you can include it in a compiler.build function for the supported targets using the 'SampleGenerationFiles' option.

For example, generate sample .NET code from the sample file addmatrixSample1 using the compiler.build.dotNETAssembly function.

buildResults = compiler.build.dotNetAssembly('addmatrix.m',...
    'AssemblyName','libmatrix',...
    'SampleGenerationFiles','addmatrixSample1.m');

Guidelines for MATLAB Sample Files

The MATLAB sample script should set data values as necessary to call the exported function and obtain an example output. If your MATLAB function takes input arguments, the sample should set specific values for these arguments.

For example, consider the function addmatrix.m that adds the two matrices passed as input.

function a = addmatrix(a1, a2)
a = a1 + a2;

The sample file addmatrixSample1.m calls the function with the specified input arguments input1 and input2.

input1 = [1 2 3; 4 5 6; 7 8 9];
input2 = [1 4 7; 2 5 8; 3 6 9];
addoutput = addmatrix(input1,input2);

After packaging, the generated target language code uses the same inputs and calculates the same output as the sample MATLAB script.

Sample MATLAB files must follow these guidelines:

• The sample file must be a MATLAB script, not a function or exported class.

• The sample file code must use only exported functions. Any user-defined function called in the script must be a top-level exported function.

• Each exported function must be in a separate sample file.

• Each call to the same exported function must be a separate sample file.

• Sample file code should not require user interaction.

• Data must be saved as a local variable and then passed to the exported function in the sample file code.

• The input parameters of the top-level function are analyzed during the process. An input parameter cannot be a field in a structure.

• The output of the exported function must be an n-dimensional numeric, character, logical, structure, or cell array.

• The sample script is executed as part of the process of generating the target language sample code. Any errors in execution (for instance, undefined variables) will prevent a sample from being generated, although the build target will still be generated.

Additional considerations specific to the target language are as follows:

• C++ mwArray API — varargin and varargout are not supported.

• .NET — Type-safe API is not supported.

• Python — Cell arrays and character arrays must be of size 1-by-N and structure arrays must be scalar. There are no restrictions on numeric or logical arrays, other than that they must be rectangular, as in MATLAB.