Main Content

Header and C++ Compiled Library Files onLinux

This example shows how to create a MATLAB®interface to a C++ librarymatrixOperationsfor Linux®by callingclibPublishInterfaceWorkflow．For this example, the library is defined by header filematrixOperations.hppand shared object filelibmwmatrixOperations.so．

MATLAB provides these files in this folder:

fullfile(matlabroot,"extern","examples","cpp_interface");

To create an interface namedmatrixlibfor this library, follow these steps in a workflow script: generate a library definition file, define any missing constructs, build the interface, and then test the interface. If you need to iterate over the publishing process, you can take additional steps to restore parameters and enable out-of-process execution mode. You can then share your published interface with other users.

Create Workflow Script

Navigate to a writeable folder and callclibPublishInterfaceWorkflow．在对话框中,指定workf的名称low script, for example,publishmatrixlib.mlx．The workflow script has steps to help you publish the interface. Use the script to save the parameters for publishing the interface. You can use the same script on all platforms.

Note

The workflow script allows you to repeatedly generate, define, build, and test an interface during multiple MATLAB sessions. However, the script does not save edits to library definition files recreated using theOverwrite existing definition filesoption.

Step 1: GENERATE

First, generate the library definition file. The workflow script contains theGenerate C++ InterfaceLive Editor task for this step. Use this task to select the files that make up the library and to set options for generating the library definition file.

Select files

The library is defined by thematrixOperations.hppheader file and the Windows®matrixOperations.liblibrary file. TheLibrary typeisHeaders and compiled library files, which is the default setting.

To set theLibrary start path, browse to the folderfullfile(matlabroot,"extern","examples","cpp_interface")and clickSelect Folder．

To select the header file, clickBrowseto open the filematrixOperations.hpp．

The header file depends on thecppshrhelp.hppheader file. Navigate to the folder inLibrary start pathand clickSelect Folder．

To select the compiled library file, browse to theglnxa64folder and open thelibmwmatrixOperations.sofile.

Select configuration

In this example, theC++ compileris set tog + +．

ChangeName of interface librarytomatrixlib．Use this name withclibto call functionality from MATLAB. For example, to create a library objectMat, from the command prompt, enter:

clib.matrixlib.Mat

Verify thatOutput folder是一个可写文件夹．

Select theOverwrite existing definition filescheck box so that you can recreate the definition file while developing the interface.

Specify optional C++ library settings

Building the interface to this library does not require optional C++ library settings.

Specify optional definition configurations

Building the interface to this library does not require optional definition configurations.

Display results

By default, when you generate a definition file, the function displays available constructs (classes and functions in the library). While developing the interface, also select theShow unavailable constructscheck box so that you can see what constructs might need more information to be included.

Generate Definition File

ClickGenerate definition file．The script displays its progress and creates the library definition filedefinematrixlib.min the specified output folder.

Warning: Some C++ language constructs in the files for generating interface file are not supported and not imported. Using g++ compiler. Definition file definematrixlib.m contains definitions for 10 constructs supported by MATLAB. - 5 constructs are fully defined. - 5 constructs partially defined and commented out. To include the 5 undefined constructs in the interface, uncomment and complete the definitions in definematrixlib.m. To build the interface, call build(definematrixlib).
MATLAB Interface to matrixlib Library Class clib.matrixlib.Mat Constructors: clib.matrixlib.Mat(clib.matrixlib.Mat) clib.matrixlib.Mat() Methods: uint64 getLength() No Properties defined Functions clib.matrixlib.updateMatByX(clib.matrixlib.Mat,int32)

Enable Tools for Development over Multiple Sessions

While publishing the interface, you might iterate over the steps, close and reopen thepublishmatrixlib.mlxscript, or restart MATLAB. Follow the instructions in these sections to help you with these workflows.

  • Preserve workspace variables across MATLAB sessions. In theRestore library definitionsection, set theoutputFolderPathvariable to the value in theOutput folderparameter. Set thelibraryNameForInterfacevariable to theName of interface libraryparametermatrixlib．Then run the section. For more information, seeRestore Library Definition．

  • Consider running theEnable out-of-process execution modesection. Using this mode while developing an interface eliminates the need to restart MATLAB while testing. After calling functionality in your library, you can unload the library by running theUnload out-of-process librarysection. For more information, seeLoad Out-of-Process C++ Library

Step 2: DEFINE

When you created the library definition file, MATLAB reported that five constructs are partially defined. To completely define the functionality, edit thedefinematrixlib.mfile. To edit the file, run theDEFINEsection.

Scroll through the library definition file to find blocks of commented code for these constructs. MATLAB cannot automatically determine the size of arguments used by these functions.

  • setMat— C++ method for classMat

  • getMat— C++ method for classMat

  • copyMat— C++ method for classMat

  • addMat— C++ package function

  • updateMatBySize— C++ package function

Based on the documentation of thematrixOperationslibrary, you can provide values forin the argument definition statements. For more information, seeDefine Missing SHAPE Parameter．

  1. For each construct, uncomment the statements defining it.

  2. Replacearguments with these values.

    Construct

    Argument Name

    Argument C++ Definition

    Description

    Replacewith Value
    setMat src int [] src

    The length of the matrix is defined by the input argumentlen．

    		 "len"
    getMat RetVal int const *

    The length of the output argument is defined by the input argumentlen．

    		 "len"
    copyMat dest int * dest

    The length ofdestis defined by the input argumentlen．

    		 "len"
    addMat mat Mat const * mat

    The function takes a singlematargument.

    		 1
    updateMatBySize arr int * arr

    The length ofarris defined by the input argumentlen．

    		 "len"

  3. Save and close the definition file.

  4. To validate the edits you made in the file, run theConfirm edits and run summarysection. Fix any reported errors in the file. Thesummaryfunction shows that the interface now includessetMat,getMat,copyMat,addMat, andupdateMatBySize．

MATLAB Interface to matrixlib Library Class clib.matrixlib.Mat Constructors: clib.matrixlib.Mat(clib.matrixlib.Mat) clib.matrixlib.Mat() Methods: setMat(clib.array.matrixlib.Int) clib.array.matrixlib.Int getMat(uint64) uint64 getLength() copyMat(clib.array.matrixlib.Int) No Properties defined Functions int32 clib.matrixlib.addMat(clib.matrixlib.Mat) clib.matrixlib.updateMatByX(clib.matrixlib.Mat,int32) clib.matrixlib.updateMatBySize(clib.matrixlib.Mat,clib.array.matrixlib.Int)

Step 3: BUILD

To build thematrixlibinterface to the library, run theBUILDsection of the script.

Building interface file 'matrixlibInterface.so' for clib package 'matrixlib'. Interface file 'matrixlibInterface.so' built in folder '/home/Documents/MATLAB/matrixlib'. To use the library, add the interface file folder to the MATLAB path. addpath('/home/Documents/MATLAB/matrixlib')

Note

You can repeat the generate, define, and build steps. However, once you display help for or call functions in the library, you cannot update thedefinematrixlibdefinition file in the same MATLAB session. Either restart MATLAB or create a new definition file by changing theName of interface libraryparameter in theSelect configurationsection.

Step 4: TEST

Set up and copy run-time libraries

Run theSet up and copy run-time librariessection. This library does not have additional run-time dependencies, so you do not need to modify the commands.

Enable out-of-process execution mode

如果定义文件的需求to change, run this command to set up the ability to call the interface library out of process so that you do not have to restart MATLAB. For more information, seeLoad C++ Library In-Process or Out-of-Process．

Call help on interface library

To display help for the interface library, run theCall help on interface librarysection.

Write code to call and test interface library

Use the code section inWrite code to call and test interface libraryto write these tests:

matObj = clib.matrixlib.Mat;% Create a Mat objectintArr = [1,2,3,4,5]; matObj.setMat(intArr);% Set the values to intArrretMat = matObj.getMat(5)% Display the values
retMat = read-only clib.array.matrixlib.Int with properties: Dimensions: 5 Resizable: 0

Share Interface

To share the interface with another MATLAB user, create a toolbox installation (．mltbx) file. Using the instructions inDistribute MATLAB Interface to C++ Library:

  • Set the toolbox folder to yourmatrixlibfolder, which contains the interface filematrixlibInterface.so．

  • Put the compiled library filelibmwmatrixOperations.soin the same folder.

  • Identify the namespace (calling syntax) asclib.matrixlib．

See Also

Related Topics