OM# Documentation

How to make an external library ?

OM# external libraries are folders containing Lisp code to be loaded dynamically in the environment.

See also: External libraries

The few following rules make for the library to smoothly integrate and run in the environment:

Structure and Naming

• The name of the library is the name of the folder before the first white space (“my-lib”, “my-lib 1.0”, …)
• The folder should contain a file of this name, with the extension “olib” (e.g. “my-lib.olib”)
• A subfolder sound contain the sources (optional)
• A subfolder named “resources” should contain the resources, and in particular another subfolder named “icons”

Note: the extension “.omlib” is also supported.

my-lib/
  |---- my-lib.olib
  |---- sources/
           |---- file-1.lisp
           |---- file-2.lisp
           |---- ...
  |---- resources/
           |---- icons/
                   |---- icon1.png
                   |---- icon2.png
                   |---- ...
           |---- ...

Warning: GitHub users/downloaders – when downloading a repository (say, for the library “my-lib”), GitHub may append the name of the branch to the downloaded packages (“my-lib-master.zip”, etc.), preventing the lib to be recognised for its true name. If this is the case, just rename the folder after downloading it.

Contents and syntax of the .olib file

The .olib file (my-lib.olib) contains list with the information necessary to display and load the library in OM#:

(:om-lib

 (:version 1.0)
 (:doc "This library does great things.")
 (:author "My Name (2019)")

 (:source-files
    "sources/file-1" 
    "sources/file-2"
    ...
    ) 

 (:symbols
  (:classes c1 c2 ...) 
  (:functions fun1 fun2 ...)
  (:packages
   (:package 
    (:name "sub-package 1")
    (:functions ...))
   ...
   ))
)

Notes:

:source-files must be followed by a number of relative pathnames (relative to the root folder of the library) designating the name and order of the source files to load. If the pathname has no extension (“.lisp”, “.xfasl”, etc.) the compiled version (“.*fasl”) of the source file will be loaded if available and up-to-date. Otherwise, the .lisp version of the file is loaded.

Compiled lisp files are generally more efficient. They require specific compilation tools and are not portable cross-platform.

:symbols determines the classes (:classes) and functions (:functions) that will be displayed explicitly in the user interface for this library (Packages Library, menus, auto-completion lists, auto-generated documentation, etc.)

The symbols can also be gathered in “sub-packages”:

(:packages
   (:package 
    (:name "sub-package 1")
    (:functions ...))
   ...
   )

Adapting an OpenMusic library

In general for a simple library (and if the code inside the source files is compatible!), adapting an OpenMusic library mostly requires making the .olib file from the corresponding “.lisp” loader-file of the library (my-lib.lisp).

Note that my-lib.lisp and my-lib.olib can both stay in the library folder, making the library compatible with both OpenMusic and OM#.