Create a Library

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 must determine if their library is "appropriate".

    For example, to determine whether a library should install or load itself, consider a library that should only run on Linux. 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 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" are immediately included in the Compose GUI highlighting and autocompletion prompting. Function names "immediately visible" are included in the funccount and funclist output in the Compose GUI and Console. Function names not "immediately visible" are always 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 are "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
    • Run a librarymanager('unixlinkadd', <library_directory>, <cell_files>) command to create links for each directory required to run the BCI library.
    • A single command can be used for each directory in the library which contains binary files. If multiple directories contain binary files, a command is required for each directory.
    • For each directory, <cell_files> should be a cell containing the full filename for each binary file required to run the library.
    • Example: { 'libfilename1.so'; 'libfilename2.so' } - Run addlibrary to load the library.
  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'); 
libraryname = 'myname'; 
% root directory of library is its name or can be user defined
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
    Example of cell variable definition:
    library_inicell = {
library_path,			% Full path to library - required
library_name,          	% Library 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 the loader.oml is being run on.

    To do this, call 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 function help is provided like the standard OML functions, accessible from the help() command or by using the F1 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 users with the library’s functions. These help documents are 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 (see Appendix 2 - HTML Help Page Example)
  • Compose recognizes a "<?STOPOUT?>" tag in help *.htm files, which concludes the 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.
Example
The “Cool Library” adds a new function coolfunc(). After this library is installed or loaded:
  1. In the Compose GUI, type coolfunc and press F1.

    Compose looks for the file <library root directory>\help\coolfunc.htm and if it exists, Compose opens the file in the default web browser.

  2. In the OML Command Window of the Compose GUI, and in the Compose Console, type help('coolfunc').

    Compose looks for the file <library root directory>\help\coolfunc.htm and if the file exists, display the text contents of the help file

Please refer to Appendix 2 - HTML Help Page Example for a detailed example of an HTML file.