Documentation

Advantages of Generating Code for Multiple Entry-Point Functions

Generating a single C/C++ library for more than one entry-point MATLAB^® function allows you to:

• Create C/C++ libraries containing multiple, compiled MATLAB files to integrate with larger C/C++ applications.

• Share code efficiently between library functions.

• Communicate between library functions using shared memory.

Generating a MEX function for more than one entry-point function allows you to validate entry-point interactions in MATLAB before creating a C/C++ library.

Generate Code for More Than One Entry-Point Function Using the MATLAB Coder App

This example shows how to generate code for multiple entry-point functions using the MATLAB Coder™ app.

Create the Entry-Point Functions

1. In a local writable folder, create a MATLAB file, ep1.m, that contains:

   function y = ep1(u) %#codegen
   y = u;

2. In the same local writable folder, create a MATLAB file, ep2.m, that contains:

   function y = ep2(u, v) %#codegen
   y = u + v;

Create the Test File

In the folder that contains ep1.m and ep2.m, create a MATLAB file, ep_test.m, that calls ep1 and ep2 with example inputs.

function [y, y1] = ep_test
y = ep1(single(2));
y1 = ep2(double(3), double(4));

Open the MATLAB Coder App

On the MATLAB Toolstrip Apps tab, under Code Generation, click the MATLAB Coder app icon.

Specify Source Files

1. On the Select Source Files page, type or select the name of the entry-point function ep1.

   The app creates a project with the default name ep1.prj in the current folder.

2. To add ep2 to the list of entry-point functions, click Add Entry-Point Function. Type or select the name of the entry-point function ep2.

3. Click Next to go to the Define Input Types step. The app analyzes the functions for coding issues and code generation readiness. If the app identifies issues, it opens the Review Code Generation Readiness page where you can review and fix issues. In this example, because the app does not detect issues, it opens the Define Input Types page.

Define Input Types

Because C uses static typing, at compile time, MATLAB Coder must determine the properties of all variables in the MATLAB files. You must specify the properties of all entry-point function inputs. From the properties of the entry-point function inputs, MATLAB Coder can infer the properties of all variables in the MATLAB files.

Specify a test file that MATLAB Coder can use to automatically define types:

1. Enter or select the test file ep_test.m.

2. Click Autodefine Input Types.

   The test file, ep_test.m, calls the entry-point functions ep1 and ep2 with the example input types. MATLAB Coder infers that for ep1, input u is single(1x1). For ep2, u and v are double(1x1).

3. Click Next to go to the Check for Run-Time Issues step.

Check for Run-Time Issues

The Check for Run-Time Issues step generates a MEX file from your entry-point functions, runs the MEX function, and reports issues. This step is optional. However, it is a best practice to perform this step. You can detect and fix run-time errors that are harder to diagnose in the generated C code.

1. To open the Check for Run-Time Issues dialog box, click the Check for Issues arrow .

   The app populates the test file field with ep_test, the test file that you used to define the input types.

2. Click Check for Issues.

   The app generates a MEX function named ep1_mex for ep1 and ep2. It runs the test file ep_test replacing calls to ep1 and ep2 with calls to the MEX function. If the app detects issues during the MEX function generation or execution, it provides warning and error messages. Click these messages to navigate to the problematic code and fix the issue. In this example, the app does not detect issues.

3. Click Next to go to the Generate Code step.

Generate MEX Function

1. To open the Generate dialog box, click the Generate arrow .

2. Set Build type to MEX.

3. Verify that the Output file name is ep1_mex. By default, the app uses the name of the alphabetically first entry-point function.

4. Click Generate.

   MATLAB Coder builds the project. It generates a MEX function, ep1_mex, in the current folder. MATLAB Coder also generates other supporting files in a subfolder called codegen/mex/ep1_mex. MATLAB Coder uses the name of the MATLAB function as the root name for the generated files. It creates a platform-specific extension for the MEX file, as described in Naming Conventions.

   You can now test your MEX function in MATLAB. See How to Call an Entry-Point Function in a MEX Function.

   If you generate a static library for ep1 and ep2, MATLAB Coder builds the project and generates a C library, ep1, and supporting files in the default folder, codegen/lib/ep1.

Generating Code for More Than One Entry-Point Function at the Command Line

To generate code for more than one entry-point function, use the following syntax, where global_options applies to functions, fun_1 through fun_n, and options_n applies only to the preceding function fun_n.

codegen -global_options fun_1 -options_1 ... fun_n -options_n

By default, codegen:

• Generates a MEX function in the current folder. codegen names the MEX function, fun_mex. fun is the name of the alphabetically first entry-point function.

  Stores generated files in the subfolder codegen/mex/fun_1. fun_1 is the name of the first entry-point function.

You can specify the output file name and subfolder name using the -o option.

codegen -o out_fun  fun_1 -options_1 ... fun_n -options_n

• Generates a MEX function named out_fun_mex in the current folder.

• Stores generated files in the subfolder codegen/mex/out_fun.

For more information on setting build options at the command line, see codegen.

Generating a MEX Function with Two Entry-Point Functions at the Command Line

Generate a MEX function with two entry-point functions, ep1 and ep2. Function ep1 takes one input, a single scalar, and ep2 takes two inputs, a double scalar and a double vector. Using the -o option, name the generated MEX function sharedmex.

codegen -o sharedmex ep1 -args single(0) ep2 -args { 0, zeros(1,1024) }

Generating a C/C++ Static Library with Two Entry-Point Functions at the Command Line

Generate standalone C/C++ code and compile it to a library for two entry-point functions, ep1 and ep2. Function ep1 takes one input, a single scalar, and ep2 takes two inputs, a double scalar and a double vector. Use the -config:lib option to specify that the target is a library. Using the -o option, name the generated library sharedlib.

codegen -config:lib -o sharedlib ep1 -args single(0) ep2 ...
   -args { 0, zeros(1,1024) }

For information on viewing entry-point functions in the code generation report, see Code Generation Reports.

How to Call an Entry-Point Function in a MEX Function

To call an entry-point function in a MEX function that has more than one entry point, use this syntax:

MEX_Function('entry_point_function_name', 
         ... entry_point_function_param1, 
         ... , entry_point_function_paramn)

Calling an Entry-Point Function in a MEX Function

Consider a MEX function, sharedmex, that has entry-point functions ep1 and ep2. Entry-point function ep1 takes one single scalar input and ep2 takes two inputs, a double scalar and a double vector.

To call ep1 with an input parameter u, enter:

sharedmex('ep1', u)

To call ep2 with input parameters u and v, enter:

sharedmex('ep2', u, v)

How to Call an Entry-Point Function in a C/C++ Library Function from C/C++ Code

To call an entry-point function in a C/C++ library function from C/C++ code, write a main function in C/C++ that:

• Includes the generated header files, which contain the function prototypes for the entry-point functions.

• Calls the initialize function before calling the entry-point functions for the first time.

• Calls the terminate function after calling the entry-point functions for the last time.

• Configures your target to integrate this custom C/C++ main function with your generated code, as described in Specify External File Locations.

• Generates the C/C++ executable using codegen.

See the example, Call a Generated C Static Library Function from C Code.