Embedded MATLAB™

emlmex - Generate C-MEX code from M-code

Syntax

emlmex [-options] fun

Description

emlmex is a MATLAB^® command that invokes Embedded MATLAB™ MEX. You issue the emlmex command from the MATLAB command prompt.

emlmex [-options] fun translates the M-file fun.m to a C-MEX file and generates all necessary wrapper files.

By default, emlmex:

Converts the M-function fun.m to a C-MEX function
Generates a platform-specific MEX-file in the current directory
Stores generated files in the subdirectory emcprj/ mexfcn/fun/

You can change the default behavior by specifying one or more compilation options as described in Options.

Options

You can specify one or more compilation options with each emlmex command. Use spaces to separate options and arguments. emlmex resolves options from left to right, so if you use conflicting options, the rightmost one prevails. Here is the list of options:

-d Specify Output Directory

-d out_directory

Store generated files in directory path specified by out_directory. If any directories on the path do not exist, emlmex creates them for you. out_directory can be an absolute path or relative path. If you do not specify an output directory, emlmex stores generated files in a default subdirectory called emcprj/mexfcn/fun.

-eg Specify Input Properties by Example

-eg example_inputs

Use the values in cell array example_inputs as sample inputs for defining the properties of the primary M-function inputs. The cell array should provide the same number and order of inputs as the primary function. See Defining Input Properties by Example at the Command Line.

-F Specify Default fimath

-F fimath

Use fimath as the default fimath object for all fixed-point inputs to the primary function. You can define the default value using the Fixed-Point Toolbox™ function fimath, as in this example:

emlmex -F fimath('OverflowMode','saturate','RoundMode','nearest') myFcn

emlmex uses the default value if you have not defined any other fimath property for the primary, fixed-point inputs, either by example (see Defining Input Properties by Example at the Command Line) or programmatically (see Defining Input Properties Programmatically in the M-File). If you do not define a default value, emlmex uses the MATLAB default fimath value.

-g Compile C-MEX Function in Debug Mode

Compile the C-MEX function in debug mode, with optimization turned off. If you do not specify -g, emlmex compiles the C-MEX function in optimized mode. You specify these modes using the mex -setup procedure described in Building MEX-Files in the MATLAB External Interfaces documentation.

-I Add Directories to Embedded MATLAB Path

-I include_path

Add include_path to the Embedded MATLAB path. By default, the Embedded MATLAB path consists of the current directory (pwd) and the Embedded MATLAB libraries directory. emlmex converts M-code to C-MEX code only if it finds the M-file on the Embedded MATLAB path. See How the Embedded MATLAB Subset Resolves Function Calls.

emlmex searches directories from left to right.

-N Specify Default Numeric Type

-N numerictype

Use numerictype as the default numerictype object for all fixed-point inputs to the primary function. You can define the default value using the Fixed-Point Toolbox function numerictype, as in this example:

emlmex -N numerictype(1,32,23) myFcn

This command specifies that the numeric type of all fixed-point inputs to the top-level function myFcn be signed (1), have a word length of 32, and have a fraction length of 23.

Embedded MATLAB MEX uses the default value if you have not specified any other numeric type for the primary, fixed-point inputs, either by example (see Defining Input Properties by Example at the Command Line) or programmatically (see Defining Input Properties Programmatically in the M-File). If you do not define a default value, then you must use one of the other methods to specify the numeric type of your primary, fixed-point inputs.

-o Specify Output File Name

-o output_file_name

Generate the final output file, the C-MEX function, with the base name output_file_name. Embedded MATLAB MEX automatically assigns C-MEX files a platform-specific extension (see Naming Conventions).

You can specify output_file_name as a file name or an existing path, with the following effects:

If you specify:	emlmex:
A file name	Copies the MEX-file to the current directory
An existing path	Generates the MEX-file in the directory specified by the path, but does not copy the MEX-file to the current directory
A path that does not exist	Generates an error

-O Specify Compiler Optimization Option

-O optimization_option

Specify compiler optimization_option with one of the following literals (no quotes):

Compiler Optimization Option	Action
`disable:inline`	Disable function inlining.
`enable:inline`	Enable function inlining (default).

-s Specify Compiler Options

-s compilation_config_object

Generate C-MEX functions based on the properties of a compilation configuration object. When you specify conflicting configuration objects on the command line, the rightmost configuration object prevails. For detailed information, see Setting C-MEX Compilation Options.

If a compilation configuration object is not specified, Embedded MATLAB Coder uses default property values, as follows:

Defaults for emlcoder.CompilerOptions.

Property	Default
`ConstantFoldingTimeout`	10000
`InlineThreshold`	10
`InlineThresholdMax`200	200
`InlineStackLimit`	4000
`SaturateOnIntegerOverflow`	true
`StackUsageMax`	200000

-? Display Help

Display emlmex command help.

Examples

This section presents examples based on an M-file emcrand.m, described in Sample M-File.

Sample M-File

function r = emcrand(num)
assert(isa(num,'double')); 
persistent seeded;
if isempty(seeded)
   seeded = true;
   rand('seed', num);
end
r = rand();

Converting M-Function to C-MEX Function

emlmex emcrand

Generates a C-MEX function. Places the C-MEX function and other supporting files in a subdirectory called emcprj/mexfcn/emcrand, the default location. emlmex uses the name of the M-function as the root name for the generated files and creates a platform-specific extension for the C-MEX file, as described in Naming Conventions.

Specifying Custom Name for C-MEX File

emlmex -o emcrandmx emcrand

Uses emcrandmx as the root name of the C-MEX file, but uses emcrand as the root name for all other generated files. Generates all files to the default directory emcprj/mexfcn/emcrand, but also makes a copy of the C-MEX file in the current directory.

Specifying Custom File Name as Path

emlmex -o mydir/emcrandx emcrand

Generates all files in an existing subdirectory called mydir, using emcrandx as the root name of the C-MEX file. When the argument is a path, emlmex does not copy the C-MEX file to the current directory.

Specifying Custom Output Directory for C-MEX File

emlmex -d mydir emcrand

Generates all files in the subdirectory mydir with the M-function name as the root name for all files.

Specifying Primary Function Input Properties by Example

Currently, the M-function emcrand (described in Sample M-File) uses the assert function to specify that its input num is a real double scalar, as follows:

assert(isa(num,'double'));

Note For information about using assert to specify input properties for emlmex, see Defining Input Properties Programmatically in the M-File.

Suppose you instead want to specify the primary function input properties by example at the command line. Remove the assert call from the M-code and enter this command:

emlmex -eg {0} emcrand

The value in the cell array {0} is a real double scalar, exemplifying the properties that you want to specify for input num.

Function Reference

eml.allowpcode