1.2 Utilización desde la línea de órdenes

Esta sección contiene información adicional sobre el uso de LilyPond en la línea de órdenes. Esta forma puede ser preferible para pasarle al programa algunas opciones adicionales. Además, existen algunos programas complementarios ‘de apoyo’ (como midi2ly) que sólo están disponibles en la línea de órdenes.

Al hablar de la ‘línea de órdenes’, nos referimos a la consola del sistema operativo. Los usuarios de Windows posiblemente estén más familiarizados con los términos ‘ventana de MS-DOS’ o ‘línea de comandos’; Los usuarios de MacOS X puede que estén más familiarizados con los términos ‘terminal’ o ‘consola’. Éstos podrían requerir algunas configuraciones adicionales y deberían consultar también el apartado X MacOS X.

La descripción del uso de esta parte de los sistemas operativos se sale del ámbito de este manual; le rogamos que consulte otros documentos sobre este tema si no le resulta familiar la línea de órdenes.


Invocar lilypond

El ejecutable lilypond se puede llamar desde la línea de órdenes de la siguiente manera:

lilypond [opción]… archivo

Cuando se invoca con un nombre de archivo sin extensión, se prueba en primer lugar con la extensión ‘.ly’. Para leer la entrada desde stdin, utilice un guión (-) en sustitución de archivo.

Cuando se procesa ‘archivo.ly’, la salida resultante por defecto es el archivo ‘archivo.pdf’. Se pueden especificar varios archivos; cada uno de ellos se procesará de forma independiente1.

Si ‘archivo.ly’ contiene más de un bloque \score, el resto de las partituras se obtiene como salida en archivos numerados, empezando por ‘archivo-1.pdf’. además, el valor de output-suffix (sufijo de salida) se inserta entre el nombre base y el número. Por ejemplo, si ‘archivo.ly’ contiene

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

La salida consiste en los archivos ‘filename-violin.pdf’ y ‘filename-cello-1.pdf’.


Uso de LilyPond con las posibilidades básicas del shell

Dado que LilyPond es una aplicación de consola, las posibilidades del ‘shell’ usado para la llamada a LilyPond también pueden aprovecharse.

Por ejemplo,

lilypond *.ly

procesa todos los archivos de LilyPond dentro del directorio actual.

También puede ser útil redireccionar la salida de consola (p.ej. hacia un archivo):

lilypond file.ly 1> salida_estandar.txt

lilypond file.ly 2> error_estandar.txt

lilypond file.ly &> todo.txt

Estas instrucciones redireccionan la salida ‘normal’, solo los ‘errores’ o ‘todo’, respectivamente, hacia un archivo de texto. Consulte la documentación de su shell concreto, Command (Windows), las aplicaciones Terminal o Console (MacOS X) para comprobar si el redireccionamiento de la salida está contemplado o si la sintaxis es distinta.

El ejemplo siguiente busca y procesa todos los archivos de entradas que estén en el directorio actual y en todos los que están por debajo de él, recursivamente. Los archivos de salida se pondrán en el mismo directorio desde el que se ejecutó la instrucción, en lugar de aquellos en los que estaban los archivos de entrada originales.

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

También debe funcionar para los usarios de MacOS X.

Un usuario de Windows haría lo siguiente:

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

introduciendo estas instrucciones desde un indicador de órdenes que normalmente está en Inicio > Accessorios > Símbolo del sistema, o escribiendo en la ventana de búsqueda ‘indicador de órdenes’.

De forma alternativa, una ruta explícita al nivel superior de su carpeta que contenga todas las subcarpetas con archivos de entrada en su interior se puede especificar mediante la opción /p;

forfiles /s /p C:\Documentos\MisPartituras /M *.ly /c "cmd /c lilypond @file"

Si el nombre de la ruta del directorio de nivel superior contiene espacios, entonces es necesario incluir toda la ruta entre comillas:

forfiles /s /p "C:\Documentos\Mis Partituras" /M *.ly /c "cmd /c lilypond @file"

Opciones básicas de la línea de órdenes para LilyPond

Están contempladas las siguientes opciones:

-d, --define-default=variable[=valor]

Véase Opciones avanzadas de línea de órdenes para LilyPond.

-e, --evaluate=expresión

Evaluar la expresión de Scheme antes de analizar los archivos ‘.ly’. Se pueden pasar varias opciones ‘-e’, que se evalúan en secuencia.

La expresión se evalúa en el módulo guile-user, de manera que si quiere usar una definición como (define-public a 42) como expresión, debe utilizar

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

en la línea de órdenes, e incluir

#(use-modules (guile-user))

al principio del archivo ‘.ly’.

Nota: Los usuarios de Windows deben utilizar comillas dobles en lugar de apóstrofos simples.

-E, --eps

Generar archivos EPS.

Esta opción equivale a establecer las opciones de la línea de órdenes de LilyPond a --ps, -dbackend=eps y -daux-files='#f'.

-f, --format=formato

Formato del archivo o archivos (principal/es) de salida. Los valores posibles de formato son ps, pdf, png o svg.

Ejemplo: lilypond -fpng archivo.ly

El SVG usa internamente un backend específico, y por tanto no se puede obtener dentro de la misma ejecución que otros formatos; el uso de -fsvg o de --svg son en realidad equivalentes al empleo de la opción -dbackend=svg. Véase Opciones avanzadas de línea de órdenes para LilyPond.

-h, --help

Mostrar un resumen de las formas de utilización.

-H, --header=CAMPO

Volcar un campo de cabecera al archivo ‘NOMBREBASE.CAMPO

A modo de ejemplo, vamos a suponer que tenemos un archivo de entrada ‘archivo.ly’ que contiene

\header { title = "Título" }
\score { c1 }

La instrucción

lilypond -H title archivo.ly

crea entonces un archivo de texto sencillo ‘archivo.title’ que contiene la cadena Título.

-i, --init=archivo

Establecer el archivo de inicio a archivo (predeterminado: ‘init.ly’).

-I, --include=directorio

Añadir el directorio a la ruta de búsqueda de archivos de entrada.

Se pueden escribir varias opciones ‘-I’. La búsqueda se inicia en el directorio actual, y no se encuentra el archivo de inclusión, la búsqueda continúa dentro del directorio especificado en la primera opción ‘-I’, a continuación en el directorio dado en la segunda opción ‘-I’, y así sucesivamente.

Nota: El uso del carácter de tilde curva (~) con la opción ‘-I’ puede producir resultados inesperados en algunos ‘shells’.

Los usuarios de Windows deben incluir una barra inclinada al final de la ruta del directorio.

-j, --jail=usuario,grupo,jaula,directorio

[Esta opción solo está disponible si su sistema operativo contempla la funcionalidad chroot. Concretamente, Windows no la contempla.]

Ejecutar lilypond en una jaula de chroot.

La opción ‘--jail’ (jaula) proporciona una alternativa más flexible a la opción ‘-dsafe’ cuando el proceso de tipografía de LilyPond está disponible a través de un servidor web o cuando LilyPond ejecuta instrucciones enviadas por fuentes externas (véase Opciones avanzadas de línea de órdenes para LilyPond).

La opción ‘--jail’ funciona cambiando la raíz de lilypond a jaula justo antes de comenzar el proceso de compilación en sí. Entonces se cambian el usuario y el grupo a los que se han dado en la opción, y el directorio actual se cambia a directorio. Esta instalación garantiza que no es posible, al menos en teoría, escapar de la jaula. Observe que para que funcione ‘--jail’, se debe ejecutar lilypond como root, lo que normalmente se puede hacer de una forma segura utilizando sudo.

La instalación de una jaula puede ser un asunto relativamente complejo, pues debemos asegurarnos de que LilyPond puede encontrar dentro de la propia jaula todo lo que necesita para poder compilar la fuente. Una típica configuración de jaula de chroot consta de los siguientes elementos:

Preparar un sistema de archivos separado

Se debe crear un sistema de archivos separado para LilyPond, de forma que se pueda montar con opciones seguras como noexec, nodev y nosuid. De esta forma, es imposible ejecutar programas o escribir directamente a un dispositivo desde LilyPond. Si no quiere crear una partición separada, tan sólo tiene que crear un archivo de un tamaño razonable y usarlo para montar un dispositivo loop. El sistema de archivos separado garantiza también que LilyPond nunca pueda escribir en un espacio mayor del que se le permita.

Preparar un usuario separado

Se debe usar un usuario y grupo separados (digamos lily/lily) con bajos privilegios para ejecutar LilyPond dentro de la jaula. Debería existir un solo directorio con permisos de escritura para este usuario, y debe pasarse en el valor directorio.

Preparar la jaula

LilyPond necesita leer algunos archivos mientras se ejecuta. Todos estos archivos se deben copiar dentro de la jaula, bajo la misma ruta en que aparecen en el sistema de archivos real de root. Todo el contenido de la instalación de LilyPond (por ejemplo ‘/usr/share/lilypond’) se debe copiar.

Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar LilyPond usando strace, lo que permite determinar qué archivos faltan.

Ejecutar LilyPond

Dentro de una jaula montada con noexec es imposible ejecutar ningún programa externo. Por tanto, LilyPond se debe ejecutar con un backend que no necesite tal programa. Como ya hemos mencionado, se debe ejecutar con privilegios del superusuario (que por supuesto perderá inmediatamente), posiblemente usando sudo. También es una práctica recomendable limitar el número de segundos de tiempo de CPU que LilyPond puede usar (p.ej., usando ulimit -t), y, si su sistema operativo lo contempla, el tamaño de la memoria que se puede reservar. Véase también LilyPond en una jaula de chroot.

-l, --loglevel=NIVEL

Fijar el grado en que la salida de consola es prolija al nivel NIVEL. Los valores posibles son:

NONE

Ninguna salida en absoluto, ni siquiera mensajes de error.

ERROR

Solamente mensajes de error, no advertencias o indicaciones de progreso.

WARN

Advertencias y mensajes de error, no de progreso.

BASIC_PROGRESS

Mensajes de progreso básicos (éxito), advertencias y errores.

PROGRESS

Todos los mensajes de progreso, advertencias y errores.

INFO

Mensajes de progreso, advertencias, errores e información de ejecución adicional. Este es el valor predeteminado.

DEBUG

Todos los mensajes posibles, incuida la información de depuración prolija.

-o, --output=archivo
-o, --output=carpeta

Establecer el nombre del archivo de salida predeterminado a archivo o, si existe una carpeta con ese nombre, dirigir la salida hacia carpeta, tomando el nombre de archivo del documento de entrada. Se añade el sufijo correspondiente (por ejemplo, ‘.pdf’ para PDF) en los dos casos.

-O, --pspdfopt=clave

Establecer la optimización de salida de PS o PDF a clave. Los valores posibles son:

size

Generar un documento PS/EPS/PDF muy pequeño. Esta es la opción predeterminada.

La utilización de este valor equivale a fijar las opciones de la línea de órdenes del Scheme de LilyPond a -dmusic-font-encodings='#f' y -dgs-never-embed-fonts='#f'.

TeX

Producir archivos que están optimizados para su inclusión dentro de documentos de pdfTeX, luatex o XeTeX.

La utilización de este valor equivale a fijar las opciones de la línea de órdenes del Scheme de LilyPond a -dmusic-font-encodings='#t' y -dgs-never-embed-fonts='#f'.

TeX-GS

Si queremos incluir más de un PDF generado por LilyPond dentro de un documento de TeX, utilice esta opción y post-procese el PDF generado por TeX con Ghostscript.

La utilización de este valor equivale a fijar las opciones de la línea de órdenes del Scheme de LilyPond a -dmusic-font-encodings='#t' y -dgs-never-embed-fonts='#t'.

–ps

Generar PostScript.

--png

Generar imágenes de las páginas en formato PNG. Esta opción equivale a -fpng.

La resolución de la imagen se puede fijar a N PPP con

-dresolution=N
--pdf

Generar un PDF. Esta es la opción predeterminada, equivalente a -fpdf.

-s, --silent

No mostrar el avance, solo los mensajes de error. Equivale a -lERROR.

--svg

Generar archivos SVG para cada página. Esta opción equivale a -fsvg.

-v, --version

Mostrar la información de la versión.

-V, --verbose

Ser prolijo: mostrar las rutas completas de todos los archivos que se leen, y dar información cronométrica.

-w, --warranty

Mostrar la garantía con que viene GNU LilyPond (¡no viene con NINGUNA GARANTÍA!).


Opciones avanzadas de línea de órdenes para LilyPond

La opción ‘-d’ es la interfaz de la línea de órdenes a la función de Scheme de LilyPond ly:set-option. Esto significa que todas las opciones que se relacionan aquí pueden establecerse también dentro de los propios archivos ‘.ly’.

-d, --define-default=opción[=valor]
-d, --define-default=no-opción

Fijar el símbolo interno de Scheme equivalente opción a valor. Por ejemplo, la opción de línea de órdenes

-dbackend=svg

equivale a

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

dentro de un archivo de entrada de LilyPond.

Si no se proporciona el valor, usar #t como valor (lo que puede producir resultados extraños cuando el tipo esperado para el valor no es booleano). Se puede añadir el prefijo no- a la opción para ‘desactivar’ una opción, aportando #f como valor. Por ejemplo,

-dpoint-and-click='#f'

es lo mismo que

-dno-point-and-click

[Observe que el carácter ‘#’ introduce un comentario en muchos shells. Por este motivo se recomienda siempre entrecomillar las expresiones que lo contengan.]

La siguiente tabla relaciona todos los nombres de opción junto con sus valores. Dentro del código de Scheme, los valores de opción se pueden leer usando la función ly:get-option.

anti-alias-factor número

Generar el gráfico a mayor resolución (usando el factor número) y reducir la escala para evitar el pixelado en las imágenes PNG. Predeterminado: 1.0.

aux-files bool

Si bool es #t, crear archivos ‘.tex’, ‘.texi’ y ‘.count’ cuando se usa con la opción de backend eps. Predeterminado: #t.

backend símbolo

Usar símbolo como backend para la salida de LilyPond. Los valores posiboles son:

ps

Es el ajuste predeterminado. Los archivos de PostScript incluyen las fuentes TTF, Type1 y OTF. No se genera ningún ‘subconjunto’ de dichas fuentes tipográficas. Advierta que el uso de conjuntos de caracteres ‘orientales’ como el japonés puede dar lugar a archivos de tamaño muy grande.

Para la salida PDF se utiliza también el backend ps; los datos PS resultantes se post-procesan mediante el guión ps2pdf de Ghostscript, que también efectúa subconjuntos de fuentes de manera predeterminada.

eps

Usado como la opción predeterminada por la instrucción lilypond-book. Vuelca cada página al mismo tiempo como un solo archivo con todas las ṕaginas y fuentes tipográficas incluidas y como archivos Postscript separados para cada página pero sin las fuentes tipográficas incluidas.

null

No producir ninguna partitura impresa a la salida; tiene el mismo efecto que -dno-print-pages.

scm

Volcado de las instrucciones de dibujo internas basadas en Scheme, en bruto.

svg

Gráficos vectoriales escalables. Por cada página de la salida, se crea un solo archivo SVG. Los glifos musicales se codifican como gráficos vectoriales, pero las fuentes tipográficas del texto no se incrustan en los archivos SVG. Cualquier visor de SVG necesita que las fuentes de texto correspondientes estén disponibles para la correcta representación tanto del texto como de la letra. Se recomienda no utilizar ‘alias’ ni ‘listas’ de fuentes tipográficas por si el visor de SVG no es capaz de manejarlas. Al usar archivos de fuente abierta para la web Web Open Font Format (WOFF), es necesario indicar la opción -dsvg-woff

check-internal-types bool

Si bool es #t, comprobar que el tipo de cada asignación de propiedades es correcto. Predeterminado: #f.

clip-systems bool

Si bool es #t, extraer fragmentos de música de la partitura. Requiere que la función clip-regions esté definida dentro del bloque \layout. Véase Extracción de fragmentos de música. No se extrae ningún fragmento si se usa con la opción ‘-dno-print-pages’. Predetermiadno: #f.

crop bool

Si bool es #t, incorporar toda la música con sus títulos y encabezamientos, sin márgenes, en un archivo de salida de ‘una sola página’. Predeterminado: #f.

datadir

Prefijo de los archivos de datos. Esta opción es de solo lectura; su establecimiento no tiene ningún efecto.

debug-gc bool

Si bool es #t, volcar las estadísticas de depuración de memoria. Predeterminado: #f.

debug-gc-assert-parsed-dead bool

Para la depuración de memoria: si bool es #t, asegurarse de que todas las referencias a objetos analizados están muertas. Es una opción interna, y se activa automáticamente para -ddebug-gc. Predeterminado: #f.

debug-lexer bool

Si bool es #t, efectuar una depuración del analizador léxico flex. Predeterminado: #f.

debug-page-breaking-scoring bool

Si bool es #t, volcar las partituras para muchas configuraciones de saltos de página diferentes. Predeterminado: #f.

debug-parser bool

Si bool es #t, efectuar una depuración del analizador sintáctico bison. Predeterminado: #f.

debug-property-callbacks bool

Si bool es #t, efectuar una depuración de las cadenas cíclicas de funciones de callback. Predeterminado: #f.

debug-skylines bool

Si bool es #t, efectuar una depuración de las líneas de horizonte. Predeterminado: #f.

delete-intermediate-files bool

Si bool es #t, eliminar los archivos intermedios .ps inútiles que se crean durante la compilación. Predeterminado: #t.

dump-signatures bool

Si bool es #t, volcar las firmas de salida de cada sistema. Usado para las pruebas de regresión. Predeterminado: #f.

embed-source-code bool

Si bool es #t, empotrar los archivos de entrada en código de LilyPond dentro del documento PDF generado. Predeterminado: #f.

eps-box-padding número

Rellenar el borde izquierdo de la caja contenedora (bounding box) del EPS de salida en número milímetros. Predeterminado: #f (que significa que no se rellena la caja contenedora).

font-export-dir cadena

Fijar el directorio para la exportación de fuentes tipográficas como archivos de PostScript a cadena. Esto es de utilidad cuando queremos crear primero un PDF sin las fuentes incrustadas, e incrustar más tarde las fuentes con Ghostscript como se ve más abajo.

$ 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

Nota: a diferencia de font-ps-resdir, este método no puede empotrar las fuentes CID con Ghostscript 9.26 y posteriores.

Nota: de la misma manera que font-ps-resdir, esta opción se salta las fuentes TrueType porque el empotrado de fuentes TrueType produce un desbaratamiento de los caracteres. Para evitar este dessbaratabiento, use gs-never-embed-fonts, pues a pesar de su nombre esta opción empotra las fuentes TrueType.

Predeterminado: #f (que significa no exportar).

font-ps-resdir cadena

Fijar el directorio (como cadena) para construir un subconjunto del directorio de recursos PostScript y usarlo para empotrar las fuentes más tarde. Esto es útil si queremos crear primero un PDF sin las fuentes empotradas y empotrar las fuentes más tarde con Ghostscript como se ve más abajo.

$ 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

Nota: es mejor no especificar el directorio que contiene el nombre ‘Resource’ porque este tiene un significado especial al especificarlo con la opción -I para Ghostscript.

Nota: a diferencia de font-export-dir, este método puede empotrar fuentes CID con Ghostscript 9.26 y posteriores.

Nota: de igual manera que font-export-dir, esta opción se salta las fuentes TrueType porque el empotrado tardío de fuentes TrueType causa un desbaratamiento de los caracteres. Para evitar el desbaratamiento, use gs-never-embed-fonts, ya que este empotra las fuentes TrueType a pesar de su nombre.

Predeterminado: #f (que significa no construir).

gs-load-fonts bool

Si bool es #t, cargar fuentes a través de Ghostscript. Esta opción hace que los archivos de salida de LilyPond solo contenga referencias a todas las fuentes, lo que debe después resolverse a las fuentes reales en un paso de post-procesado por medio de Ghostscript. Predeterminado: #f.

gs-load-lily-fonts bool

Si bool es #t, cargar las fuentes de LilyPond por medio de Ghostscript. Esta opción hace que los archivos de salida de LilyPond contengan solamente referencias a sus fuentes de música, lo que debe después resolverse a las fuentes reales en un paso de post-procesado por medio de Ghostscript. Todas las demás fuentes se dirigen a la salida como es habitual. Predeterminado: #f.

gs-never-embed-fonts bool

Si bool es #t, hacer que Ghostscript incruste solamente tipos de letra TrueType y ningún otro formato de fuente. Predeterminado: #f.

gui bool

Si bool es #t, LilyPond se ejecuta silenciosamente y se redirige toda la salida a un archivo de registro. Predeterminado: #f.

Nota para los usuarios de Windows: De manera predeterminada, ‘lilypond.exe’ dirige toda la salida de la información de avance hacia la ventana de consola, mientras que ‘lilypond-windows.exe’ no lo hace y devuelve un indicador del sistema, sin ninguna indicación del avance, inmediatamente en la línea de órdenes. La opción ‘-dgui’ se puede usar en este caso para redirigir la salida a un archivo de registro.

help bool

Si bool es #t, mostrar esta ayuda. Predeterminado: #f.

include-book-title-preview bool

Si bool es #t, incluir los títulos de libro en las imágenes de vista previa. Predeterminado: #t.

include-eps-fonts bool

Si bool es #t, incluir las fuentes tipográficas en los archivos EPS de cada uno de los sistemas. Predeterminado: #t.

include-settings cadena

Incluir el archivo cadena de ajustes globales, que se incluye antes de que la partitura se procese Predeterminado: #f (que significa que no se incluye ningún archivo de ajustes globales).

job-count número

Procesar en paralelo, utilizando número tareas. Predeterminado: #f (que significa que no se hace ningún procesado paralelo).

log-file cadena

Redirigir la salida hacia el archivo de registro ‘cadena.log’. Predeterminado: #f (que significa ningún archivo de registro).

max-markup-depth número

Fijar la profundidad máxima del árbol de marcado al valor número. Si un elemento de marcado tiene más niveles, suponer que no va a finalizar por sí mismo, imprimir un mensaje de advertencia y devolver un elemento de marcado nulo en su lugar. Predeterminado: 1024.

midi-extension cadena

Fijar la extensión de archivo predeterminada para los archivos MIDI de salida a ‘.cadena’. Predeterminado: "midi".

music-strings-to-paths bool

Si bool es #t, converir las cadenas de texto a trayectos cuando los glifos pertenecen a una fuente musical. Predeterminado: #f.

paper-size extra-quoted-string

Establecer el tamaño predeterminado de papel a extra-quoted-string. Observe que la cadena se debe encerrar dentro de comillas con prefijo de escape. Predeterminado: "\"a4\"".

pixmap-format symbol

Establecer el formato de salida de Ghostscript para las imágenes de matriz de puntos a symbol. Predeterminado: png16m.

point-and-click bool

Si bool es #t, añadir enlaces de ‘apuntar y pulsar’ links a las salidas de PDF y SVG. Véase Apuntar y pulsar. Predeterminado: #t.

preview bool

Si bool es #t, crear imágenes de vista previa además de la salida normal. Predeterminado: #f.

Esta opción está contemplada por todos los ‘back-ends’ (pdf, png, ps, eps y svg), excepto scm. Para un nombre de archivo de entrada archivo y un backend formato, genera un archivo de salida, con el nombre ‘archivo.preview.formato’, que contiene los títulos y el primer sistema de la música. Si se están utilizando bloques \book o \bookpart, aparecen en la salida los títulos de \book, \bookpart o \score, incluido el primer sistema de cada bloque \score si la variable de \paper print-all-headers está fijada al valor #t.

Para suprimir la salida usual, utilice las opciones ‘-dprint-pages’ o ‘-dno-print-pages’ según sus necesidades.

print-pages bool

Si bool es #t, generar páginas completas. Predeterminado: #t.

La opción ‘-dno-print-pages’ es útil en combinación con las opciones ‘-dpreview’ o ‘-dcrop’.

profile-property-accesses bool

Si bool es #t, recabar estadísticas de las llamadas de función get_property(). Predeterminado: #f.

protected-scheme-parsing bool

Si bool es #t, continuar cuando se interceptan errores en el código empotrado de Scheme dentro del analizador sintáctico. Si se establece al valor #f, detenerse cuando se produzca algún error e imprimir una traza de la pila. Predeterminado: #t.

read-file-list cadena

Usar el archivo ‘cadena’ que contiene una lista de archivos de entrada que procesar. Predeterminado: #f (que significa ningún archivo de lista de entrada).

relative-includes bool

Cuando se procesa una instrucción \include, buscar el archivo de inclusión en una ruta relativa al archivo actual si bool es #t. Si se establece a #f, buscar el archivo según una ruta relativa al archivo raíz. Predeterminado: #t.

resolution número

Fijar la resolución para generar imágenes de matriz de puntos PNG a número ppp. Predeterminado: 101.

safe #f

No confiar en la entrada .ly.

Cuando el servicio de tipografía está disponible a través de un servidor web, SE DEBEN pasar las opciones -dsafe o ‘--jail’. La opción -dsafe evita que el código de Scheme empotrado pueda producir un desastre, p.ej.:

% demasiado peligroso para escribirlo correctamente
#(s ystem "rm -rf /")
% malicioso pero no destructivo
{ c4^$(ly:gulp-file "/etc/passwd") }

La opción ‘-dsafe’ funciona evaluando las expresiones de Scheme en línea dentro de un módulo seguro especial. Deriva del módulo ‘safe-r5rs’ de GUILE, pero además añade unas cuantas funciones de la API de LilyPond que están relacionadas en ‘scm/safe-lily.scm’.

Además, el modo seguro prohíbe las directivas \include y desactiva la utilización de barras invertidas en las cadenas de TeX. Asimismo, no es posible importar variables de LilyPond dentro de Scheme cuando se está en modo seguro.

La opción ‘-dsafeno detecta la sobreutilización de recursos, por lo que aún es posible hacer que el programa se cuelgue indefinidamente, por ejemplo suministrando estructuras de datos cíclicas en el backend. Por ello, si está usando LilyPond en un servidor web accesible públicamente, el proceso se debe limitar tanto en el uso de memoria como de CPU.

El modo seguro evita que se puedan compilar muchos fragmentos de código útiles.

La opción ‘--jail’ es una alternativa más segura aún, pero requiere más trabajo para su configuración. Véase Opciones básicas de la línea de órdenes para LilyPond.

separate-log-files bool

Para los archivos de entrada ‘archivo1.ly’, ‘archivo2.ly’, …, dar salida a datos de registro hacia los archivos ‘archivo1.log’, ‘archivo2.log’, …, si bool es #t. Predeterminado: #f.

show-available-fonts bool

Si bool es #t, imprimir un listado de los nombres de fuente tipográfica disponibles tal y como los proporciona la biblioteca fontconfig. Al final de esta lista, LilyPond presenta los ajustes de configuración del propio fontconfig. Predeterminado: #f.

strict-infinity-checking bool

Si bool es #t, hacer que la instrucción lilypond aborte al encontrar las excepciones de coma flotante Inf y NaN. Predeterminado: #f.

strip-output-dir bool

Si bool es #t, no utilizar la parte del directorio tomada de las rutas de los archivos cuando se construyen nombres de archivos de salida. Predeterminado: #t.

strokeadjust bool

Si bool es #t, forzar el ajuste de los trazos de PostScript. Esta opción es relevante principalmente cuando se genera un PDF a partir de la salida de PostScript (el ajuste del trazo está por lo general activado automáticamente para dispositivos de mapa de puntos de baja resolución). Sin esta opción, los visores de PDF tienden a producir anchuras de plica muy poco consistentes con las resoluciones típicas de las pantallas de ordenador. Sin embargo, la opción no afecta de forma muy significativa a la calidad de la impresión y causa grandes incrementos en el tamaño del archivo PDF. Predeterminado: #f.

svg-woff bool

Esta opción es necesaria al usar archivos de fuente abierta para la Web, Web Open Font Format (WOFF) con el backend svg. Si bool es #t, se crea un solo archivo SVG para cada página de salida. Aparte de los glifos musicales propios de LilyPond, no se incluye ninguna otra información de fuente tipográfica. Todo visor de SVG necesita, por ello, tener las fuentes disponibles para la representación correcta tanto del texto como de la letra. Asimismo se recomienda no usar alias de fuentes ni listas, por si el visor de SVG no es capaz de manejarlos. Predeterminado: #f.

verbose

Nivel de verbosidad. Esta es una opción de solo lectura; su establecimiento no tiene ningún efecto.

warning-as-error bool

Si bool es #t, cambiar todos los mensajes de advertencia y de ‘error de programación’ a errores. Predeterminado: #f.


Variables de entorno

lilypond reconoce las siguientes variables de entorno:

LILYPOND_DATADIR

Especifica un directorio en el que los mensajes de localización y de datos se buscan de forma predeterminada, sobreescribiendo las ubicaciones definidas en tiempo de compilación o computadas dinámicamente en tiempo de ejecución (véase Reubicación del programa). El directorio debe contener subdirectorios llamados ‘ly’, ‘ps’, ‘tex’, etc.

LILYPOND_LOCALEDIR

Espcificar el directorio en que están los archivos específicos de localización. Sobreescribe el valor derivado de LILYPOND_DATADIR.

LILYPOND_RELOCDIR

Especificar el directorio en que se ubican los archivos de relocalización. Sobreescribe el valor que se deriva de la ubicación del binario lilypond.

LANG

Idioma de los datos de LilyPond enviados a stdout y a stderr, por ejemplo informes del avance, mensajes de advertencia o salida de depuración. Ejemplo: LANG=es.

LILYPOND_LOGLEVEL

Nivel de registro predeterminado. Si LilyPond se llama sin ningún nivel de registro explícito (es decir, sin opción de línea de órdenes ‘--loglevel’), se usa este valor.

LILYPOND_GC_YIELD

Una variable, como porcentaje, que ajusta el comportamiento de la administración de memoria. Con valores más altos, el programa usa más memoria; con valores más bajos, usa más tiempo de CPU. El valor predeterminado es 70.

TMPDIR

Esto especifica el directorio temporal en GNU/Linux y Mac. EL predeterminado es ‘/tmp’. Es el directorio en que se guardan los archivos intermedios (tales como archivos de PostScript) durante la compilación. La sobreescritura de esta variable podría ser útil, por ejemplo, si el usuario que ejecuta lilypond no tiene privilegios de escritura sobre el directorio temporal predeteminado. Ejemplo: TMPDIR=~/foo.


Reubicación del programa

Casi todos los programas dentro del mundo Unix utilizan directorios predeterminados para sus datos, que vienen determinados en el momento de la configuración y antes de la compilación. LilyPond no es una excepción; por ejemplo, una instalación típica coloca el binario ‘lilypond’ en ‘/usr/bin’ y todos los archivos específicos de LilyPond dentro de subdirectorios de ‘/usr/share/lilypond/2.21.0/’ (suponiendo que la versión actual es 2.21.0).

Aunque este enfoque funciona perfectamente para la compilación manual y para plataformas que vienen con gestores de paquetes estandarizados, puede producir algunos problemas allí donde los mencionados gestores no son tan comunes o no se utilizan por defecto. Son ejemplos típicos de este tipo de plataformas Windows y MacOS, donde los usuarios dan por sentado que todo lo que viene con la aplicación se puede ubicar en cualquier lugar.

La solución habitual a este problema es que el programa contemple la reubicación: en lugar de usar rutas fijas a los archivos de datos, las ubicaciones a los necesarios archivos de apoyo se calculan en tiempo de ejecución relativos al binario que se ejecuta.


Archivos de reubicación

En realidad existe un segundo mecanismo para la configuración en tiempo de ejecución: LilyPond se apoya fuertemente en bibliotecas y programas externos, especialmente las bibliotecas ‘FontConfig’ y ‘GUILE’ para encontrar las fuentes tipográficas del sistema y manejar los archivos de Scheme, respectivamente, y el programa gs (Ghostscript) para convertir datos de PS a archivos PDF. Todos ellos se deben configurar también para tener localizados sus respectivos archivos de datos. Para ello, el programa lilypond analiza todos los archivos que están dentro de un directorio llamado ‘relocate’ (si existe; véase más abajo dónde se busca este directorio) para manipular las variables de entorno, las que a su vez controlan estas bibliotecas y programas externos. El formato de estos archivos de reubicación es sencillo; cada línea tiene la sintaxis siguiente:

instrucción clave=valor

y las líneas vacías se ignoran.

La directiva instrucción es una de las siguientes.

set

Fijar incondicionalmente la variable clave a valor. Esto sobreescribe cualquier valor establecido previamente.

set?

Fijar la variable de entorno clave a valor solamente si clave no está definida aún. Dicho de otra forma, no sobreescribe ningún valor fijado previamente.

setdir

Si valor es un directorio, fijar incondicionalmente la variable de entorno clave a valor. En caso contrario, emitir un mensaje de advertencia.

setfile

Si valor es un archivo, fijar incondicionalmente la variable de entorno clave a valor. En caso contrario, emitir un mensaje de advertencia.

prependdir

Anadir el nombre del directorio valor al principio de la lista de directorios de la variable de entorno clave. Si clave no existe, se crea.

Se permite usar variables de entorno (prefijadas por el símbolo del dólar) dentro de valor y se expanden antes de que la directiva se ejecute.

He aquí dos ejemplos de entradas del archivo de reubicación, tomadas del (véase Grand Unified Builder (GUB)).

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

Se debe evitar que más de una línea establezca el valor de la misma variable de entorno dentro de los archivos de reubicación, ya que el orden de la exploración de los archivos en el directorio ‘relocate’ es arbitrario.


Algoritmo de la reubicación

LilyPond usa el siguiente algoritmo para buscar los archivos de datos.

  1. Calcular el directorio en que se encuentra el archivo binario lilypond que se está ejecutando actualmente. Le llamaremos bindir. Fijar la variable de entorno (itnerna) INSTALLER_PREFIX a ‘bindir/..’ (esto es, el directorio padre de bindir).
  2. Comprobar la variable de entorno LILYPOND_DATADIR. Si está establecida, usar su valor como el directorio de datos de LilyPond, datadir. En caso contrario, usar o bien ‘$INSTALLER_PREFIX/share/lilypond/versión’ (siendo versión la versión actual de LilyPond) o bien ‘$INSTALLER_PREFIX/share/lilypond/current’.
  3. Comprobar la variable de entorno LILYPOND_LOCALEDIR. Si está establecida, usar su valor como la carpeta de datos de localización internacional de LilyPond, localedir. En caso contrario, usar ‘$INSTALLER_PREFIX/share/locale’.
  4. Comprobar la variable de entorno LILYPOND_RELOCDIR. Si está establecida, usar su valor como el directorio de los archivos de reubicación de LilyPond, relocdir. En caso contrario, usar ‘$INSTALLER_PREFIX/etc/relocate’.
  5. Si datadir no existe, usar en su lugar un valor calculado en tiempo de compliación. Lo mismo para localedir (pero no para relocdir, puesto que no tiene razón de ser).
  6. Si relocdir existe, procesar todos los archivos de este directorio como se describe en Archivos de reubicación.

LilyPond en una jaula de chroot

La preparación del servidor para que ejecute LilyPond en una jaula de chroot es una tarea muy complicada. Los pasos están relacionados más abajo. Los ejemplos que aparecen en cada uno de los pasos son válidos para Ubuntu GNU/Linux, y pueden requerir el uso de sudo según corresponda.

Guión de ejemplo para Ubuntu 8.04 de 32 bits

#!/bin/sh
## aquí se fijan los valores predeterminados

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# prefijo (¡sin la barra inicial!)
lilyprefix=usr/local
# el directorio en que lilypond se encuentra instalado en el sistema
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

# Ahora la magia de copiar las bibliotecas
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

# Los archivos compartidos para Ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# Los archivos compartidos para ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Ahora, suponiendo que tenemos test.ly en /mnt/lilyloop/lilyhome,
### deberíamos poder ejecutar:
### Observe que /$lilyprefix/bin/lilypond es un guión, que establece
### un valor para LD_LIBRARY_PATH : esto es crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

Notas el pie

[1] El estado de GUILE no se restablece después de procesar un archivo ‘.ly’, por lo que debe tener cuidado de no modificar ningún valor predeterminado desde dentro de Scheme.


LilyPond — Utilización v2.21.82 (rama de desarrollo).