emlc - Generate embeddable C code from MATLAB code

Syntax

emlc -options files fcn

Description

emlc -options files fcn translates the MATLAB^® function in fcn .m or fcn.p to an embeddable C library or executable, or to a MEX function, based on compiler options. Optionally, you can specify custom files to include in the build.

Inputs

fcn

MATLAB function from which to generate a MEX function, C library, or C executable code. fcn must comply with Embedded MATLAB™ syntax and semantics, a subset of the MATLAB language.

files

Space-separated list of custom files to include in generated code. You can include the following types of files:

C file (.c)
Header file (.h)
Object file (.o or .obj)
Library (.a, .so, or .lib)
Template makefile (.tmf)

options

Choice of compiler options. emlc resolves options from left to right. If you specify conflicting options, the rightmost one prevails.

`-c`	Generate C code, but do not invoke the `make` command. Use only with `rtw`, `rtw:exe`, and `rtw:lib` targets.
`-d out_folder`	Store generated files in the absolute or relative path specified by `out_folder`. If the folder specified by `out_folder` does not exist, `emlc` creates it for you. If not specified, generates files in the default folder: emcprj/`target`/`fcn` `target` can be: `mexfcn` for MEX functions `rtwexe` for embeddable C executables `rtwlib` for embeddable C libraries `fcn` is the name of the MATLAB function.
`-eg example_inputs`	Define the size, class, and complexity of all MATLAB function inputs. Use the values in `example_inputs` to define these properties. `example_inputs` must be a cell array that specifies the same number and order of inputs as the MATLAB function.
`-F fimath_obj`	Specify `fimath_obj` as the default `fimath` object for all fixed-point inputs to the primary function. You can define `fimath_obj` using the `fimath` function. If not specified, `emlc` uses the MATLAB default `fimath` value.
`-g`	Compiles MEX functions in debug mode, with optimization turned off. Use only for `mex` targets. If not specified, `emlc` generates MEX functions in optimized mode.
`-I include_path`	Add `include_path` to the beginning of the Embedded MATLAB path. `emlc` searches the Embedded MATLAB path first when converting M-code to C code.
`-N numerictype_obj`	Specify `numerictype_obj` as the default `numerictype` object for all fixed-point inputs to the MATLAB function. You can define `numerictype_obj` using the `numerictype` function. If not specified, you must define fixed-point inputs using the `-eg` option.
`-o output_file_name`	Generate the MEX function, C library, or C executable file with the base name `output_file_name` plus an extension: `.a` or `.lib` for C libraries `.exe` or no extension for C executables Platform-dependent extension for generated MEX functions `output_file_name` can be a file name or include an existing path.
`-O optimization_option`	Optimize generated code, based on the value of `optimization_option`: `enable:inline` — Enable function inlining `disable:inline` — Disable function inlining `enable:blas` — Use BLAS library, if available `disable:blas` — Do not use BLAS library If not specified, `emlc` uses inlining and BLAS library functions for optimization.
`-report`	Generate a compilation report. If not specified, `emlc` generates a report only if there are error or warning messages.
`-s config_obj`	Specify code generation parameters, based on `config_obj`, defined as one of these objects: `emlcoder.HardwareImplementation` — Parameters of the target hardware for embeddable C code. Use with `rtw`, `rtw:lib`, or `rtw:exe` targets. If not specified, `emlc` generates code compatible with the MATLAB host computer. `emlcoder.MEXConfig` — Parameters for MEX code generation. Use with `mex` target. `emlcoder.RTWConfig` — Parameters for embeddable C code generation. Use with `rtw`, `rtw:lib`, and `rtw:exe` targets. Define `config_obj` as a MATLAB variable. For example: rtw_config = emlcoder.RTWConfig
`-T target_option`	Specify target for generated code, based on value of `target_option`: `mex` — Generate a MEX function (default) `rtw` or `rtw:lib` — Generate embeddable C library file `rtw:exe` — Generate embeddable C code executable file. You must provide a `main` function to include in the build. If not specified, `emlc` generates a MEX function.
`-v`	Enable verbose mode to show compilation steps. Use with `rtw`, `rtw:lib`, and `rtw:exe` targets.
`-?`	Display help for `emlc` command.

Examples

Generate a MEX function from an Embedded MATLAB compliant function:

Write a MATLAB function emcrand that generates a random scalar value drawn from the standard uniform distribution on the open interval (0,1):
```
function r = emcrand() %#eml
% The directive %#eml declares the function
%  to be Embedded MATLAB compliant
r = rand();
```
Generate and run the MEX function:
```
emlc emcrand
emcrand
```

Generate C executable files from an Embedded MATLAB compliant function. Specify the main C function as a configuration parameter:

Write a MATLAB function emcrand that generates a random scalar value drawn from the standard uniform distribution on the open interval (0,1):
```
function r = emcrand() %#eml
r = rand();
```

Write a main C function c:\myfiles\main.c that calls emcrand:

/*
** main.c
*/
#include <stdio.h>
#include <stdlib.h>

int main()
{
    emcrand_initialize();
    
    printf("emcrand=%g\n", emcrand());
    
    emcrand_terminate();
    
    return 0;
}

Configure your code generation parameters to include the main C function, then generate the C executable:
```
rtwcfg = emlcoder.RTWConfig
rtwcfg.CustomSource = 'main.c'
rtwcfg.CustomInclude = 'c:\myfiles'
emlc -T rtw:exe -s rtwcfg emcrand
```
emlc generates C executables and supporting files in the default folder emcprj/rtwexe/emcrand.
This example shows how to specify a main function as a parameter in the configuration object emlcoder.RTWConfig. Alternatively, you can specify the file containing main() separately on the command line. This file can be a source, object, or library file.

Generate C library files in a custom folder from an Embedded MATLAB compliant function with inputs of different classes and sizes. The first input is a 1–by-4 vector of unsigned 16–bit integers; the second input is a double-precision scalar:

Write a MATLAB function emcadd that returns the sum of two values:
```
function y = emcadd(u,v) %#eml
y = u + v;
```

Generate the C library files in a custom folder emcaddlib:

emlc -T rtw:lib -d emcaddlib -eg {zeros(1,4,'uint16'),0} emcadd

Generate C library files from an Embedded MATLAB compliant function that takes a fixed-point input:

Write an M-function emcsqrtfi that computes the square root of a fixed-point input:
```
function y = emcsqrtfi(x) %#eml
y = sqrt(x);
```

Define numerictype and fimath properties for the fixed-point input x and generate C library code for emcsqrtfi:

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)}
emlc -T rtw:lib -eg myfiprops emcsqrtfi

emlc generates C library and supporting files in the default folder emcprj/rtwlib/emcsqrtfi.

Alternatives

You can use a GUI to modify parameters for code generation with emlc:

To modify hardware implementation parameters using a dialog box:
```
hw_config = emlcoder.HardwareImplementation
open hw_config
```
To modify C code generation parameters using a dialog box:
```
rtw_config = emlcoder.RTWConfig
open rtw_config
```
To modify MEX code generation parameters using a dialog box:
```
mex_config = emlcoder.MEXConfig
open mex_config
```