LilyPond Application Usage: 1.2 Command-line usage

## 1.2 Command-line usage

This section contains extra information about using LilyPond on the command-line. This may be desirable to pass extra options to the program. In addition, there are certain extra ‘helper’ programs (such as `midi2ly`) which are only available on the command-line.

By ‘command-line’, we mean the command line in the operating system. Windows users might be more familiar with the terms ‘DOS shell’ or ‘command shell’. MacOS X users might be more familiar with the terms ‘terminal’ or ‘console’. Some additional setup is required for MacOS X users; please see MacOS X.

Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command-line.

### Invoking `lilypond`

The `lilypond` executable may be called as follows from the command line.

>     lilypond [option]… file…

When invoked with a filename that has no extension, the ‘`.ly`’ extension is tried first. To read input from stdin, use a dash (`-`) for file.

When ‘`filename.ly`’ is processed it produces ‘`filename.pdf`’ as output by default. Several files can be specified; they are each processed independently.1

If ‘`filename.ly`’ contains more than one `\book` block, the rest of the scores is output in numbered files, starting with ‘`filename-1.pdf`’. In addition, the value of `output-suffix` is inserted between the basename and the number. For example, if ‘`filename.ly`’ contains

>     #(define output-suffix "violin")
>     \score { … }
>     #(define output-suffix "cello")
>     \score { … }

LilyPond outputs ‘`filename-violin.pdf`’ and ‘`filename-cello-1.pdf`’.

#### Using LilyPond with standard shell features

Since LilyPond is a command line application, features of the ‘shell’ used for calling LilyPond can also be put to good use.

For example,

>     lilypond *.ly

processes all LilyPond files in the current directory.

Redirecting the console output (e.g., to a file) may also be useful:

>     lilypond file.ly 1> stdout.txt
>     lilypond file.ly 2> stderr.txt
>     lilypond file.ly &> all.txt

The above commands divert ‘normal’ output, ‘errors’ only, or ‘everything’, respectively, to text files. Consult the documentation for your particular shell, Command (Windows), Terminal or Console applications (MacOS X) to check whether output redirection is supported or if the syntax is different.

The following example searches and processes all input files in the current directory and all directories below it recursively. The output files are located in the same directory that the command was run in, rather than in the same directories as the original input files.

>     find . -name '*.ly' -exec lilypond '{}' \;

This should also work for MacOS X users.

A Windows user would run

>     forfiles /s /M *.ly /c "cmd /c lilypond @file"

entering these commands in a `command prompt` usually found under `Start > Accessories > Command Prompt`, or by typing in the search window ‘command prompt’.

Alternatively, an explicit path to the top-level of your folder containing all the sub-folders that have input files in them can be stated using the `/p` option;

>     forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @file"

If there are spaces in the path to the top-level folder, then the whole path needs to be inside double quotes;

>     forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @file"

### Basic command line options for LilyPond

The following options are supported.

`-d`, `--define-default=`var[`=`val]

  See Advanced command line options for LilyPond.

`-e`, `--evaluate=`expr

  Evaluate the Scheme expr before parsing any ‘`.ly`’ files. Multiple ‘`-e`’ options may be given, they are evaluated sequentially.

  The expression is evaluated in the `guile-user` module, so if you want to use a definition like `(define-public a 42)` as expr, use

  >     lilypond -e '(define-public a 42)'

  on the command-line, and include

  >     #(use-modules (guile-user))

  at the top of the ‘`.ly`’ file.

  Note: Windows users must use double quotes instead of single quotes.

`-E`, `--eps`

  Generate EPS files.

  This option is equivalent to setting LilyPond’s command line options `--ps`, `-dbackend=eps`, and `-daux-files='#f'`.

`-f`, `--format=`format

  The format of the (main) output file or files. Possible values for format are `ps`, `pdf`, `png` or `svg`.

  Example: `lilypond -fpng foo.ly`

  SVG internally uses a specific backend, and therefore cannot be obtained in the same run as other formats; using `-fsvg` or `--svg` is actually equivalent to using the `-dbackend=svg` option. See Advanced command line options for LilyPond.

`-h`, `--help`

  Show a summary of usage.

`-H`, `--header=`field

  Dump a header field to file ‘`BASENAME.field`’.

  As an example, let’s assume that you have an input file ‘`foo.ly`’ containing

  >     \header { title = "bar" }
  >     \score { c1 }

  The command

  >     lilypond -H title foo.ly

  then creates a plain text file ‘`foo.title`’ containing the string `bar`.

`-i`, `--init=`file

  Set init file to file (default: ‘`init.ly`’).

`-I`, `--include=`directory

  Append directory to the search path for input files with relative paths. By default, only the current working directory gets searched.

  Multiple ‘`-I`’ options may be given. The search starts in the current working directory, and if the file to be included is not found the search continues in the directory given by the first ‘`-I`’ option, then the directory in the second ‘`-I`’ option, and so on.

  Note: Using the tilde character (`~`) with the ‘`-I`’ switch may produce unexpected results in some shells.

  Windows users need to include a trailing slash for the directory’s path.

`-j`, `--jail=`user`,`group`,`jail`,`dir

  [This option is only available if your operating system supports the `chroot` functionality. In particular, Windows doesn’t support it.]

  Run `lilypond` in a chroot jail.

  The ‘`--jail`’ option provides a more flexible alternative to ‘`-dsafe`’, when LilyPond formatting is being provided via a web server, or whenever LilyPond executes commands sent by external sources (see Advanced command line options for LilyPond).

  It works by changing the root of `lilypond` to jail just before starting the actual compilation process. The user and group are then changed to match those provided, and the current directory is changed to dir. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for ‘`--jail`’ to work, `lilypond` must be run as root, which is usually accomplished in a safe way using `sudo`.

  Setting up a jail can be a relatively complex matter, as we must be sure that LilyPond is able to find whatever it needs to compile the source inside the jail itself. A typical chroot jail comprises the following steps:

  Setting up a separate filesystem

    A separate filesystem should be created for LilyPond, so that it can be mounted with safe options such as `noexec`, `nodev`, and `nosuid`. In this way, it is impossible to run executables or to write directly to a device from LilyPond. If you do not want to create a separate partition, just create a file of reasonable size and use it to mount a loop device. A separate filesystem also guarantees that LilyPond cannot write more space than it is allowed.

  Setting up a separate user

    A separate user and group (say, `lily`/`lily`) with low privileges should be used to run LilyPond inside the jail. There should be a single directory writable by this user, which should be passed in dir.

  Preparing the jail

    LilyPond needs to read a number of files while running. All these files are to be copied into the jail, under the same path they appear in the real root filesystem. The entire content of the LilyPond installation (e.g., ‘`/usr/share/lilypond`’) should be copied.

    If problems arise, the simplest way to trace them down is to run LilyPond using `strace`, which allows you to determine which files are missing.

  Running LilyPond

    In a jail mounted with `noexec` it is impossible to execute any external program. Therefore LilyPond must be run with a backend that does not require any such program. As we have already mentioned, it must be run with superuser privileges (which, of course, it loses immediately), possibly using `sudo`. It is also good practice to limit the number of seconds of CPU time LilyPond can use (e.g., using `ulimit -t`), and, if your operating system supports it, the amount of memory that can be allocated. Also see LilyPond in chroot jail.

`-l`, `--loglevel=`level

  Set the verbosity of the console output to level. Possible values are:

  `NONE`

    No output at all, not even error messages.

  `ERROR`

    Only error messages, no warnings or progress messages.

  `WARN`

    Warnings and error messages, no progress.

  `BASIC_PROGRESS`

    Basic progress messages (success), warnings and errors.

  `PROGRESS`

    All progress messages, warnings and errors.

  `INFO`

    Progress messages, warnings, errors and further execution information. This is the default.

  `DEBUG`

    All possible messages, including verbose debug output.

`-o`, `--output=`file
`-o`, `--output=`folder

  Set the default output file to file or, if a folder with that name exists, direct the output to folder, taking the file name from the input file. The appropriate suffix is added (e.g., ‘`.pdf`’ for PDF) in both cases.

`-O`, `--pspdfopt=`key

  Set the PS/PDF output optimization to key. Possible values are:

  `size`

    Generate a very small PS/EPS/PDF document. This is the default.

    Using this value is equivalent to setting LilyPond’s Scheme command line options `-dmusic-font-encodings='#f'` and `-dgs-never-embed-fonts='#f'`.

  `TeX`

    Produce files that are optimized for inclusion in pdfTeX, luatex, or XeTeX documents.

    Using this value is equivalent to setting LilyPond’s Scheme command line options `-dmusic-font-encodings='#t'` and `-dgs-never-embed-fonts='#f'`.

  `TeX-GS`

    If you want to include more than one PDF generated by LilyPond in a TeX document, use this option and postprocess the PDF generated by TeX with Ghostscript.

    Using this value is equivalent to setting LilyPond’s Scheme command line options `-dmusic-font-encodings='#t'` and `-dgs-never-embed-fonts='#t'`.

`--ps`

  Generate PostScript. This option is equivalent to `-fps`.

`--png`

  Generate pictures of each page, in PNG format. This option is equivalent to `-fpng`.

  The resolution of the image may be set to N DPI with

  >     -dresolution=N

`--pdf`

  Generate PDF. This is the default, being equivalent to `-fpdf`.

`-s`, `--silent`

  Show no progress, only error messages. This is equivalent to `-lERROR`.

`--svg`

  Generate SVG files for each page. This option is equivalent to `-fsvg`.

`-v`, `--version`

  Show version information.

`-V`, `--verbose`

  Be verbose: show full paths of all files read, give timing information, etc. It is equivalent to `-lDEBUG`.

`-w`, `--warranty`

  Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

### Advanced command line options for LilyPond

Option ‘`-d`’ is the command-line interface to LilyPond’s Scheme function `ly:set-option`. This means that all options listed here can also be set within ‘`.ly`’ files.

`-d`, `--define-default=`option-name[`=`value]
`-d`, `--define-default=no-`option-name

  Set the equivalent internal Scheme symbol option-name to value. For example, the command-line option

  >     -dbackend=svg

  is equivalent to

  >     #(ly:set-option 'backend 'svg)

  in a LilyPond input file.

  If value is not supplied, use `#t` as the value (which might produce strange results if the expected value type is not boolean). The prefix `no-` may be added to option-name to switch ‘off’ an option, providing `#f` as the value. For example,

  >     -dpoint-and-click='#f'

  is the same as

  >     -dno-point-and-click

[Note that the ‘`#`’ character introduces a comment in many shells. For this reason it is recommended to always quote expressions that contain it.]

The following table lists all supported option names together with its values. Within Scheme code, option values can be read using function `ly:get-option`.

`anti-alias-factor` num

  Render at a higher resolution (using factor num, which must be a positive integer ≤8) and scale down the result to prevent ‘jaggies’ in PNG images. Default: `1`.

`aux-files` bool

  If bool is `#t`, create ‘`.tex`’, ‘`.texi`’, and ‘`.count`’ files when used with the `eps` backend option. Default: `#t`.

`backend` symbol

  Use symbol as the backend for LilyPond output. Possible values are:

  `ps`

    This is the default setting. PostScript files include TTF, Type1, and OTF fonts. No ‘subsetting’ of these fonts is done. Be aware that using ‘oriental’ character sets like Japanese can lead to very large file sizes.

    For PDF output, the `ps` backend is used, too; the resulting PS data is post-processed by Ghostscript’s `ps2pdf` script, which also does font subsetting by default.

  `eps`

    Used as the default by the `lilypond-book` command. This dumps every page as both a single file with all pages and fonts included and as separate encapsulated PostScript files for each page but without fonts included.

  `null`

    Do not output a printed score. This has the same effect as `-dno-print-pages`.

  `scm`

    This dumps out the raw, internal Scheme-based drawing commands.

  `svg`

    Scalable Vector Graphics. A single SVG file is created for every page of output. Music glyphs are encoded as vector graphics, but text fonts are not embedded in the SVG files. Any SVG viewer will therefore need the relevant text fonts to be available to it for proper rendering of both text and lyrics. It is recommended to not use font ‘lists’ or ‘aliases’ in case an SVG viewer is unable to handle them. When using Web Open Font Format (WOFF) files the additional `-dsvg-woff` switch is required.

`check-internal-types` bool

  If bool is `#t`, check every property assignment for types. Default: `#f`.

`clip-systems` bool

  If bool is `#t`, extract music fragments out of a score. This requires that the `clip-regions` function has been defined within the `\layout` block. See music Extracting fragments of music. No fragments are extracted though if used with the ‘`-dno-print-pages`’ option. Default: `#f`.

`crop` bool

  If bool is `#t`, fit all the music and headers, without margins, into a ‘single-page’ output file. Default: `#f`.

`datadir`

  Prefix for data files. This is a read-only option; setting it has no effect.

`debug-gc` bool

  If bool is `#t`, dump memory debugging statistics. Default: `#f`.

`debug-gc-assert-parsed-dead` bool

  For memory debugging: If bool is `#t`, ensure that all references to parsed objects are dead. This is an internal option, and is switched on automatically for `-ddebug-gc`. Default: `#f`.

`debug-lexer` bool

  If bool is `#t`, debug the flex lexer. Default: `#f`.

`debug-page-breaking-scoring` bool

  If bool is `#t`, dump scores for many different page breaking configurations. Default: `#f`.

`debug-parser` bool

  If bool is `#t`, debug the bison parser. Default: `#f`.

`debug-property-callbacks` bool

  If bool is `#t`, debug cyclic callback chains. Default: `#f`.

`debug-skylines` bool

  If bool is `#t`, debug skylines. Default: `#f`.

`delete-intermediate-files` bool

  If bool is `#t`, delete the unusable, intermediate ‘`.ps`’ files created during compilation. Default: `#t`.

`dump-signatures` bool

  If bool is `#t`, dump output signatures of each system. Used for regression testing. Default: `#f`.

`embed-source-code` bool

  If bool is `#t`, embed the LilyPond source files inside the generated PDF document. Default: `#f`.

`eps-box-padding` num

  Pad left edge of the output EPS bounding box by num millimeters. Default: `#f` (meaning no bounding box padding).

`font-export-dir` string

  Set directory for exporting fonts as PostScript files to string. This is useful when you want to create a PDF without embedded fonts first and later embed the fonts with Ghostscript as shown below.

  >     $ lilypond -dfont-export-dir=fontdir -dgs-never-embed-fonts foo.ly
  >     $ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
  >          -sOutputFile=foo.embedded.pdf foo.pdf fontdir/*.font.ps

  Note: Unlike `font-ps-resdir`, this method cannot embed CID fonts with Ghostscript 9.26 and later.

  Note: Same as `font-ps-resdir`, this option skips TrueType fonts because embedding TrueType fonts later causes garbled characters. To avoid garbling characters, use `gs-never-embed-fonts`, as this embeds TrueType fonts despite its name.

  Default: `#f` (meaning not to export).

`font-ps-resdir` string

  Set directory (as string) to build a subset of the PostScript resource directory to be used for embedding fonts later. This is useful when you want to create a PDF without embedded fonts first and later embed the fonts with Ghostscript as shown below.

  >     $ lilypond -dfont-ps-resdir=resdir -dgs-never-embed-fonts foo.ly
  >     $ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
  >          -I resdir -I resdir/Font \
  >          -sOutputFile=foo.embedded.pdf foo.pdf

  Note: It is better not to specify the directory that contains the name ‘`Resource`’ because it has a special meaning when specified with the `-I` option for Ghostscript.

  Note: Unlike `font-export-dir`, this method can embed CID fonts with Ghostscript 9.26 and later.

  Note: Same as `font-export-dir`, this option skips TrueType fonts because embedding TrueType fonts later causes garbled characters. To avoid garbling characters, use `gs-never-embed-fonts`, as this embeds TrueType fonts despite its name.

  Default: `#f` (meaning not to build).

`gs-load-fonts` bool

  If bool is `#t`, load fonts via Ghostscript. This option makes LilyPond’s output files contain only references to all fonts, which must be resolved to real fonts in a post-processing step by Ghostscript. Default: `#f`.

`gs-load-lily-fonts` bool

  If bool is `#t`, load LilyPond fonts via Ghostscript. This option makes LilyPond’s output files contain only references to its music fonts, which must be resolved to real fonts in a post-processing step by Ghostscript. All other fonts are still output as usual. Default: `#f`.

`gs-never-embed-fonts` bool

  If bool is `#t`, make Ghostscript embed only TrueType fonts and no other font format. Default: `#f`.

`gui` bool

  If bool is `#t`, make LilyPond run silently and redirect all output to a log file. Default: `#f`.

  Note to Windows users: By default, ‘`lilypond.exe`’ outputs all progress information to the command window, while ‘`lilypond-windows.exe`’ does not and returns a prompt, with no progress information, immediately at the command line. The ‘`-dgui`’ option can be used in this case to redirect output to a log file.

`help` bool

  If bool is `#t`, show this help. Default: `#f`.

`include-book-title-preview` bool

  If bool is `#t`, include book titles in preview images. Default: `#t`.

`include-eps-fonts` bool

  If bool is `#t`, include fonts in separate-system EPS files. Default: `#t`.

`include-settings` string

  Include file string for global settings, which is included before the score is processed. Default: `#f` (meaning no global settings file).

`job-count` num

  Process in parallel, using num jobs. Default: `#f` (meaning no parallel processing).

`log-file` string

  Redirect output to the log file ‘`string.log`’. Default: `#f` (meaning no log file).

`max-markup-depth` num

  Set maximum depth for the markup tree to value num. If a markup has more levels, assume it will not terminate on its own, print a warning, and return a null markup instead. Default: `1024`.

`midi-extension` string

  Set the default file extension for MIDI output files to ‘`.string`’. Default: `"midi"`.

`music-strings-to-paths` bool

  If bool is `#t`, convert text strings to paths when glyphs belong to a music font. Default: `#f`.

`paper-size` extra-quoted-string

  Set default paper size to extra-quoted-string. Note that the string must be enclosed in escaped double quotes. Default: `"\"a4\""`.

`pixmap-format` symbol

  Set Ghostscript’s output format for pixel images to symbol. Default: `png16m`.

`png-width` width
`png-height` height

  For PNG output, set the width and height (in pixels) of the created image file. If one of the options is missing, the other dimension is computed according to the EPS bounding box, retaining the aspect ratio.

  In addition to ‘`--png`’, either ‘`--eps`’, ‘`-dcrop`’, or ‘`-dpreview`’ should be used to get proper image scaling without clipping.

  Option ‘`-dresolution`’ is ignored.

  Note that there is a bug in ghostscript versions up to 9.52 for these two options: It produces empty PNG images if the height is larger than the width.

`point-and-click` bool

  If bool is `#t`, add ‘point & click’ links to PDF and SVG output. See Point and click. Default: `#t`.

`preview` bool

  If bool is `#t`, create preview images in addition to normal output. Default: `#f`.

  This option is supported by all backends (`pdf`, `png`, `ps`, `eps`, and `svg`) except `scm`. For input file name file and backend format, it generates an output file having the name ‘`file`.preview.`format`’, containing the titles and the first system of music. If `\book` or `\bookpart` blocks are used, the titles of `\book`, `\bookpart` or `\score` will appear in the output, including the first system of every `\score` block if the `\paper` variable `print-all-headers` is set to `#t`.

  To suppress the usual output, use the ‘`-dprint-pages`’ or ‘`-dno-print-pages`’ options according to your requirements.

`print-pages` bool

  If bool is `#t`, generate full pages. Default: `#t`.

  Option ‘`-dno-print-pages`’ is useful in combination with ‘`-dpreview`’ or ‘`-dcrop`’.

`profile-property-accesses` bool

  If bool is `#t`, keep statistics of `get_property()` function calls. Default: `#f`.

`protected-scheme-parsing` bool

  If bool is `#t`, continue when errors in inline Scheme code are caught in the parser. If set to `#f`, halt on errors and print a stack trace. Default: `#t`.

`read-file-list` string

  Use file ‘`string`’ that contains a list of input files to be processed. Default: `#f` (meaning no input list file).

`relative-includes` bool

  When processing an `\include` command, look for the included file relative to the current file if bool is `#t`. If set to `#f`, look for the file relative to the root file. Default: `#t`.

`resolution` num

  Set resolution for generating `PNG` pixmaps to num dpi. Default: `101`.

`safe` bool

  If bool is `#t`, do not trust the ‘`.ly`’ input. Default: `#f`.

  When LilyPond formatting is available through a web server, either the `-dsafe` or the ‘`--jail`’ option MUST be passed. The `-dsafe` option prevents inline Scheme code from wreaking havoc, e.g.,

  >     % too dangerous to write correctly
  >     #(s ystem "rm -rf /")
  >     % malicious but not destructive
  >     { c4^$(ly:gulp-file "/etc/passwd") }

  The ‘`-dsafe`’ option works by evaluating in-line Scheme expressions in a special safe module. This is derived from GUILE’s ‘`safe-r5rs`’ module, but also adds a number of functions of the LilyPond API which are listed in ‘`scm/safe-lily.scm`’.

  In addition, safe mode disallows `\include` directives and disables the use of backslashes in TeX strings. It is also not possible to import LilyPond variables into Scheme while in safe mode.

  Option ‘`-dsafe`’ does not detect resource overuse, so it is still possible to make the program hang indefinitely, for example by feeding cyclic data structures into the backend. Therefore, if using LilyPond on a publicly accessible webserver, the process should be limited in both CPU and memory usage.

  Safe mode will prevent many useful LilyPond snippets from being compiled.

  Option ‘`--jail`’ is an even more secure alternative, but requires more work to set up. See Basic command line options for LilyPond.

`separate-log-files` bool

  For input files ‘`file1.ly`’, ‘`file2.ly`’, …, output log data to files ‘`file1.log`’, ‘`file2.log`’, …, if bool is `#t`. Default: `#f`.

`show-available-fonts` bool

  If bool is `#t`, list available font names as delivered by the fontconfig library. Appended to this list LilyPond displays the configuration settings of fontconfig itself. Default: `#f`.

`strict-infinity-checking` bool

  If bool is `#t`, make `lilypond` abort on encountering `Inf` and `NaN` floating point exceptions. Default: `#f`.

`strip-output-dir` bool

  If bool is `#t`, don’t use the directory part from input file paths while constructing output file names. Default: `#t`.

`strokeadjust` bool

  If bool is `#t`, force PostScript stroke adjustment. This option is mostly relevant when a PDF is generated from PostScript output (stroke adjustment is usually enabled automatically for low-resolution bitmap devices). Without this option, PDF previewers tend to produce widely inconsistent stem widths at resolutions typical for screen display. However, the option does not noticeably affect print quality and causes large file size increases in PDF files. Default: `#f`.

`svg-woff` bool

  This option is required when using Web Open Font Format (WOFF) font files with the `svg` backend. If bool is `#t`, a single SVG file is created for every page of output. Apart from LilyPond’s own music glyphs, no other font information will be included. Any SVG viewer will therefore require the fonts be available to it for the proper rendering of both text and lyrics. It is also recommended not to use any font ‘aliases’ or ‘lists’ in case the SVG viewer cannot handle them. Default: `#f`.

`verbose`

  Verbosity level. This is a read-only option; setting it has no effect.

`warning-as-error` bool

  If bool is `#t`, change all warning and ‘programming error’ messages into errors. Default: `#f`.

### Environment variables

`lilypond` recognizes the following environment variables:

`LILYPOND_DATADIR`

  This specifies a directory where locale messages and data files are looked up by default, overriding locations defined either at compile-time or computed dynamically at run-time (see Relocation). The directory should contain subdirectories called ‘`ly`’, ‘`ps`’, ‘`tex`’, etc.

`LILYPOND_LOCALEDIR`

  Specify the directory where locale-specific files are located. This overrides the value derived from `LILYPOND_DATADIR`.

`LILYPOND_RELOCDIR`

  Specify the directory where relocation files are located. This overrides the value derived from the location of the `lilypond` binary.

`LANG`

  The language for LilyPond data sent to `stdout` and `stderr`, for example progress reports, warning messages, or debug output. Example: `LANG=de`.

`LILYPOND_LOGLEVEL`

  The default loglevel. If LilyPond is called without an explicit loglevel (i.e., no ‘`--loglevel`’ command line option), this value is used.

`LILYPOND_GC_YIELD`

  A variable, as a percentage, that tunes memory management behavior. A higher values means the program uses more memory, a smaller value means more CPU time is used. The default value is `70`.

`TMPDIR`

  This specifies the temporary directory in GNU/Linux and Mac. Default is ‘`/tmp`’. It is the directory where intermediate files (such as PostScript files) are saved during compilation. Overriding this variable might be useful, for example, if the user running lilypond does not have write access to the default temporary directory. Example: `TMPDIR=~/foo`.

### Relocation

Most programs in the Unix world use default directories for its data that are determined at configure time before compilation. LilyPond is no exception; for example, a typical installation puts the ‘`lilypond`’ binary into ‘`/usr/bin`’ and all files specific to LilyPond into subdirectories of ‘`/usr/share/lilypond/2.21.0/`’ (assuming that the current version is 2.21.0).

While this approach works fine for manual compilation and platforms that come with standardized package managers, it can cause issues where such managers are not common or not used by default. Typical examples of such platforms are Windows and MacOS, where users expect that application bundles can be installed anywhere.

The common solution to this problem is relocation support: Instead of using hard-coded paths to data files, locations of the necessary support files are computed at run time relative to the executed binary.

#### 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, taken from GUB (see Grand Unified Builder (GUB)).

>     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.

#### Relocation algorithm

LilyPond uses the following algorithm to find its data files.

1. Compute the directory where the currently executed `lilypond` binary is located. Let’s call this `bindir`. Set (internal) environment variable `INSTALLER_PREFIX` to ‘`bindir/..`’ (i.e., the parent directory of `bindir`).
2. Check environment variable `LILYPOND_DATADIR`. If it is set, use its value for LilyPond’s data directory, `datadir`. Otherwise use either ‘`$INSTALLER_PREFIX/share/lilypond/version`’ (with version being the current LilyPond version) or ‘`$INSTALLER_PREFIX/share/lilypond/current`’.
3. Check environment variable `LILYPOND_LOCALEDIR`. If it is set, use its value for LilyPond’s locale data directory, `localedir`. Otherwise use ‘`$INSTALLER_PREFIX/share/locale`’.
4. Check environment variable `LILYPOND_RELOCDIR`. If it is set, use its value for the directory of LilyPond’s relocation files, `relocdir`. Otherwise use ‘`$INSTALLER_PREFIX/etc/relocate`’.
5. If `datadir` doesn’t exist, use a compile-time value instead. Ditto for `localedir` (but not for `relocdir`, since it doesn’t make sense to have that).
6. If `relocdir` exists, process all files in this directory as described in Relocation files.

### LilyPond in chroot jail

Setting up the server to run LilyPond in a chroot jail is a complicated task. The steps are listed below. Examples in the steps are from Ubuntu GNU/Linux, and may require the use of `sudo` as appropriate.

- Install the necessary packages: LilyPond, Ghostscript, and ImageMagick.
- Create a new user by the name of `lily`:

  >     adduser lily

  This will create a new group for the `lily` user as well, and a home folder, `/home/lily`

- In the home folder of the `lily` user create a file to use as a separate filesystem:

  >     dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000

  This example creates a 200MB file for use as the jail filesystem.

- Create a loop device, make a file system and mount it, then create a folder that can be written by the `lily` user:

  >     mkdir /mnt/lilyloop
  >     losetup /dev/loop0 /home/lily/loopfile
  >     mkfs -t ext3 /dev/loop0 200000
  >     mount -t ext3 /dev/loop0 /mnt/lilyloop
  >     mkdir /mnt/lilyloop/lilyhome
  >     chown lily /mnt/lilyloop/lilyhome

- In the configuration of the servers, the JAIL will be `/mnt/lilyloop` and the DIR will be `/lilyhome`.
- Create a big directory tree in the jail by copying the necessary files, as shown in the sample script below.

  You can use `sed` to create the necessary copy commands for a given executable:

  >     for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
  >       do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
  >         cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
  >           \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done

### Example script for 32-bit Ubuntu 8.04

>     #!/bin/sh
>     ## defaults set here

>     username=lily
>     home=/home
>     loopdevice=/dev/loop0
>     jaildir=/mnt/lilyloop
>     # the prefix (without the leading slash!)
>     lilyprefix=usr/local
>     # the directory where lilypond is installed on the system
>     lilydir=/$lilyprefix/lilypond/

>     userhome=$home/$username
>     loopfile=$userhome/loopfile
>     adduser $username
>     dd if=/dev/zero of=$loopfile bs=1k count=200000
>     mkdir $jaildir
>     losetup $loopdevice $loopfile
>     mkfs -t ext3 $loopdevice 200000
>     mount -t ext3 $loopdevice $jaildir
>     mkdir $jaildir/lilyhome
>     chown $username $jaildir/lilyhome
>     cd $jaildir

>     mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
>     chmod a+w tmp

>     cp -r -L $lilydir $lilyprefix
>     cp -L /bin/sh /bin/rm bin
>     cp -L /usr/bin/convert /usr/bin/gs usr/bin
>     cp -L /usr/share/fonts/truetype usr/share/fonts

>     # Now the library copying magic
>     for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
>       "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
>         \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
>           's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
>             | sed '/.*=>.*/d'; done | sh -s

>     # The shared files for Ghostscript...
>           cp -L -r /usr/share/ghostscript usr/share
>     # The shared files for ImageMagick
>           cp -L -r /usr/lib/ImageMagick* usr/lib

>     ### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
>     ### you should be able to run:
>     ### Note that /$lilyprefix/bin/lilypond is a script, which sets the
>     ### LD_LIBRARY_PATH - this is crucial
>           /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

### Footnotes

[1] The status of GUILE is not reset after processing a ‘`.ly`’ file, so be careful not to change any system defaults from within Scheme.

#### LilyPond — Usage v2.22.2 (stable-branch).