Integrate a C/C++ Shared Library into an Application

This example shows how to call a C++ shared library built with MATLAB® Compiler SDK™ from a C++ application.

To create a C++ application that calls a MATLAB generated shared library:

  1. Install the MATLAB Runtime and shared library files in one of the following ways.

    • Running the installer generated by MATLAB. It is located in the for_redistribution folder of the deployment project.

      Doing so automatically installs the MATLAB Runtime from the Web and places the shared library folders onto your computer.

    • Manually installing the MATLAB Runtime and the generated shared libraries onto you development system.

      You can download the MATLAB Runtime installer from http://www.mathworks.com/products/compiler/mcr. The generated shared libraries and support files are located in the MATLAB deployment project's for_testing folder.

  2. In the folder containing the generated shared libraries, create a new file called addmatrix.cpp.

  3. Using a text editor, open addmatrix.cpp.

  4. Place the following as the first line in the file.

    #include "addmatrix.h"

    Inserting this statement includes the generated header file for the MATLAB shared library.

  5. Add the following main() function.

    int main()
    {
        mclmcrInitialize();
        return mclRunMain((mclMainFcnType)run_main,0,NULL);
    }

    The main() function does the following:

    • mclmcrInitialize() initializes the MATLAB Runtime so that it is ready to load the MATLAB code required to execute the deployed function.

    • mclRunMain() creates a new thread and runs the MATLAB generated code in it.

  6. Add a run_main() function to the application.

    int run_main(int argc, char **argv)
    {
    }
  7. Add the following code to the top of the run_main() function.

    if (!mclInitializeApplication(NULL,0)) 
      {
        std::cerr << "could not initialize the application properly"
                  << std::endl;
        	return -1;
      }

    The mclInitializeApplication() function sets up the application state for the MATLAB Runtime instance created in the application.

  8. Add the following code below the code initializing the application.

    if( !addmatrixInitialize() )
        {
            std::cerr << "could not initialize the library properly"
                       << std::endl;
    	    return -1;
    	}

    The addmatrixInitialize() function loads the required MATLAB code into the MATLAB Runtime.

  9. Add a try/catch block after the block for addmatrixInitialize().

  10. In the try section of the try/catch block, add the following code.

    // Create input data
    double data[] = {1,2,3,4,5,6,7,8,9};
    mwArray in1(3, 3, mxDOUBLE_CLASS, mxREAL);
    mwArray in2(3, 3, mxDOUBLE_CLASS, mxREAL);
    in1.SetData(data, 9);
    in2.SetData(data, 9);
    
    // Create output array
    mwArray out;

    The code creates three instances of the mwArray class, in1, in2, and out. in1 and in2 passed as input parameters to the addmatirx() function generated by MATLAB. out is the value returned from the addmatirx() function. mwArray is a special class used by MATLAB generated code to facilitate the use of complex arrays.

  11. After the code that initializes the parameters, add the following code to call the addmatirx() function and display the results.

    addmatrix(1, out, in1, in2);
    
    std::cout << "The value of added matrix is:" << std::endl;
    std::cout << out << std::endl;
  12. Add the following catch section to the try/catch block.

    catch (const mwException& e)
      {
        std::cerr << e.what() << std::endl;
        return -2;
      }
    catch (...)
      {
        std::cerr << "Unexpected error thrown" << std::endl;
        return -3;
      }

    The first catch clause catches the MATLAB generated mwException. This exception is thrown by the MATLAB code running in the MATLAB Runtime.

    The second catch clause catches any other exceptions that may be thrown.

  13. Add the following after the try/catch block to terminate the MATLAB Runtime and clean up any resources it was using.

    addmatrixTerminate();
    mclTerminateApplication();
    return 0;

    addmatrixTerminiate() releases the resources used by the generated MATLAB code.

    mclTerminateApplication() releases all state and resources used by the MATLAB Runtime for the application.

  14. Save the C++ file.

    The completed C++ file should resemble the following.

    #include "addmatrix.h"
    
    int run_main(int argc, char **argv)
    {
      if (!mclInitializeApplication(NULL,0)) 
        {
          std::cerr << "could not initialize the application properly"
                    << std::endl;
        	  return -1;
        }
      if( !addmatrixInitialize() )
        {
          std::cerr << "could not initialize the library properly"
                    << std::endl;
    	     return -1;
        }
     
      try
        {
          // Create input data
          double data[] = {1,2,3,4,5,6,7,8,9};
          mwArray in1(3, 3, mxDOUBLE_CLASS, mxREAL);
          mwArray in2(3, 3, mxDOUBLE_CLASS, mxREAL);
          in1.SetData(data, 9);
          in2.SetData(data, 9);
        
          // Create output array
          mwArray out;
                
          // Call the library function
          addmatrix(1, out, in1, in2);
        
          std::cout << "The value of added matrix is:" << std::endl;
          std::cout << out << std::endl;
        }
      catch (const mwException& e)
        {
          std::cerr << e.what() << std::endl;
          return -2;
        }
      catch (...)
        {
          std::cerr << "Unexpected error thrown" << std::endl;
          return -3;
        }
    
      addmatrixTerminate();
      mclTerminateApplication();
      return 0;
    }
    
    int main()
    {
      mclmcrInitialize();
      return mclRunMain((mclMainFcnType)run_main,0,NULL);
    }
  15. Use the system's command line to navigate to the folder where you installed the C++ shared library.

  16. Use mbuild to compile and link the application.

    mbuild addmatrix.cpp addmatrix.lib
  17. From the system's command prompt, run the application.

    addmatrix
    The value of added matrix is:
         2     8    14
         4    10    16
         6    12    18

To follow up on this example:

  • Try installing the new application on a different computer.

  • Try building an installer for the application.

  • Try integrating a shared library that consists of more than one function.

Was this topic helpful?