MATLAB Compiler

C Shared Library Example

This example takes several M-files and creates a C shared library. It also includes a stand-alone 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 stand-alone application's main function.

2. To create the shared library, use

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

1. 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 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 Compiler 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) prior to 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. See Calling a Shared Library for complete details on using a 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 stand-alone application, matrixdriver.exe, on Windows, and matrixdriver, on UNIX.

Difference in the Exported Function Signature.   The interface to the mlf functions generated by the Compiler from your M-file routines has changed from earlier versions of the Compiler. 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 stand-alone 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 stand-alone 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 Testing Components on 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)
  

1. The results are displayed as:

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

Deploying Stand-Alone Applications That Call MATLAB Compiler-Based Shared Libraries

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

Component	Description
MCRInstaller.zip	(UNIX) MATLAB Component Runtime library archive; platform-dependent file that must correspond to the end-user's platform
MCRInstaller.exe	(Windows) Self-extracting MATLAB Component Runtime library utility; platform-dependent file that must correspond to the end-user's platform
unzip	(UNIX) Utility to unzip MCRInstaller.zip (optional). The target machine must have an unzip utility installed.
matrixdriver	Application; matrixdriver.exe for Windows
libmatrix	Shared library; extension varies by platform, for example, DLL on Windows

Note    You can distribute a MATLAB Compiler-generated stand-alone 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 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.

Component	Description
MCRInstaller.zip	(UNIX) MATLAB Component Runtime library archive; platform-dependent file that must correspond to the end-user's platform
MCRInstaller.exe	(Windows) Self-extracting MATLAB Component Runtime library utility; platform-dependent file that must correspond to the end-user's platform
unzip	(UNIX) Utility to unzip MCRInstaller.zip (optional). The target machine must have an unzip utility installed.
libmatrix.ctf	Component Technology File archive; platform-dependent file that must correspond to the end-user's platform
libmatrix	Shared library; extension varies by platform, for example, DLL on Windows
libmatrix.h	Library header file

C Shared Library Target

Calling a Shared Library

© 1994-2005 The MathWorks, Inc.