LilyPond: manual de utilización del programa: 1.2 Utilización desde la línea de órdenes

## 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` y `-dlilypond-book-output`.

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

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

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

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

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

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

`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 ‘`-dsafe`’ no 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`.

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

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

- Instale los paquetes necesarios: LilyPond, Ghostscript e ImageMagick.
- Cree un usuario nuevo con el nombre de `lily`:

  >     adduser lily

  Esto también creará un nuevo grupo para el usuario `lily`, y una carpeta personal, `/home/lily`

- En la carpeta personal del usuario `lily`, cree un archivo para usarlo como un sistema de archivos separado:

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

  Este ejemplo crea un archivo de 200MB para su uso como el sistema de archivos de la jaula.

- Cree un dispositivo loop, haga un sistema de archivos y móntelo, después cree una carpeta que sea escribible por el usuario `lily`:

  >     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

- En la configuración de los servidores, JAIL será `/mnt/lilyloop` y DIR será `/lilyhome`.
- Cree un gran árbol de directorios dentro de la jaula copiando los archivos necesarios, como se muestra en el guión de ejemplo que aparece más abajo.

  Puede usar `sed` para crear los archivos de copia necesarios para un ejecutable dado:

  >     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

### 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.24.4 (rama estable).