Main Content

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

Include Sample Files Using Library Compiler

When you use the Library Compiler app, you can either write your own sample MATLAB script or generate a script using the sample file creation feature.

Samples section of the Library Compiler with the buttons 'Create New Sample' and 'Add Existing Sample'

To automatically generate a new MATLAB sample file, click Create New Sample and select your MATLAB function. 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.

To upload a MATLAB script you have already written, click Add Existing Sample.

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 and call the exported function. 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 = [1 4 7; 2 5 8; 3 6 9];
input2 = input1;
addoutput = addmatrix(input1,input2);

After packaging, the generated sample code in the target language returns 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.

See Also

| | |

Related Topics