mbuild

Compile and link source files against MATLAB generated shared libraries

Syntax

mbuild [options] sourceFile

Description

Use mbuild to compile and link source files against MATLAB^® generated shared libraries.

mbuild is called implicitly by mcc in order to produce C or C++ mwArray shared libraries. You can call it explicitly in order to link additional C or C++ code with those shared libraries.

If no platform is listed, the option is available on both UNIX^® and Windows^®. Some of the options (-f, -g, and -v) are available on the mcc command line and are passed along to mbuild. Others can be passed along using the -M option to mcc. For details, see mcc -M.

When manually integrating shared libraries generated by mcc using the mbuild command, the flags should match. For instance, if -M -R2018a is passed to the mcc command, -R2018a should be passed to mbuild.

Any arguments to mbuild that are not used by mbuild itself are passed along to mex.

mbuild [options] sourceFile compiles and links customer written C or C++ code against MATLAB generated shared libraries.

Examples

Set Up C/C++ Compiler

To change the default C/C++ compiler for use with MATLAB Compiler SDK™, use

mbuild -setup

To compile and link an external C program foo.c against libfoo, use

mbuild foo.c -L. -lfoo (on UNIX)
mbuild foo.c libfoo.lib (on Windows)

This assumes both foo.c and the library generated above are in the current working folder.

Compile and Link C Program

To compile and link an external C program foo.c against libfoo, use

mbuild foo.c -L. -lfoo (on UNIX)
mbuild foo.c libfoo.lib (on Windows)

This assumes both foo.c and the library generated above are in the current working folder.

Input Arguments

sourceFile — Files to be compiled

(default) |

File to be compiled, specified as a character vector or string scalar.

Supported types of source files are:

• .c

• .cpp

Arguments to mbuild that are not options and do not belong to one of the supported source file types are assumed to be library names and passed to the linker.

Example: "mylib.cpp"

Options

@<rspfile> — Command line argument file

(default) |

Include the contents of the text file rspfile as command line arguments to mbuild. This option is available on Windows only.

-c — Compile only

(default) |

Compile only. Creates an object file only.

-D<name>[=<value>] — Define symbol name to C preprocessor

(default) |

Define a symbol name to the C preprocessor. Equivalent to a #define <name> directive in the source.

If you specify a value, define a symbol name and value to the C preprocessor. Equivalent to a #define <name> <value> directive in the source.

Do not add a space between D and <name>. Do not add spaces around the = sign.

Example: -DSPACE_PADDING

-f <optionsfile> — Options file

(default) |

Specify location and name of options file to use. Overrides the mbuild default options file search mechanism. This option lets you use different ANSI compilers for different invocations of the compiler.

You can also specify this option using mcc.

-g — Add debug symbols

(default) |

Create an executable containing additional symbolic information for use in debugging. This option disables the mbuild default behavior of optimizing built object code (see the -O option).

-h,-help — Help text

(default) |

Print help for mbuild.

-I<pathname> — Add folder to include path

(default) |

Add <pathname> to the list of folders to search for #include files.

-l<name> — Link with object library

(default) |

Link with object library. On Windows systems, <name> expands to <name>.lib or lib<name>.lib and on UNIX systems, to lib<name>.so or lib<name>.dylib.

Do not add a space between I and <name>.

Note

When linking with a library, it is essential that you first specify the path (with -L<pathname>, for example).

-L<folder> — Add folder to search path

(default) |

Add <folder> to the list of folders to search for libraries specified with the -l option. On UNIX systems, you must also set the run-time library paths.

If used, the -L option must precede the -l option. When using the -L option on Linux^® or macOS systems, you also must set the runtime library path. For details, see Set Run-Time Library Path.

Do not add a space between L and <folder>.

-n — No execute mode

(default) |

Print out any commands that mbuild would otherwise have executed, but do not actually execute any of them.

-O — Optimize object code

(default) |

Use this option to compile with optimization. Optimization is enabled by default. Optimization is disabled when the -g option appears without the -O option.

-outdir <dirname> — Output folder

(default) |

Place all output files in folder <dirname>.

-output <resultname> — Executable name

(default) |

Create an executable named <resultname>. An appropriate executable extension is automatically appended. Overrides the mbuild default executable naming mechanism.

-R2017b|-R2018a — Complex API type

(default)

When you generate C shared libraries based on mxArray, or C++ shared libraries based on mwArray using the mcc function, these libraries default to a separate storage representation for complex numbers, a representation that can degrade performance. To use interleaved representation in these shared libraries, utilize the -M R2018a option while executing the mcc command.

The R2018a option builds with:

• Interleaved complex API, which includes the typed data access functions. For more information, see Upgrade MEX Files to Use Interleaved Complex API.

• Large-array-handling API

• Treating a handle to a graphics object as object, not double.

The R2017b option builds with:

• Separate complex API, which contains the C and Fortran Matrix API functionality in MATLAB R2017b and earlier.

• Large-array-handling API, which handles arrays with more than 2³¹–1 elements.

• Treating a handle to a graphics object as object, not double.

MathWorks recommends that you create applications and update existing applications to use the R2018a option for interleaved complex API. Alternatively, use the MX_HAS_INTERLEAVED_COMPLEX macro to apply the desired behavior across versions of MATLAB. For more information, see MATLAB Support for Interleaved Complex API in MEX Functions.

-setup — Specify options file

(default) |

Interactively specify the C/C++ compiler options file to use as the default for future invocations of mbuild by placing it in the user profile folder (returned by the prefdir command). When this option is specified, no other command line input is accepted.

-setup -client mbuild_com — Specify COM options file

(default) |

Interactively specify the COM compiler options file to use as the default for future invocations of mbuild by placing it in the user profile folder (returned by the prefdir command). When this option is specified, no other command line input is accepted.

-U<name> — Remove symbol

(default) |

Remove any initial definition of the C preprocessor symbol <name>. (Inverse of the -D option.)

-v — Verbose mode

(default) |

Enable verbose mode. Print the values for important internal variables after the options file is processed and all command line arguments are considered. Prints each compile step and final link step fully evaluated.

<name>=<value> — Override options file variable

(default)

Supplement or override an options file variable for variable <name>. This option is processed after the options file is processed and all command line arguments are considered. You may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax. On Windows double quotes are used (e.g., COMPFLAGS="opt1 opt2"), and on UNIX single quotes are used (e.g., CFLAGS='opt1 opt2').

It is common to use this option to supplement a variable already defined. To do this, refer to the variable by prepending a $ (e.g., COMPFLAGS="$COMPFLAGS opt2" on Windows or CFLAGS='$CFLAGS opt2' on UNIX shell).

For the MinGW-w64 compiler, which is based on gcc/g++, use single quotes (').

Example: COMPFLAGS="$COMPFLAGS opt2"

Version History

Introduced before R2006a