General Library Structure

Basic Interface for Library Writers

TODO: All of the following should be moved to a dedicated Contributor's Guide. It was a bad idea in the first draft to mix things up that way.

Each library lives in the repository's /ly directory and the top-level directory name corresponds to the library name.

Library Initialization

A library can have a file __init__.ly inside its main directory. If present this file is read before for the first time any module from within the library is loaded. So you can use that file for setting up any common infrastructure, for example to initialize shared variables.

Configuration Management

It is strongly recommended that libraries use configuration variables to control their behaviour (if any kind of behaviour control is appropriate for the library). For this openLilyLib provides a unified infrastructure as already described above. A library can maintain any number of (nested) options that are centrally managed through openLilyLib. To make options known to the system (and accessible to the user) use the \registerOption command in the library's __init__.ily file:

\registerOption <library.path.to.option> <default>
% Example
\registerOption test.my.option "Hello"
\registerOption test.my.other-option #f

Options specified this way can be retrieved with \getOption as described above, and the user can use \setOption to configure the library's behaviour in concrete projects.

Options can have any kind of Scheme value, which also includes (nested) lists or even music expressions (for example key or time signatures or markup). It is up to the library maintainers to make use of that variety, but may we will provide extended functionality to manage complex options in the future.

Directory Structure

Generally we suggest libraries to have flat directory structures, that is usually all files should live within the root directory of the library. A hierarchical representation is set up through the metadata and tags in particular. However it is of course possible to use subdirectories to group functionality that belongs together.

Loading Modules and Individual Units

Any directory (and this includes the library's root directory) can contain a __main__.ily file which represents the directory as a module. Loading that file is considered loading that module, and the file should behave accordingly and load the whole module. The main files are not loaded directly but by passing the containing directory name as the argument to \loadModule. If there is a library test containing a sub directory containing a __main__.ily file then \loadModule "test/sub" will load __main__.ily from within test. If you want users to be able to load the library as a whole write the appropriate code in test/__main__.ily.