Main Content

Modify Library Help

This example shows how to modify help generated for a MATLAB® interface to a C++ library.

This example shows help for the XMLPlatformUtils.Initialize method in the Apache® Xerces-C++ XML parser library. This content comes from the Apache Xerces project, https://xerces.apache.org, and is licensed under the Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0.

To build a MATLAB interface to this library, you need the header files and compiled library files. This example describes the build process and shows the output of building such a library. You cannot, however, execute the code shown in the example, unless you have access to the Xerces files.

Set Up

For information about setting up your environment, see Requirements for Building Interface to C++ Libraries.

  • Verify your compiler. This example assumes the library file was built with the Microsoft® Visual C++® 2017 compiler.

    mex -setup cpp
  • Identify the path myPath to your .hpp and compiled library files. This example uses the library file xerces-c_3.lib.

    includePath = "myPath\include";
    libFile = "myPath\lib\xerces-c_3.lib";
  • Identify the header files required for your interface. This example uses the XMLPlatformUtils.Initialize method from the PlatformUtils.hpp file.

    headers = includePath+"\xercesc\util\PlatformUtils.hpp";
    

Define MATLAB Interface

For information about defining the interface, see Define MATLAB Interface for C++ Library.

  • Generate the library definition file defineMyXercesLibrary.m.

    clibgen.generateLibraryDefinition(headers, ... 
        "IncludePath",includePath, ... 
        'Libraries',libFile, ... 
        "Verbose",true, ... 
        "InterfaceName","MyXercesLibrary")
  • Edit the defineMyXercesLibrary.m file. This example resolves undefined functionality for the Initialize method only. Search for:

    C++ Signature: static void xercesc_3_1::XMLPlatformUtils::Initialize
  • Update the defineArgument statements for locale and nlsHome to be null-terminated strings by replacing <MLTYPE> with "string" and <SHAPE> with "nullTerminated". For information about updating the code, see Define Missing SHAPE Parameter.

    defineArgument(InitializeDefinition, "locale", "string", "input", "nullTerminated", ...
        "Description", "locale The locale to use for messages."); % '<MLTYPE>' can be clib.array.xerces.Char,int8,string, or char 
    defineArgument(InitializeDefinition, "nlsHome", "string", "input", "nullTerminated", ...
        "Description", "nlsHome User specified location where MsgLoader retrieves error message files." + newline + ... 
    
  • In the same method, define the panicHandler and memoryManager arguments as scalar by replacing <SHAPE> with 1.

    defineArgument(InitializeDefinition, "panicHandler", ...
        "clib.MyXercesLibrary.xercesc_3_1.PanicHandler", "input", 1, ...
        "Description", "panicHandler Application's panic handler, application owns this handler." + newline + ...
    defineArgument(InitializeDefinition, "memoryManager", ...
        "clib.MyXercesLibrary.xercesc_3_1.MemoryManager", "input", 1, ...
        "Description", "memoryManager Plugged-in memory manager which is owned by the" + newline + ...
  • Validate the library definition file and resolve any errors.

    libDef = defineMyXercesLibrary

Update Generated Help Text

  • Review the auto-generated help text.

    className = "xercesc_3_1::XMLPlatformUtils";
    methodName = "Initialize";
    for i = 1:numel(libDef.Classes)
        if (matches(libDef.Classes(i).CPPName,className))
            classID = i;
            for j = 1:numel(libDef.Classes(i).Methods)             
                 if (startsWith(libDef.Classes(i).Methods(j).MATLABSignature,methodName))
                    methodID = j;
                 end
            end
        end
    end
    Description = libDef.Classes(classID).Methods(methodID).Description                 
    DetailedDescription = libDef.Classes(classID).Methods(methodID).DetailedDescription
    Description = 
        "clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize    Method of C++ class xercesc_3_1::XMLPlatformUtils.
         Perform per-process parser initialization"
    DetailedDescription = 
        "This content is from the external library documentation.
         
         Initialization <b>must</b> be called first in any client code."
    
  • Modify the text This content is from the external library documentation to display information about the Apache Xerces project. Open the library definition file.

    edit defineMyXercesLibrary
  • Search for the xercesc_3_1::XMLPlatformUtils::Initialize method:

    C++ Signature: static void xercesc_3_1::XMLPlatformUtils::Initialize
  • In the DetailedDescription argument, replace This content is from the external library documentation with the new content. The line now reads:

    "DetailedDescription", "This content comes from the Apache Xerces project, https://xerces.apache.org, and is licensed under the " + newline + ...
    "Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0." + newline + ...
    
  • Save the file.

  • Review the updated help text.

    libDef = defineMyXercesLibrary;
    libDef.Classes(classID).Methods(methodID).DetailedDescription
    ans = 
        "This content comes from the Apache Xerces project, https://xerces.apache.org, and 
         is licensed under the Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0.
         
         Initialization <b>must</b> be called first in any client code."
    

Build Library and Display Help

  • build(defineMyXercesLibrary)
  • Add the library to your path. Either click the link in the message or type:

    addPath(MyXercesLibrary)
  • Update the system path, identifying the location myPath of your library file.

    dllPath = "myPath\lib"; 
    syspath = getenv("PATH"); 
    setenv("PATH",dllPath+";"+syspath)
  • Review the contents.

    summary(defineMyXercesLibrary)
  • Display help for the Initialize method.

    help clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize
     clib.MyXercesLibrary.xercesc_3_1.XMLPlatformUtils.Initialize    Method of C++ class xercesc_3_1::XMLPlatformUtils.
        Perform per-process parser initialization
    
        This content comes from the Apache Xerces project, https://xerces.apache.org, and is licensed under the 
        Apache 2.0 license, https://www.apache.org/licenses/LICENSE-2.0.
        
        Initialization <b>must</b> be called first in any client code.
    
        Inputs
          locale         read-only string  
          locale The locale to use for messages.
    
          nlsHome        read-only string  
          nlsHome User specified location where MsgLoader retrieves error message files.
          the discussion above with regard to locale, applies to nlsHome as well.
    
          panicHandler   clib.MyXercesLibrary.xercesc_3_1.PanicHandler  
          panicHandler Application's panic handler, application owns this handler.
          Application shall make sure that the plugged panic handler persists
          through the call to XMLPlatformUtils::Terminate().
    
          memoryManager  clib.MyXercesLibrary.xercesc_3_1.MemoryManager  
          memoryManager Plugged-in memory manager which is owned by the
          application. Applications must make sure that the
          plugged-in memory manager persist through the call to
          XMLPlatformUtils::Terminate()
    

Related Topics