Library Management

The Library Management commands in OML provide features to:
  • Create a library.
  • Load a library.
  • Install a library.
  • Uninstall a library.

The library relies on the OML language features to load scripts and functions (path, for example) described above. It also relies on a loader.oml script to specify precisely what a library should contain, load, and install.

The protection of a library relies on:
  • The ability to encrypt the scripts (for example, convert loader.oml into loader.omc).
  • Licensing features.

OML Commands for Library Creation and Loading/Unloading

This section explains the OML language functions that can be useful for libraries. These OML commands are used extensively in the loader.oml and unload.oml scripts to specify the scripts and functions to be added and exposed in the library.
addpath(thepath)
All OML scripts located in the path are available for use and appear in the Library Browser and autocompletion is enabled.
addhiddenpath(thepath)
All OML scripts located in the path are available for use, but do not appear in the Library Browser and autocompletion is not enabled. Usually, this is for utility functions provided by the library, but are not supposed to be visible or used directly by the end user.
registerpath(thepath)
An extension of addpath(). The second argument is a cell array of function names to be pre-registered. These appear in autocomplete, and so on, without actually having to parse and run each file.
addlibrary(thelibraryname.dll or .so)
This OML command loads a binary library. In the context of user-defined libraries, it mostly applies to libraries developed using the BCI (Binary Compiler Interface) Please see Write a C/C++ OML Library Using the Binary-compatible Interface.
removepath(thepath)
The opposite of addpath().
removehiddenpath(thepath)
The opposite of addhiddenpath().
removelibrary(thelibrary.dll or .so)
The opposite of addlibrary().

OML Library Management Commands

Once a library is created (the library is compliant with the requirements and definitions presented above), it can be used inside Compose using the Library Management commands.

Commands designed for use by the Compose Console or GUI user:
Commands designed for use by the Console or GUI user:
librarymanager('install', '<fullpath to library root directory>')
  • The install process runs the loader.omc or loader.oml script provided by the library creator in the library root directory.
  • An installed library is active (loaded and ready to use) each time Compose is started.
  • The root directory name is the library's name. Placing library files into directories with meaningful names helps identify them.
librarymanager('uninstall', '<fullpath to library root directory>')
  • The uninstall process runs the unload.omc or unload.oml script provided by the library creator in the library root directory.
  • An uninstalled library is not loaded when Compose is started.
  • The 'uninstall' command searches for an exact match in the library list table and removes the library entry from that table.
  • Use of the 'list' command is recommended to identify the proper full path for use in the 'uninstall' command.
librarymanager('load', '<fullpath to library root directory>')
  • A loaded library remains exposed and available during the current Compose session until unloaded or the Compose session is ended. When Compose is started, a library “loaded” in a previous session won’t be loaded automatically.
  • The load process runs the loader.omc or loader.oml script provided by the library creator in the library root directory.
librarymanager('unload', '<fullpath to library root directory>')
  • An unloaded library is no longer active (not exposed, not available) during the current Compose session. An installed library is not uninstalled by unload and is activated (exposed and available) when Compose is started again.
  • The unload process runs the unload.omc or unload.oml script provided by the library creator in the library root directory.
librarymanager('list')
  • Displays brief details about installed libraries. Applies only to installed libraries, not loaded libraries.
  • Displays the installed library paths from the library installation table.
librarymanager('listdetail')
  • Displays more details about installed libraries. Applies only to installed libraries, not loaded libraries.
  • Details originate from the library.ini file, with the details originating in the library's loader.oml file.
librarymanager('launch')
  • Runs the load process for each installed directory. In practice, this means the loader.oml (or loader.omc) script is executed for the library.
  • Ordinarily, library manager users should not need to run this feature because the library manager's loader.oml runs this function. However, running this feature after OML has launched may provide useful information during the load sequence depending on messaging provided by the library creator.
Features designed for use in the loader.oml function for individual libraries:
returnlist = librarymanager('scriptlist')
  • Returns a cell containing all filenames in the scripts/oml directory.
  • Each *.oml file under scripts/oml is assumed to be a script containing an OML function. If this is not the case, the 'scriptlist' option provides an incorrect function list and should not be used.
libraryname = librarymanager('libraryname')
  • Root directory of library is its name.
  • The 'libraryname' option returns the library's root directory name. Again, this is considered to be the library's name. You are encouraged to place libraries in directories with meaningful folder names.
librarymanager('saveini', cell_settings)
  • Write the library.ini file in the root directory.
  • The variable cell_settings must contain the library root directory, library descriptive name, library version, library short description, and long description.