OML Library Management Features

Use the Library Management commands in OML 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 and so on). It also relies on a loader.oml script to specify precisely what a library should contain, load, and install. Additional details can be found in Create a Library.

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 Management

This section describes the OML language functions that can be used with libraries. The 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 thepath are available for use and are displayed in the Library Browser. Autocompletion is enabled.
addhiddenpath(thepath)
All OML scripts located in thepath 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 not 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 are displayed in autocomplete without actually having to parse and run each file.
addlibrary(thelibraryname .dll or .so)
The OML command to load a binary library. In the context of user-defined libraries, it mostly applies to libraries developed using the BCI Binary Compiler Interface (please refer to the Compose documentation on BCI).
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 (meaning the library is compliant with the requirements and definitions presented above), it can be used inside Compose using the Library Management commands.

Commands Designed by the Compose Console or Compose 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 for use) each time Compose is started.
  • The root directory name is the library's name. Placing library files into directories with meaningful names help 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.
  • It's recommended to use the 'list' command to identify the proper fullpath to use 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 until 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 next.
  • The unload process runs the unload.omc or unload.oml script provided by the library creator in the library root directory.
librarymanager('list')
  • Show 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')
Show more details about installed libraries. Applies only to installed libraries, not loaded libraries.
Details come from the library.ini file with the details originating in the library's loader.oml file as provided by the library creator.
librarymanager('launch')
  • This feature 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, you should not need to run this feature, because the librarymanager'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 library creators.
Features Designed for the loader.oml Function for Individual Libraries
returnlist = librarymanager('scriptlist')
  • Return 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 the 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.
librarymanager('unixlinkadd', library_directory, cell_files)
  • Create symbolic links to run a Unix BCI library.
  • BCI libraries are accessed by symbolic links created in a directory added to the LD_LIBRARY_PATH when Compose is launched. This command is required in the loader.oml (or .omc) file to enable using the BCI library on a Unix system.
  • The library_directory must be the full path to a directory containing the library’s binary files.
  • ‘unixlinkadd’ must run separately for each directory that needs to be added.
  • The variable cell_files should contain an entry with the filename for each binary file required to run the library.
librarymanager('unixlinkdel', cell_files)
  • Delete symbolic links which were created to run a Unix BCI library.
  • This command is required in the unload.oml (or .omc) file to remove link files created to run a BCI library on a Unix system.
  • The variable cell_files should contain an entry with the filename for each binary file required to run the library.
  • A single ‘unixlinkdel’ command can be used to delete all links created to run a BCI library.
librarymanager('unixlinkdir')
  • Return the location of the directory that contains the symbolic links.
  • This action is used internally by both ‘unixlinkadd’ and ‘unixlinkdel’ to obtain the location of the directory.
  • Library creators and users may find this action useful to review the links created to launch BCI libraries.
  • Examples:
    • dir(librarymanager('unixlinkdir'))
    • system( [ 'ls -alF ' librarymanager('unixlinkdir')])