Modify Library Help - MATLAB & Simulink (original) (raw)

Main Content

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 theMicrosoft® Visual C++® 2017 compiler.
• Identify the path myPath to your .hpp and compiled library files. This example uses the library filexerces-c_3.lib.
  includePath = "myPath\include";
  libFile = "myPath\lib\xerces-c_3.lib";
• Identify the header files required for your interface. This example uses theXMLPlatformUtils.Initialize method from thePlatformUtils.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 filedefineMyXercesLibrary.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 forlocale 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."); % '' 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 andmemoryManager 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 must 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 must 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:

• 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 must 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()

See Also

Topics

• Define MATLAB Interface for C++ Library
• Publish Help Text for MATLAB Interface to C++ Library