[ << Programming work ]	[Top][Contents]	[ Release work >> ]
[ < Localization ]	[ Up: Programming work ]	[ Debugging LilyPond > ]

---

10.6 Warnings, Errors, Progress and Debug Output

Available log levels

LilyPond has several log levels to specify how verbose the output on the console should be, as shown in the following table. Note that only the first few characters of a given value are checked (as indicated); additionally, case doesn’t matter. In other words, ERR is the same as error or ERRO, for example.

NONE

no output at all, even on failure

ERR[OR]

only error messages

WARN

only error messages and warnings

BASIC

warnings, errors, and basic progress (success, etc.)

PROG[RESS]

warnings, errors, and full progress messages

INFO

warnings, errors, progress, and more detailed information (default)

DEBUG

all messages, including full debug messages (very verbose!)

The log level can either be set with the environment variable LILYPOND_LOGLEVEL or on the command line with the --loglevel=... option.

Functions for debug and log output

LilyPond has two different types of error and log functions:

• If a warning or error is caused by an identified position in the input file, e.g., by a grob or by a music expression, the functions of the Input class provide logging functionality that prints the position of the message in addition to the message.
• If a message can not be associated with a particular position in an input file, e.g., the output file cannot be written, the functions in file flower/include/warn.hh provide logging functionality that only prints out the message, but no location.

There are also Scheme functions to access all of these logging functions from scheme. In addition, the Grob class contains some convenience wrappers for even easier access to these functions.

The message and debug functions in file warn.hh also have an optional argument newline to specify whether the message should always start on a new line or continue a previous message. They also do not have a particular input position associated, so there are no progress functions in the Input class. By default, function progress_indication() does not start on a new line but rather continues the previous output. All other functions by default start their output on a new line.

LilyPond’s error functions come in three different flavors: fatal error messages, programming error messages, and normal error messages.

• Errors written by the error() function cause the lilypond binary to exit immediately, returning a non-zero value.
• Errors by Input::error() let lilypond continue the compilation but return a non-zero value (i.e., indicating an unsuccessful program execution).
• All other errors are printed on the console without making lilypond exit or indicate an unsuccessful return code; they only differ to warning messages by the displayed text and that they are shown with log level ERROR.

If the Scheme option warning-as-error is set, any warning is treated as if Input::error() was called.

All logging functions at a glance

	C++, no location	C++, from input location
ERROR	error (), programming_error (msg), non_fatal_error (msg)	Input::error (msg), Input::programming_error (msg)
WARN	warning (msg)	Input::warning (msg)
BASIC	basic_progress (msg)	—
PROGRESS	progress_indication (msg)	—
INFO	message (msg)	Input::message (msg)
DEBUG	debug_output (msg)	Input::debug_output (msg)
	C++, from a Grob	Scheme, music expression
ERROR	Grob::programming_error (msg)	—
WARN	Grob::warning (msg)	(ly:music-warning music msg)
BASIC	—	—
PROGRESS	—	—
INFO	—	(ly:music-message music msg)
DEBUG	—	—
	Scheme, no location	Scheme, input location
ERROR	—	(ly:error msg args), (ly:programming-error msg args)
WARN	(ly:warning msg args)	(ly:input-warning input msg args)
BASIC	(ly:basic-progress msg args)	—
PROGRESS	(ly:progress msg args)	—
INFO	(ly:message msg args)	(ly:input-message input msg args)
DEBUG	(ly:debug msg args)	—