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 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 son los archivos ‘`archivo.ps`’ y ‘`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 obtendrán como salida en archivos numerados, empezando por ‘`archivo-1.pdf`’. además, el valor de `output-suffix` (sufijo de salida) se insertará entre el nombre base y el número. Un archivo de entrada que contenga

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

producirá como salida base‘`-violin.pdf`’ y base‘`-cello-1.pdf`’.

#### Instrucciones estándar de la línea de órdenes

Si su terminal (o ventana de órdenes) contempla las redirecciones normales, quizá le sean de utilidad las siguientes instrucciones para redirigir la salida de la consola a un archivo:

- `lilypond archivo.ly 1>salidaestandar.log` para redirigir la salida normal
- `lilypond archivo.ly 2>salidadeerror.log` para redirigir los mensajes de error
- `lilypond archivo.ly &>todo.log` para redirigir toda la salida

Consulte la documentación de su shell para ver si contempla estas opciones, o si la sintaxis es distinta. Observe que son instrucciones del shell y que no tienen nada que ver con lilypond.

### Opciones de la línea de órdenes para `lilypond`

Están contempladas las siguientes opciones:

`-e,--evaluate=expresión`

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

  La expresión se evaluará en el módulo `guile-user`, de manera que si quiere usar definiciones dentro de 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`’.

`-f,--format=formato`

  Formato de la salida. Como `formato` se puede elegir entre `ps`, `pdf` y `png`.

  Ejemplo: `lilypond -fpng archivo.ly`

`-d,--define-default=variable=valor`

  Establece la opción interna del programa variable al valor de Scheme valor. Si no se proporciona ningún valor, se usa #t. Para desactivar una opción se puede anteponer `no-` a la variable, p.ej.:

  >     -dno-point-and-click

  es lo mismo que

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

  A continuación veremos algunas opciones interesantes.

  ‘`help`’

    La ejecución de `lilypond -dhelp` imprimirá todas las opciones `-d` que están disponibles.

  ‘`paper-size`’

    Esta opción establece el tamaño predeterminado del papel,

    >     -dpaper-size=\"letter\"

    Observe que la cadena se debe incluir dentro de comillas escapadas ( `\"` ).

  ‘`safe`’

    No confiar en la entrada ‘`.ly`’.

    Cuando el proceso de tipografía de LilyPond se encuentra disponible a través de un servidor web, SE DEBEN pasar las opciones `--safe` (seguro) o `--jail` (jaula). La opción `--safe` evita que el código de Scheme en línea arme un desastre, por ejemplo

    >     #(system "rm -rf /")
    >     {
    >       c4^#(ly:export (ly:gulp-file "/etc/passwd"))
    >     }

    La opción `-dsafe` funciona evaluando las expresiones en línea de Scheme dentro de un módulo especial seguro. Este módulo seguro deriva del módulo GUILE ‘`safe-r5rs`’, pero añade ciertas funciones del API de LilyPond. Estas funciones se relacionan en ‘`scm/safe-lily.scm`’.

    Además, el modo seguro prohíbe las directivas `\include` e inhabilita el uso de barras invertidas en las cadenas de TeX.

    En el modo seguro, no es posible la importación de variables de LilyPond dentro de Scheme.

    `-dsafe` no detecta la sobreutilización de recursos. Aún es posible hacer que el programa se cuelgue indefinidamente, por ejemplo alimentando el backend con estructuras de datos cíclicas. Por tanto, si se está utilizando LilyPond sobre un servidor web accesible públicamente, el proceso debe limitarse tanto en el uso de CPU como de memoria.

    El modo seguro impide que muchos fragmentos útiles de código de LilyPond se puedan compilar. La opción `--jail` es una alternativa más segura, pero su preparación requiere más trabajo.

  ‘`backend`’

    el formato de salida que usar para el back-end o extremo final. Para el `formato` se puede elegir entre

    `ps`

      para PostScript.

      Los archivos PostScript incluyen las tipografías TTF, Type1 y OTF. No se seleccionan subconjuntos de estas tipografías. Cuando se usan conjuntos de caracteres orientales, esto puede dar lugar a archivos enormes.

    `eps`

      para obtener PostScript encapsulado. Esto vuelca cada una de las páginas/sistemas como un archivo ‘`EPS`’ distinto, sin tipografías, y como un solo archivo ‘`EPS`’ encuadernado con todas las páginas/sistemas con las tipografías incluidas.

      Este modo se usa de forma predeterminada por parte de `lilypond-book`.

    `svg`

      para obtener SVG (gráficos vectoriales escalables).

      Crea un único archivo SVG que contiene toda la salida de música, con las tipografías incrustadas. Se necesita un visor de SVG que contemple las tipografías incrustadas, o un visor de SVG que pueda sustituir las tipografías incrustadas por tipografías OTF. Bajo UNIX, puede usar Inkscape (versión 0.42 o posterior), después de copiar las tipografías OTF del directorio de LilyPond (que normalmente es ‘`/usr/share/lilypond/VERSIÓN/fonts/otf/`’) al directorio ‘`~/.fonts/`’.

    `scm`

      para obtener un volcado de las instrucciones internas de dibujo basadas en Scheme, en bruto.

    `null`

      no producir una salida impresa; tiene el mismo efecto que `-dno-print-pages`.

    Ejemplo: `lilypond -dbackend=svg archivo.ly`

  ‘`preview`’

    Generar un archivo de salida que contenga solamente los títulos de cabecera y el primer sistema de música. Si se usan bloques `\bookpart`, los títulos y el primer sistema de todos los bloques `\bookpart` aparecerán en la salida. Los motores `ps`, `eps` y `svg` contemplan esta opción.

  ‘`print-pages`’

    Generar las páginas completas, el ajuste predeterminado. `-dno-print-pages` es útil en combinación con `-dpreview`.

`-h,--help`

  Mostrar un resumen de las formas de utilización.

`-H,--header=CAMPO`

  Volcar un campo de cabecera al archivo ‘`NOMBREBASE.CAMPO`’

`--include, -I=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 primer directorio definido, y si el archivo que se debe incluir no se encuentra, la búsqueda continúa en los directorios siguientes.

`-i,--init=archivo`

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

`-o,--output=ARCHIVO o 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.

`--ps`

  Generar PostScript.

`--png`

  Generar imágenes de las páginas en formato PNG. Esto implica `--ps`. La resolución en PPP de la imagen se puede establecer con

  >     -dresolution=110

`--pdf`

  Generar PDF. Implica `--ps`.

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

  Ejecutar `lilypond` en una jaula de chroot.

  La opción `--jail` (jaula) proporciona una alternativa más flexible a la opción `--safe` cuando el proceso de tipografía de LilyPond está disponible a través de un servidor web o cuando LilyPond ejecuta archivos fuente procedentes del exterior.

  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 es un asunto algo delicado, pues debemos asegurarnos de que LilyPond puede encontrar dentro de la jaula todo lo que necesita para poder compilar la fuente. Una configuración típica 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 le permitirá 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 mencionamos, también se debe ejecutar con privilegios del superusuario (que por supuesto perderá inmediatamente), posiblemente usando `sudo`. Es buena idea 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,--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!).

### 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 buscarán de forma predeterminada. El directorio debe contener subdirectorios llamados ‘`ly/`’, ‘`ps/`’, ‘`tex/`’, etc.

`LANG`

  Selecciona el idioma de los mensajes de advertencia.

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

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

Otros idiomas: English, deutsch, français, magyar, italiano, 日本語.

#### LilyPond — Utilización