MATLAB® Compiler™

C Shared Library Target

C Shared Library Wrapper

The C library wrapper option allows you to create a shared library from an arbitrary set of M-files on both Microsoft^® Windows^® and UNIX^® operating systems. The MATLAB^® Compiler™ product generates a wrapper file, a header file, and an export list. The header file contains all of the entry points for all of the compiled M-functions. The export list contains the set of symbols that are exported from a C shared library.

Note   Even if you are not producing a shared library, you must use -W lib or -W cpplib when including any MATLAB Compiler generated code into a larger application.

Note   mclmcrrt.lib is required for successful linking. For more information, see the MathWorks Support database and search for information on the MSVC shared library.

Back to Top

C Shared Library Example

This example takes several M-files and creates a C shared library. It also includes a standalone driver application to call the shared library.

Building the Shared Library

1. Copy the following files from matlabroot/extern/examples/compiler to your work directory:

   matlabroot/extern/examples/compiler/addmatrix.m
   matlabroot/extern/examples/compiler/multiplymatrix.m
   matlabroot/extern/examples/compiler/eigmatrix.m
   matlabroot/extern/examples/compiler/matrixdriver.c
   

   Note   matrixdriver.c contains the standalone application's main function.

2. To create the shared library, enter the following command on a single line:

   mcc -B csharedlib:libmatrix addmatrix.m multiplymatrix.m 
   eigmatrix.m -v
   

   The -B csharedlib option is a bundle option that expands into

   -W lib:<libname> -T link:lib
   

   The -W lib:<libname> option tells the MATLAB Compiler product to generate a function wrapper for a shared library and call it libname. The -T link:lib option specifies the target output as a shared library. Note the directory where the product puts the shared library because you will need it later on.

Writing the Driver Application

All programs that call MATLAB Compiler generated shared libraries have roughly the same structure:

1. Declare variables and process/validate input arguments.

2. Call mclInitializeApplication, and test for success. This function sets up the global MCR state and enables the construction of MCR instances.

3. Call, once for each library, <libraryname>Initialize, to create the MCR instance required by the library.

4. Invoke functions in the library, and process the results. (This is the main body of the program.)

   Note   If your driver application displays MATLAB® figure windows, you should include a call to mclWaitForFiguresToDie(NULL) before calling the Terminate functions and mclTerminateApplication in the following two steps.

5. Call, once for each library, <libraryname>Terminate, to destroy the associated MCR.

6. Call mclTerminateApplication to free resources associated with the global MCR state.

7. Clean up variables, close files, etc., and exit.

This example uses matrixdriver.c as the driver application.

Note   You must call mclInitializeApplication once at the beginning of your driver application. You must make this call before calling any other MathWorks™ functions or when linking to a MATLAB library such as mclmcrrt.lib (for example, before accessing an MWArray). See Calling a Shared Library for complete details on using a MATLAB Compiler generated library in your application.

Compiling the Driver Application

To compile the driver code, matrixdriver.c, you use your C/C++ compiler. Execute the following mbuild command that corresponds to your development platform. This command uses your C/C++ compiler to compile the code.

mbuild matrixdriver.c libmatrix.lib    (Windows)
mbuild matrixdriver.c -L. -lmatrix -I. (UNIX)

Note   This command assumes that the shared library and the corresponding header file created from step 2 are in the current working directory. On UNIX, if this is not the case, replace the "." (dot) following the -L and -I options with the name of the directory that contains these files, respectively. On Windows, if this is not the case, specify the full path to libmatrix.lib, and use a -I option to specify the directory containing the header file.

This generates a standalone application, matrixdriver.exe, on Windows, and matrixdriver, on UNIX.

Difference in the Exported Function Signature.   The interface to the mlf functions generated by the MATLAB Compiler product from your M-file routines has changed from earlier versions of the product. The generic signature of the exported mlf functions is

• M-functions with no return values

  void mlf<function-name>(<list_of_input_variables>);
  

• M-functions with at least one return value

  void mlf<function-name>(int number_of_return_values, 
  <list_of_pointers_to_return_variables>, 
  <list_of_input_variables>);
  

Refer to the header file generated for your library for the exact signature of the exported function. For example, in the library created in the previous section, the signature of the exported addmatrix function is

void mlfAddmatrix(int nlhs,mxArray **a,mxArray *a1,mxArray *a2);

Testing the Driver Application

These steps test your standalone driver application and shared library on your development machine.

Note   Testing your application on your development machine is an important step to help ensure that your application is compilable. To verify that your application compiled properly, you must test all functionality that is available with the application. If you receive an error message similar to Undefined function or Attempt to execute script script_name as a function, it is likely that the application will not run properly on deployment machines. Most likely, your CTF archive is missing some necessary functions. Use -a to add the missing functions to the archive and recompile your code.

1. To run the standalone application, add the directory containing the shared library that was created in step 2 in Building the Shared Library to your dynamic library path.

2. Update the path for your platform by following the instructions in Developing and Testing Components on a Development Machine.

3. Run the driver application from the prompt (DOS prompt on Windows, shell prompt on UNIX) by typing the application name.

   matrixdriver.exe            (On Windows)
   matrixdriver	               (On UNIX)
   

   The results are displayed as

   The value of added matrix is: 
   2.00		8.00		14.00	 
   4.00		10.00		16.00	 
   6.00		12.00		18.00	 
    
   The value of the multiplied matrix is: 
   30.00		66.00		102.00	 
   36.00		81.00		126.00	 
   42.00		96.00		150.00		 
    
   The eigenvalues of the first matrix are: 
   16.12		-1.12		-0.00	 

Creating Shared Libraries from C with mbuild

mbuild can also create shared libraries from C source code. If a file with the extension .exports is passed to mbuild, a shared library is built. The .exports file must be a text file, with each line containing either an exported symbol name, or starting with a # or * in the first column (in which case it is treated as a comment line). If multiple .exports files are specified, all symbol names in all specified .exports files are exported.

Deploying Standalone Applications That Call MATLAB^® Compiler™ Based Shared Libraries

Gather and package the following files and distribute them to the deployment machine.

Note   MCRInstaller.exe has obsoleted the need for the function buildmcr or the creation of MCRInstaller.zip. See Replacement of MCRInstaller.zip and BUILDMCR Functionality for more details including complete file paths to all install programs.

Note   You can distribute a MATLAB Compiler generated standalone application to any target machine that has the same operating system as the machine on which the application was compiled. If you want to deploy the same application to a different platform, you must use the MATLAB Compiler product on the different platform and completely rebuild the application.

Deploying Shared Libraries to Be Used with Other Projects

To distribute the shared library for use with an external application, you need to distribute the following.

Note   MCRInstaller.exe has obsoleted the need for the function buildmcr or the creation of MCRInstaller.zip. See Replacement of MCRInstaller.zip and BUILDMCR Functionality for more details including complete file paths to all install programs.

Back to Top

Calling a Shared Library

At run-time, there is an MCR instance associated with each individual shared library. Consequently, if an application links against two MATLAB Compiler generated shared libraries, there will be two MCR instances created at run-time.

You can control the behavior of each MCR instance by using MCR options. The two classes of MCR options are global and local. Global MCR options are identical for each MCR instance in an application. Local MCR options may differ for MCR instances.

To use a shared library, you must use these functions:

• mclInitializeApplication

• mclTerminateApplication

mclInitializeApplication allows you to set the global MCR options. They apply equally to all MCR instances. You must set these options before creating your first MCR instance.

These functions are necessary because some MCR options such as whether or not to start Java™, the location of the MCR itself, whether or not to use the MATLAB JIT feature, and so on, are set when the first MCR instance starts and cannot be changed by subsequent instances of the MCR.

Caution   You must call mclInitializeApplication once at the beginning of your driver application. You must make this call before calling any other MathWorks functions. This also applies to shared libraries. Avoid calling mclInitializeApplication multiple times in an application as it will cause the application to hang. After you call mclTerminateApplication, you may not call mclInitializeApplication again. No MathWorks functions may be called after mclTerminateApplication.

Function Signatures

The function signatures are

bool mclInitializeApplication(const char **options, int count);
bool mclTerminateApplication(void); 

mclInitializeApplication.   Takes an array of strings of user-settable options (these are the very same options that can be provided to mcc via the -R option) and a count of the number of options (the length of the option array). Returns true for success and false for failure.

mclTerminateApplication.   Takes no arguments and can only be called after all MCR instances have been destroyed. Returns true for success and false for failure.

This C example shows typical usage of the functions:

int main(){
    
    mxArray *in1, *in2; /* Define input parameters */
    mxArray *out = NULL;/* and output parameters to pass to
                           the library functions */
    
    double data[] = {1,2,3,4,5,6,7,8,9};
    
    /* Call library initialization routine and make sure that
       the library was initialized properly */
    mclInitializeApplication(NULL,0);
    if (!libmatrixInitialize()){
        fprintf(stderr,"could not initialize the library 
                        properly\n");
        return -1;
    }

    /* Create the input data */
    in1 = mxCreateDoubleMatrix(3,3,mxREAL);
    in2 = mxCreateDoubleMatrix(3,3,mxREAL);
    memcpy(mxGetPr(in1), data, 9*sizeof(double));
    memcpy(mxGetPr(in2), data, 9*sizeof(double));
    
    /* Call the library function */
    mlfAddmatrix(1, &out, in1, in2);
    /* Display the return value of the library function */
    printf("The value of added matrix is:\n");
    display(out);
    /* Destroy return value since this variable will be reused
       in next function call. Since we are going to reuse the
       variable, we have to set it to NULL. Refer to MATLAB 
       Compiler documentation for more information on this. */
    mxDestroyArray(out); out=0;
    mlfMultiplymatrix(1, &out, in1, in2);
    printf("The value of the multiplied matrix is:\n");
    display(out);
    mxDestroyArray(out); out=0;
    mlfEigmatrix(1, &out, in1);
    printf("The Eigen value of the first matrix is:\n");
    display(out);
    mxDestroyArray(out); out=0;
    
    /* Call the library termination routine */
    libmatrixTerminate();
    
    /* Free the memory created */
    mxDestroyArray(in1); in1=0;
    mxDestroyArray(in2); in2 = 0;
    mclTerminateApplication();
    return 0;
}

Caution   mclInitializeApplication can only be called once per application. Calling it a second time generates an error, and will cause the function to return false. This function must be called before calling any C-Mex function or MAT-file API function.

Using a Shared Library

To use a MATLAB Compiler generated shared library in your application, you must perform the following steps:

1. Include the generated header file for each library in your application. Each MATLAB Compiler generated shared library has an associated header file named libname.h, where libname is the library's name that was passed in on the command line when the library was compiled.

2. Initialize the MATLAB libraries by calling the mclInitializeApplication API function. You must call this function once per application, and it must be called before calling any other MATLAB API functions, such as C-Mex functions or C MAT-file functions. mclInitializeApplication must be called before calling any functions in a MATLAB Compiler generated shared library. You may optionally pass in application-level options to this function. mclInitializeApplication returns a Boolean status code. A return value of true indicates successful initialization, and false indicates failure.

3. For each MATLAB Compiler generated shared library that you include in your application, call the library's initialization function. This function performs several library-local initializations, such as unpacking the CTF archive, and starting an MCR instance with the necessary information to execute the code in that archive. The library initialization function will be named libnameInitialize(), where libname is the library's name that was passed in on the command line when the library was compiled. This function returns a Boolean status code. A return value of true indicates successful initialization, and false indicates failure.

   Note   On Windows, if you want to have your shared library call a MATLAB shared library (as generated by the MATLAB Compiler product), the MATLAB library initialization function (e.g., <libname>Initialize, <libname>Terminate, mclInitialize, mclTerminate) cannot be called from your shared library during the DllMain(DLL_ATTACH_PROCESS) call. This applies whether the intermediate shared library is implicitly or explicitly loaded. You must place the call somewhere after DllMain().

4. Call the exported functions of each library as needed. Use the C-Mex API to process input and output arguments for these functions.

5. When your application no longer needs a given library, call the library's termination function. This function frees the resources associated with its MCR instance. The library termination function will be named <libname>Terminate(), where <libname> is the library's name that was passed in on the command line when the library was compiled. Once a library has been terminated, that library's exported functions should not be called again in the application.

6. When your application no longer needs to call any MATLAB Compiler generated libraries, call the mclTerminateApplication API function. This function frees application-level resources used by the MCR. Once you call this function, no further calls can be made to MATLAB Compiler generated libraries in the application.

Loading Libraries in a Compiled Function

With MATLAB Compiler version 4.0 (R14) and later, you can use M-file prototypes as described below to load your library in a compiled application. Note that loading libraries using H-file headers is not supported in compiled applications. This behavior occurs when loadlibrary is compiled with the header argument as in the statement:

loadlibrary(library, header)

In order to work around this issue, execute the following command at the MATLAB command prompt:

loadlibrary(library, header, 'mfilename', 'mylibrarymfile'); 

where mylibrarymfile is the name of an M-file you would like to use when loading this library. This step only needs to be performed once to generate an M-file for the library.

In the code that is be compiled, you can now call loadlibrary with the following syntax:

loadlibrary(library, @mylibrarymfile, 'alias', alias)

With MATLAB Compiler versions 4.0.1 (R14+) and later, generated M-files will automatically be included in the CTF file as part of the compilation process. For MATLAB Compiler versions 4.0 (R14) and later, include your library M-file in the compilation with the -a option with mcc.

Caution   With MATLAB Compiler Version 3.0 (R13SP1) and earlier, you cannot compile calls to loadlibrary because of general restrictions and limitations of the product.

Note   You can use your operating system's loadlibrary function to call a MATLAB Compiler shared library function as long as you first call the initialization and termination functions mclInitializeApplication() and mclTerminateApplication().

Back to Top

Addressing mwArrays Above the 2 GB Limit

C++ Shared Library Target