Relocation files

There’s actually a second mechanism for run-time configuration: LilyPond heavily relies on external programs and libraries, in particular the ‘FontConfig’ and ‘Guile’ libraries to find system fonts and handle Scheme files, respectively, and the gs program to convert PS data to PDF files. All of them must be configured also to locate its relevant data files. To do that, the lilypond program parses all files in a directory called relocate (if it exists; see below where this directory is searched for) to manipulate environment variables, which in turn control those external libraries and programs. The format of such relocation files is simple; each line has the syntax

command key=value

and empty lines get ignored.

The command directive is one of the following.

set

Uncondionally set environment variable key to value. This overrides a previously set value.

set?

Set environment variable key to value only if key isn’t defined yet. In other words, it doesn’t override a previously set value.

setdir

If value is a directory, unconditionally set environent variable key to value. Otherwise, emit a warning.

setfile

If value is a file, unconditionally set environent variable key to value. Otherwise, emit a warning.

prependdir

Prepend directory value to the list of directories in environment variable key. If key doesn’t exist it gets created.

Environment variables (marked with a leading dollar sign) are allowed in value and get expanded before the directive is executed.

Here are two examples of relocation file entries.

set? FONTCONFIG_FILE=$INSTALLER_PREFIX/etc/fonts/fonts.conf
prependdir GUILE_LOAD_PATH=$INSTALLER_PREFIX/share/guile/1.8

Multiple lines setting the same environment variable should be avoided in relocation files since the parsing order of files in the relocate directory is arbitrary.