Create a Library in OML

Loader.oml Files

Each library must include a loader.oml script to verify the library is appropriate for the environment/computer where the installation is being attempted.

The loader.oml script must perform the following actions.
  1. Delete the library.ini file if it exists.

    This file should be recreated before the script terminates if the function is "appropriate". Library creators will need to determine if their library is "appropriate".

    For example, to determine whether a library should install or load itself:
    • Perhaps a library should only run on a Linux environment. If the loader.oml is run on a non-Linux computer, the loader.oml should quietly fail.
  2. Create a list of available functions.
    Libraries containing OML scripts should create a cell variable containing a list of function names to be immediately visible in the OML interpreter.
    Note: After the OML function scripts are run, the function is always visible in the OML interpreter.
    This list can be hard coded in the script. For example:
    library_functionlist = { 'demo1func1' ; 'demo1func2' };
    This list can be created in the loader.oml script using the feature:
    returnlist = librarymanager('scriptlist')

    This list is used as the second argument in the registerpath() OML function.

    Function names "immediately visible" will immediately be included in the Compose GUI highlighting and autocompletion prompting. Function names "immediately visible" will be included in the funccount and funclist output in the Compose GUI and Console. Function names not "immediately visible" will always be visible after the function script is run.

  3. Run registerpath().
    Libraries containing OML scripts should run registerpath(), providing arguments for:
    • The full path to the script directory.
    • A cell variable with a list of functions, which will be "immediately visible" .
  4. BCI libraries have the following requirements:
    On Windows:
    • Add the library's <rootdir>\bin\win64 directory to the system path.
    • Run addlibrary to load the DLL.
    On Linux:
    • Specify the full path name to the "so" file, <rootdir>/bin/linux64/lib<filename>.so
    • Run addlibrary using the full path name.
  5. Create a cell variable, providing the following information about the library:
    library_path = [fileparts(omlfilename('fullpath'))];  
           % This is the full path to the library directory
    libraryname = librarymanager('libraryname'); 
           % root directory of library is its name
    library_version = '01.00';  
           % specified by the library creator
    library_shortdescription = 'Brief description of the library';
           % specified by the library creator
    library_longdescription = 'Expanded description of the library’;
           % specified by the library creator
    Cell variable definition example:
    library_inicell = {
    library_path,                 % Full path to library - required
    library_name,                 % Library Directory Name - required
    library_version,              % Library Version Number - required 
    library_shortdescription,     % Library Description - can be an empty string
    library_longdescription       % Library Description - can be an empty string
    };
  6. Create the library.ini file in the library root directory, if the library is appropriate for the environment on which the loader.oml file is being run.

    This is done calling librarymanager('saveini',cell_settings) with the library directory, name, version, and short and long descriptions. The 'saveini' feature writes the function information to create the library.ini file in the root directory. This file is read and provides information for the 'listdetail' feature.

Documentation for a Compose OML Library

The Compose OML library functions' help will be provided to end users for standard OML functions, either by using the help() command or pressing F1 for context sensitive help.

The help pages are:
  • .htm files.
  • One file per function.
  • Located in the help/ folder of the library.

Library creators may provide help files to assist you with your library’s functions. These help documents will be integrated with Compose help features if they follow the specifications listed below.

Library help documents should be:
  • Located in the <library root directory>\help directory.
  • Named <functionname>.htm
  • Formatted .
  • Compose recognizes a "<?STOPOUT?>" tag in the help *.htm files, which concludes help file output when using the Compose help() function.
  • Library creators are advised to test their help documents using Compose to verify the output meets their expectations.
For example, the “Cool Library” adds a new function coolfunc(). After this library is installed or loaded:
  • In the Compose GUI, type coolfunc and press F1. Compose looks for the file <library root directory>\help\coolfunc.htm and if it exists, it opens the file in the default browser.
  • In the Compose GUI , OML Command Window, and Compose Console, type help('coolfunc'). Compose looks for the file <library root directory>\help\coolfunc.htm and if the file exists, Compose displays the text contents of the help file.