codegen - Generate C/C++ code from

    MATLAB code - MATLAB ([original](http://www.mathworks.com/access/helpdesk/help/coder/ref/codegen.html)) ([raw](?raw))

Generate C/C++ code fromMATLAB code

Syntax

Description

codegen [options](#mw%5F65d7c5e8-d444-4a9a-beb5-909507aba70c) [function](#mw%5F18c379d8-47c1-4054-9024-04e63ea8194d) generates C or C++ code from a MATLAB® function and builds the generated code. This syntax is applicable if either of these conditions is true:

• The function does not have input arguments.
• The function contains one or more arguments blocks that specify the type and size of all the input arguments.

Use the options argument to specify settings such as the code generation configuration object. The configuration object controls build type (MEX, lib, dll, or exe) and code generation parameters. For information on creating and using a configuration object, see Configure Code Generation and Build Settings, coder.config, and the configuration object reference pages: coder.CodeConfig, coder.MexCodeConfig, and coder.EmbeddedCodeConfig.

example

codegen [options](#mw%5F65d7c5e8-d444-4a9a-beb5-909507aba70c) [function](#mw%5F18c379d8-47c1-4054-9024-04e63ea8194d) -args {[func_inputs](#mw%5F8cc53e3e-b706-4281-947d-4c6d2ef4126f)} generates C or C++ code from a MATLAB function with inputs of type func_inputs and builds the generated code. Use the options argument to specify settings such as the code generation configuration object. The configuration object controls build type (MEX, lib, dll, or exe) and code generation parameters. For information on creating and using a configuration object, see Configure Code Generation and Build Settings, coder.config, and the configuration object reference pages: coder.CodeConfig, coder.MexCodeConfig, and coder.EmbeddedCodeConfig.

If the function does not have inputs, omit the function-specific -args {`func_inputs`} option.

example

codegen [options](#mw%5F65d7c5e8-d444-4a9a-beb5-909507aba70c) [files](#mw%5F7938a9d8-b3b7-4a68-bfea-3bd73c0c06e0) function1 -args {func1_inputs} ... functionN -args {funcN_inputs} generates C/C++ code from multiple MATLAB functions. Write the input arguments separately for each function following the function name. You can also use the -nargout option for each function. The functions that you generate code from are called entry-point functions. For more information, see Generate Code for Multiple Entry-Point Functions.

codegen [options](#mw%5F65d7c5e8-d444-4a9a-beb5-909507aba70c) [files](#mw%5F7938a9d8-b3b7-4a68-bfea-3bd73c0c06e0) [function](#mw%5F18c379d8-47c1-4054-9024-04e63ea8194d) -args {func_inputs1} ... -args {func_inputsN} generates code that accepts input arguments with multiple type signatures specified by-args. For the MEX target, a single MEX function is generated that accepts all the specified signatures. However, for standalone targets, a C/C++ entry-point function is generated for each signature. Use theoptions argument to specify settings such as the code generation configuration object and parameters. For more information, see Generate Code for Functions with Multiple Signatures.

example

codegen [project](#mw%5F47ec214c-9923-4131-9d4c-d1f3668556e9) generates code from aMATLAB Coder™ project file, for example, test.prj.

Examples

collapse all

Generate MEX Function from MATLAB Function Using Input Argument Validation to Specify Input Types

Write a MATLAB function mcadd that returns the sum of two input arguments u and v. Use anarguments block to declare that u is a 1-by-4 row vector of real double values and v is a real scalar double.

function y = mcadd(u,v) %#codegen % The directive %#codegen indicates that the function % is intended for code generation arguments u (1,4) double v (1,1) double end y = u + v; end

At the MATLAB command line, run this codegen command.

The code generator produces a MEX file mcadd_mex in the current working folder.

• If you do not specify a build target, code generation defaults to MEX code generation. By default, the code generator names the generated MEX functionmcadd_mex.
• To allow the generation of MEX or C/C++ code with specific types, you must specify the type and size of all input variables to the MATLAB entry-point functions. In this example, you use thearguments block to declare that the first input is a1-by-4 array of realdouble values and the second input is a real scalardouble.

At the command line, call the generated MEX function mcadd_mex. Make sure that the type and size of the values that you pass tomcadd_mex match the input properties that you specified in thearguments block.

Running the MATLAB function mcadd with these input values produces the same output. This test case verifies that mcadd andmcadd_mex have the same behavior.

Generate a MEX Function from a MATLAB Function Using -args to Specify Input Types

Write a MATLAB function mcadd that returns the sum of two values.

function y = mcadd(u,v) %#codegen % The directive %#codegen indicates that the function % is intended for code generation y = u + v; end

At the MATLAB command line, run this codegen command.

codegen mcadd -args {[0 0 0 0],0}

The code generator produces a MEX file mcadd_mex in the current working folder.

• If you do not specify a build target, code generation defaults to MEX code generation. By default, the code generator names the generated MEX functionmcadd_mex.
• To allow the generation of MEX or C/C++ code with specific types, you must specify the properties (class and size) of all input variables to the MATLAB entry-point functions. In this example, you use the-args option to provide example values for the inputs. The code generator uses these example values to determine that the first input is a1-by-4 array of realdouble values and the second input is a real scalardouble.
  The actual values of these example inputs are not relevant for code generation. Any other pair of values with the same properties (class and size) results in the same generated code. See Specify Types of Entry-Point Function Inputs.

At the command line, call the generated MEX function mcadd_mex. Make sure that the class and size of the values that you pass tomcadd_mex match the input properties that you specified in thecodegen command.

Running the MATLAB function mcadd with these input values produces the same output. This test case verifies that mcadd andmcadd_mex have the same behavior.

Generate a MEX Function from a MATLAB Function That Has Multiple Signatures

Write a MATLAB function myAdd that returns the sum of two values.

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

At the MATLAB command line, run this codegen command.

codegen -config:mex myAdd.m -args {1,2} -args {int8(2),int8(3)} -args {1:10,1:10} -report

The code generator creates a single MEX function myAdd_mex for the multiple signatures specified in the codegen command. For more information, see Generate Code for Functions with Multiple Signatures.

Generate C Static Library Files in a Custom Folder

Write a MATLAB function, mcadd, that returns the sum of two values.

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

Generate the C library files in a custom folder mcaddlib using the -config:lib option. Specify the first input type as a 1-by-4 vector of unsigned 16-bit integers. Specify the second input as a double-precision scalar.

codegen -d mcaddlib -config:lib mcadd -args {zeros(1,4,'uint16'),0}

Generate an Executable

Write a MATLAB function, coderRand, that generates a random scalar value from the standard uniform distribution on the open interval (0,1).

function r = coderRand() %#codegen r = rand();

Write a main C function, c:\myfiles\main.c, that callscoderRand.

/* ** main.c */ #include <stdio.h> #include <stdlib.h> #include "coderRand.h" #include "coderRand_initialize.h" #include "coderRand_terminate.h" int main() { coderRand_initialize(); printf("coderRand=%g\n", coderRand()); coderRand_terminate();

puts("Press enter to quit:");
getchar();

return 0;

}

Configure your code generation parameters to include the main C function, then generate the C executable.

cfg = coder.config('exe') cfg.CustomSource = 'main.c' cfg.CustomInclude = 'c:\myfiles' codegen -config cfg coderRand

codegen generates a C executable,coderRand.exe, in the current folder, and supporting files in the default folder, codegen\exe\coderRand.

This example shows how to specify a main function as a parameter in the configuration object coder.CodeConfig. Alternatively, you can specify the file containing main() separately at the command line. You can use a source, object, or library file.

For a more detailed example, see Use an Example C Main in an Application.

Generate Code That Uses a Variable-Size Input

Write a MATLAB function that takes a single input.

function y = halfValue(vector) %codegen y = 0.5 * vector; end

Use coder.typeof to define an input type as a row vector of doubles with a maximum size of 1-by-16, with the second dimension variable-size.

vectorType = coder.typeof(1, [1 16], [false true]);

Generate a C static library.

codegen -config:lib halfValue -args {vectorType}

Generate Code That Uses Global Data

Write a MATLAB function, use_globals, that takes one input parameteru and uses two global variables AR andB.

function y = use_globals(u) %#codegen % Turn off inlining to make % generated code easier to read coder.inline('never'); global AR; global B; AR(1) = u(1) + B(1); y = AR * 2;

Generate a MEX function. By default, codegen generates a MEX function named use_globals_mex in the current folder. Specify the properties of the global variables at the command line by using the-globals option. Specify that input u is a real, scalar, double, by using the -args option.

codegen -globals {'AR', ones(4), 'B', [1 2 3 4]} use_globals -args {0}

Alternatively, you can initialize the global data in the MATLAB workspace. At the MATLAB prompt, enter:

global AR B; AR = ones(4); B = [1 2 3];

Generate the MEX function.

codegen use_globals -args {0}

Generate Code That Accepts an Enumerated Type Input

Write a function, displayState, that uses enumerated data to activate an LED display, based on the state of a device. It lights a green LED display to indicate the ON state. It lights a red LED display to indicate the OFF state.

function led = displayState(state) %#codegen

if state == sysMode.ON led = LEDcolor.GREEN; else led = LEDcolor.RED; end

Define an enumeration LEDColor. On the MATLAB path, create a file named 'LEDColor' containing:

classdef LEDcolor < int32 enumeration GREEN(1), RED(2), end end

Create a coder.EnumType object using a value from an existing MATLAB enumeration.

Define an enumeration sysMode. On the MATLAB path, create a file named 'sysMode' containing:

classdef sysMode < int32 enumeration OFF(0) ON(1) end end

Create a coder.EnumType object from this enumeration.

t = coder.typeof(sysMode.OFF);

Generate a MEX function for displayState.

codegen displayState -args {t}

Generate Code for a Function in a MATLAB Namespace

Write a MATLAB function myMult that returns the product of two values. Save this function in namespace+myNamespace.

function out = myMult(a,b) out = a*b; end

Generate code for this function at the command line. Specify the functionmyMult in namespace +myNamespace using dot notation.

codegen myNamespace.myMult -args {0,0}

To prevent name clashes among entry-point functions with the same name in different namespaces, the files generated by the code generator begin with the name of the namespace and the name of the entry-point function. For example, use this command to call the generated MEX function.

myNamespace_myMult_mex(4,3)

Generate a Static Library That Accepts a Fixed-Point Input

Write a MATLAB language function, mcsqrtfi, that computes the square root of a fixed-point input.

function y = mcsqrtfi(x) %#codegen y = sqrt(x);

Define numerictype and fimath properties for the fixed-point input x and generate C library code formcsqrtfi using the -config:lib option.

T = numerictype('WordLength',32, ... 'FractionLength',23, ... 'Signed',true) F = fimath('SumMode','SpecifyPrecision', ... 'SumWordLength',32, ... 'SumFractionLength',23, ... 'ProductMode','SpecifyPrecision', ... 'ProductWordLength',32, ... 'ProductFractionLength',23) % Define a fixed-point variable with these % numerictype and fimath properties myfiprops = {fi(4.0,T,F)} codegen -config:lib mcsqrtfi -args myfiprops

codegen generates C library and supporting files in the default folder,codegen/lib/mcsqrtfi.

Generate a Static C++ Library That Accepts Half-Precision Inputs

You can generate code for MATLAB code that accepts half-precision inputs. For more information, see half.

Write a MATLAB function foo that returns the sum of two values.

function y = foo(a,b) y = a + b; end

At the MATLAB command line, run this codegen command.

codegen -lang:c++ -config:lib foo -args {half(0),half(0)} -report

Code generation successful: View report

The code generator produces a static C++ library in_`work`_\codegen\lib\foo, where_`work`_ is the current working folder.

To view the code generation report, click _View report_. In the report viewer, inspect the generated C++ source code in the file foo.cpp.

real16_T foo(real16_T a, real16_T b) { return a + b; }

The generated function foo accepts and returns half-precision values. The C++ half-precision type real16_T is defined in the generated header file rtwhalf.h. Inspect the definition of the+ operator of the class real16_T.

The generated code in this example converts half-precision inputs to single-precision, performs the addition operation in single-precision, and converts the result back into half-precision.

Convert Floating-Point MATLAB Code to Fixed-Point C Code

This example requires Fixed-Point Designer™.

Write a MATLAB function, myadd, that returns the sum of two values.

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

Write a MATLAB function, myadd_test, to testmyadd.

function y = myadd_test %#codegen y = myadd(10,20); end

Create a coder.FixptConfig object, fixptcfg, with default settings.

fixptcfg = coder.config('fixpt');

Set the test bench name.

fixptcfg.TestBenchName = 'myadd_test';

Create a code generation configuration object to generate a standalone C static library.

cfg = coder.config('lib');

Generate the code using the -float2fixed option.

codegen -float2fixed fixptcfg -config cfg myadd

Convert codegen Command to Equivalent MATLAB Coder Project

Define a MATLAB function, myadd, that returns the sum of two values.

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

Create a coder.CodeConfig object for generating a static library. Set TargetLang to 'C++'.

cfg = coder.config('lib'); cfg.TargetLang = 'C++';

At the MATLAB command line, create and run a codegen command. Specifymyadd as the entry-point function. Specify the inputs tomyadd to be variable-size matrices of typedouble whose dimensions are unbounded. Specifycfg as the code configuration object. Include the-toproject option to convert the codegen command to an equivalent MATLAB Coder project file with name myadd_project.prj.

codegen -config cfg myadd -args {coder.typeof(1,[Inf,Inf]),coder.typeof(1,[Inf,Inf])} -toproject myadd_project.prj

Project file 'myadd_project.prj' was successfully created. Open Project

The code generator creates the project file myadd_project.prj in the current working folder. Running codegen with the-toproject option does not generate code. It only creates the project file.

Generate code from myadd_project.prj by using anothercodegen command.

codegen myadd_project.prj

The code generator produces a C++ static library function myadd in the _`work`_\codegen\lib\myadd folder, where _`work`_ is your current working directory.

Input Arguments

collapse all

options — Code generation options

option value | space delimited list of option values

The codegen command gives precedence to individual command-line options over options specified by a configuration object. If command-line options conflict, the rightmost option prevails. The order of the options and the other syntax elements is interchangeable.

Specified as one or more of these values:

function — Name of MATLAB function to generate code from

function name

Specified as a function existing in the current working folder or on the path. To specify a function in a MATLAB namespace that exists in the current working folder or on the path, add the namespace name to the beginning of the function name, followed by a dot. If the MATLAB file is on a path that contains non 7-bit ASCII characters, such as Japanese characters, then the codegen command might not find the file.

Example: codegen myAddFunction

Example: codegen myNamespace.myAddFunction

func_inputs — Example values for MATLAB function inputs

expression | variable | literal value | coder.Type object

Example values that define the size, class, and complexity of the inputs of the preceding MATLAB function. The position of the input in the cell array must correspond to the position of the input argument in the MATLAB function definition. Alternatively, instead of an example value, you can provide a coder.Type object. To create a coder.Type object, usecoder.typeof.

To generate a function that has fewer input arguments than the function definition has, omit the example values for the arguments that you do not want.

For more information, see Specify Types of Entry-Point Function Inputs.

Example: codegen foo -args {1}

Example: codegen foo2 -args {1, ones(3,5)}

Example: codegen foo3 -args {1, ones(3,5), coder.typeof("hello")}

files — Names of custom source files

file name | space delimited list of file names

Space-separated list of custom files to include in generated code. The order of the options, external files, and function specifications is interchangeable. You can include these types of files:

• C file (.c)
• C++ file (.cpp)
• Header file (.h)
• Object file (.o or .obj)
• Library (.a, .so,.dylib, or .lib)

If these files are on a path that contains non 7-bit ASCII characters, such as Japanese characters, the codegen command might not find the files.

Example: codegen foo myLib.lib

number_args — Number of output arguments in the generated entry-point function

integer

Number of output arguments in the C/C++ entry-point function generated for the preceding MATLAB function. The code generator produces the specified number of output arguments in the order in which they occur in the MATLAB function definition.

Example: codegen myMLfnWithThreeOuts -nargout 2

project — Project file name

file name

Project file created from the MATLAB Coder app. The code generator uses the project file to set entry-point functions, input type definitions, and other options. To open the app and create or modify a project file, use the coder function.

Example: codegen foo.prj

Limitations

• You cannot generate code for MATLAB scripts. Rewrite the script as a function to generate code.
• Generating code when the current folder is a private folder or an @ folder is not supported, because these folders have special meanings in MATLAB. You can generate code that invokes methods in @ folders and functions in private folders.
• When generating code for entry-point functions in namespaces, the codegen command does not support the options -double2single,-float2fixed, and -singleC.

Tips

• By default, code is generated in the foldercodegen/_`target`_/_`function`_. MEX functions and executables are copied to the current working folder.
• To simplify your code generation process, you can write your code generation commands in a separate script. In the script, define your function input types and code generation options. To generate code, call the script.
• Each time codegen generates the same type of output for the same code or project, it removes the files from the previous build. If you want to preserve files from a previous build, before starting another build, copy the files to a different location.
• Use the coder function to open the MATLAB Coder app and create a MATLAB Coder project. The app provides a user interface that facilitates adding MATLAB files, defining input parameters, and specifying build parameters.
• You can call codegen by using function syntax. Specify thecodegen arguments as character vectors or string scalars. For example:
  codegen('myfunction','-args',{2 3},'-report')
• To provide a string scalar as an input or to specify a codegen argument as a string scalar, use the function syntax. For example:
  codegen('myfunction','-args',"mystring",'-report')
  codegen("myfunction","-args","mystring","-report")
  Providing string scalar inputs to the command form of codegen can produce unexpected results. See Choose Command Syntax or Function Syntax.
• To perform programmatic codegen calls, use the function syntax. For example:
  A = {'myfunction','-args',{2 3}};
  codegen(A{:})

Version History

Introduced in R2011a