1.2 Utilització des de la línia d’ordres

Aquesta secció conté informació addicional sobre l’ús del LilyPond a la línia d’ordres. Aquesta forma pot ser preferible per passar-li al programa algunes opcions addicionals. A més a més, existeixen alguns programes complementaris ‘de suport’ (com ara midi2ly) que sols estan disponibles a la línia d’ordres.

En parlar de la ‘línia d’ordres’, ens referim a la consola del sistema operatiu. Els usuaris del Windows possiblement estiguin més familiaritzats amb els termes ‘finestra del MS-DOS’ o ‘línia de comandes’; Els usuaris del MacOS X potser que estiguin més familiaritzats amb els termes ‘terminal’ o ‘consola’. Aquests podrien requerir algunes configuracions addicionals i haurien de consultar també l’apartat MacOS X.

La descripció de l’ús d’aquesta part dels sistemes operatius excedeix l’àmbit d’aquest manual; us preguem que consulteu altres documents sobre aquest tema si no us resulta familiar la línia d’ordres.


Invocació del lilypond

L’executable lilypond es pot cridar des d’una línia d’ordres de la manera següent:

lilypond [opció]… fitxer

Quan s’invoca amb un nom de fitxer sense extensió, es prova en primer lloc amb la extensió ‘.ly’. Per llegir l’entrada des de stdin, utilitzeu un guió (-) en substitució de fitxer.

Quan es processa ‘archivo.ly’, la sortida resultant són els fitxers ‘fitxer.ps’ i ‘fitxer.pdf’. Es poden especificar diversos fitxers; cadascú d’ells es processarà de forma independent1.

Si ‘fitxer.ly’ conté més d’un bloc \score, la resta de les partitures s’obtindran com a sortida en fitxers numerats, començant per ‘fitxer-1.pdf’. A més, el valor de output-suffix (sufix de sortida) s’inserirà entre el nom base i el número. Un fitxer de sortida que contingui

#(define output-suffix "violí")
\score { … }
#(define output-suffix "violoncel")
\score { … }

produirà com a sortida base-violí.pdf’ i base-violoncel-1.pdf’.


Instruccions estàndard de la línia d’ordres

Si la vostra terminal (o finestra d’ordres) contempla les redireccions normals, potser us siguin d’utilitat les següents instruccions per redirigir la sortida de la consola d’un fitxer:

Consulteu la documentació del vostre intèrpret d’ordres per veure si contempla aquestes opcions, o si la sintaxi és diferent. Observeu que són instruccions de l’intèrpret d’ordres i que no tenen res a veure amb el LilyPond.


Opcions bàsiques de la línia d’ordres per al LilyPond

Estan contemplades les opcions següents:

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

Vegeu Opcions avançades de la línia d’ordres per al LilyPond.

-e, --evaluate=expressió

Avalua l’expressió del Scheme abans d’analitzar els fitxers ‘.ly’. Es poden passar diverses opcions ‘-e’, que s’avaluaran en seqüència.

L’expressió s’avaluarà al mòdul guile-user, de manera que si voleu usar definicions dins d’expressió, heu d’utilitzar

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

a la línia d’ordres, i incloure

#(use-modules (guile-user))

al principi del fitxer ‘.ly’.

Nota: Els usuaris de Windows han d’utilitzar cometes dobles en comptes de cometes simples.

-f, --format=format

quins formats s’han d’escriure. Les opcions per a format són ps, pdf, i png.

Exemple: lilypond -fpng fitxer.ly

-h, --help

Mostra un resum de les formes de utilització.

-H, --header=CAMP

Bolca un camp de capçalera al fitxer ‘NOMBASE.CAMP

-i, --init=archivo

Establir el fitxer d’inici a fitxer (predeterminat: ‘init.ly’).

-I, --include=directori

Afegir el directori a la ruta de cerca de fitxers d’entrada.

Es poden escriure diverses opcions -I. La cerca s’inicia al primer directori definit, i si el fitxer que s’ha d’incloure no es troba, la cerca continua als directoris següents.

-j, --jail=usuari,grup,gàbia,directori

Executar lilypond a una gàbia de chroot.

L’opció ‘--jail’ (gàbia) proporciona una alternativa més flexible a l’opció ‘-dsafe’ quan el procés de tipografia del LilyPond està disponible a un servidor web o quan el LilyPond executa instruccions enviades per fonts externes (vegeu Opcions avançades de la línia d’ordres per al LilyPond).

L’opció ‘--jail’ funciona canviant l’arrel de lilypond a gàbia just o abans de començar el procés de compilació en sí. Si es fa això es canvien l’usuari i el grup als que s’han donat a l’opció, i el directori actual es canvia a directori. Aquesta instal·lació garanteix que no és possible, al menys en teoria, escapar a la gàbia. Observeu que perquè funcioni ‘--jail’, s’ha d’executar lilypond com root, cosa que normalment es pot fer d’una forma segura utilitzant sudo.

La instal·lació d’una gàbia pot ser un assumpte relativament complex, atès que hem d’assegurar-nos que el LilyPond pot trobar dins de la pròpia gàbia tot el que necessita per poder compilar la font. Una típica configuració de gàbia de chroot consta dels següents elements:

Preparació d’un sistema de fitxers separat

S’ha de crear un sistema de fitxers separat per al LilyPond, de forma que es pugui muntar amb opcions segures com noexec, nodev i nosuid. D’aquesta forma, és impossible executar programes o escriure directament a un dispositiu des del LilyPond. Si no voleu crear una partició separada, tan sols té que crear un fitxer d’una mida raonable i usar-lo per muntar un dispositiu loop. El sistema de fitxers separat garanteix també que el LilyPond mai no pugui escriure en un espai major del què se li permeti.

Preparar un usuari separat

Es pot usar un usuari i grup separats (diguem-ne lily/lily) amb pocs privilegis per executar el LilyPond dins d’una gàbia. Hauria d’existir un sols directori amb permisos d’escriptura per a aquest usuari, i s’ha de passar el valor directori.

Preparació de la gàbia

El LilyPond necessita llegir alguns fitxers mentre s’executa, Tots aquests fitxers s’han de copiar dins de la gàbia, sota la mateixa ruta en la qual apareixen al sistema de fitxers real de root. Tot el contingut de la instal·lació del LilyPond (per exemple ‘/usr/share/lilypond’) s’ha de copiar.

Si sorgeixen problemes, la forma més senzilla de rastrejar-los és executar el LilyPond usant strace, cosa que li permetrà determinar quins fitxers falten.

Execució del LilyPond

Dins d’una gàbia muntada amb noexec és impossible executar cap programa extern. Per tant, el LilyPond s’ha d’executar amb un backend que no necessiti un programa extern. Com ja hem mencionat, s’ha d’executar amb privilegis del superusuari (que per suposat perdrà immediatament), possiblement usant sudo. També de CPU que el LilyPond pot usar (per exemple usant ulimit -t), i, si el vostre sistema operatiu ho contempla, la mida de la memòria que es pot reservar. Vegeu també El LilyPond a una gàbia de chroot.

-l, --loglevel=NIVELL

Fixa el grau en el qual la sortida de consola és neta al nivell NIVELL. Els valors possibles són:

NONE

Cap sortida en absolut, ni tan sols missatges d’error.

ERROR

Sols missatges d’error, cap advertiment o indicacions de progrés.

WARN

Advertiments i missatges d’error, no de progrés.

BASIC_PROGRESS

Missatges de progrés bàsics (èxit), advertiment i errors.

PROGRESS

Tots els missatges de progrés, advertiments i errors.

INFO (predeterminat)

Missatges de progrés, advertiments, errors i informació d’execució addicional.

DEBUG

Tots els missatges possibles, fins i tot la informació detallada de depuració.

-o, --output=FITXER o CARPETA

Estableix el nom del fitxer de sortida predeterminat a FITXER o, si hi ha una carpeta amb aquest nom, dirigeix la sortida cap a CARPETA, agafant el nom de fitxer del document d’entrada. S’afegeix el sufix corresponent (per exemple, .pdf per a PDF) als dos casos.

--ps

Generar PostScript.

--png

Genera imatges de les pàgines en format PNG. Això implica ‘--ps’. La resolució en PPP de la imatge es pot establir amb

-dresolution=110
--pdf

Genera PDF. Implica ‘--ps’.

-v, --version

Mostra la informació de la versió.

-V, --verbose

Sigues detallat: mostra les rutes completes de tots els fitxers que se llegeixen, i dóna informació cronomètrica.

-w, --warranty

Mostra la garantia del GNU LilyPond (no ve amb CAP GARANTIA!).


Opcions avançades de la línia d’ordres per al LilyPond

-d[nom-de-opció]=[valor], --define-default=[nom-de-opció]=[valor]

Estableix la funció del Scheme interna equivalent a valor.

-dbackend=svg

Si no es proporciona cap valor, s’usa el valor predeterminat Per desactivar una opció es pot anteposar no- a la variable, per exemple:

-dno-point-and-click

és el mateix que

-dpoint-and-click=#f

Estan contemplades les següents opcions junt als seus respectius valors predeterminats:

SímbolValorExplicació/Opcions
anti-alias-factor (factor d’antiàlies)1Renderitza a una major resolució (utilitzant el factor donat) i redueix l’escala del resultat per així evitar ‘escales’ a les imatges PNG.
aux-files (fitxers auxiliars)#tCrea fitxeres .tex, .texi, .count al ‘back-end’ EPS.
backendpsSelecciona un ‘rerefons’. Els fitxers (l’opció predeterminada) inclouen els tipus tipogràfics de lletra TTF, Type1 i OTF. No es fa cap subconjunt d’aquests tipus de lletra. L’ús de conjunts de caràcters ‘orientals’ pot produir fitxers molts grans.
epsPostScript encapsulat. Bolca cada pàgina o sistema com un fitxer ‘EPS’ diferent, sense tipus tipogràfics de lletra, i com un fitxer ‘EPS’ enquadernat amb totes les pàgines o sistemes que inclouen els tipus de lletra. Utilitzat com a opció predeterminada per part de lilypond-book.
nullNo produeixes cap partitura impresa a la sortida; té el mateix efecte que -dno-print-pages.
svgGràfics vectorials escalables. Crea un únic fitxer SVG, sense tipus tipogràfics de lletra incrustats, per a cada pàgina de sortida. Es recomana instal·lar el tipus de lletra Century Schoolbook, que està inclòs a la instal·lació del LilyPond, per a un renderitzat òptim. Sota l’UNIX, bastarà amb que copieu aquests fitxers de tipus de lletra del directori del Lilypond (normalment ‘/usr/share/lilypond/VERSION/fonts/otf/’) al directori ‘~/.fonts/’. La sortida SVG hauria de ser compatible amb qualsevol editor o client de SVG. També hi ha una opció svg-woff (vegeu més avall) per usar els fitxers de tipus de lletra woff al ‘rerefons’ SVG.
scmBolcat de les instruccions de dibuix internes basades en Scheme, en brut.
check-internal-types n#fComprova el tipus de cada assignació de propietats.
clip-systems (retalla els sistemes de pentagrames)#fGenera framents d’imatge retallats d’una partitura.
datadir (directori de dades)Prefix dels fitxers de dades (sols lectura).
debug-gc#fBolca estadístiques de depuració de memòria.
debug-gc-assert-parsed-dead#fPer a la depuració de memòria: assegura’t que totes les referències a objectes analitzats estiguin mortes. És una opció interna, i s’activa automàticament per a `-ddebug-gc'.
debug-lexer#fDepuració de l’analitzador lèxic flex.
debug-page-breaking-scoring#fBolca les partitures per a moltes configuracions de salts de pàgina diferents.
debug-parser#f fDepuració de l’analitzador sintàctic bison.
debug-property-callbacks#fDepuració de les cadenes cícliues de funcions de callback.
debug-skylines#fDepuració de les línies de horitzó.
delete-intermediate-files#tElimina els fitxers intermedis .ps inútils que es creen durant la compilació.
dump-signatures#fBolca les signatures de sortida de cada sistema. Usat per a les proves de regressió.
eps-box-padding#fOmple la vora esquerra de la capsa contenidora de l’EPS de sortida en la quantitat donada (en mm).
gs-load-fonts#fCarrega els tipus tipogràfics de lletra a través del Ghostscript.
gs-load-lily-fonts#fCarrega sols els tipus de lletra del LilyPond per mitjà del Ghostscript.
gui#fS’executa silenciosament i es redirigeix tota la sortida a un fitxer de registre.

Nota per als usuaris del Windows: De manera predeterminada, lilypond.exe dirigeix tota la sortida de la informació d’avenç cap a la finestra de consola, lilypond-windows.exe no ho fa i retorna un indicador del sistema, sense cap indicació d’avenç, immediatament en la línia d’ordres. L’opció ‘-dgui’ es pot usar en aquest cas per redirigir la sortida a un fitxer de registre.

help#fMostra aquesta ajuda
include-book-title-preview#tInclou els títols de llibre a les imatges de vista prèvia.
include-eps-fonts#tIncloure els tipus tipogràfics de fonts als fitxers EPS de cadascú dels sistemes.
include-settings#fInclou el fitxer dels ajustos globals, s’inclou abans que la partitura es processi.
job-count#fProcessa en paral·lel, usant el nombre de tasques donat.
log-file#f [fitxer]Si es dóna a una cadena fitxer como a segon argument, redirigeix la sortida al fitxer de registre fitxer.log.
max-markup-depth1024Profunditat màxima de l’arbre de l’etiquetatge. Si un etiquetatge té més nivells, suposa que no acabarà per sí mateix, imprimint un advertiment i retornant en el seu lloc un element d’etiquetatge nul.
midi-extension"midi"Fixa l’extensió de fitxer predeterminat per al fitxer de sortida MIDI a la cadena donada.
music-strings-to-paths#fConverteix les cadenes de text a rutes quan els glifs pertanyen a un tipus de lletra de tipografia musical.
paper-size\"a4\"Estableix la mida predeterminada del paper. Observeu que la cadena ha d’anar tancada entre cometes dobles.
pixmap-formatpng16mFixa el format de sortida del Ghostsript per a les imatges de píxels.
point-and-click#fAfegeix enllaços d’‘apuntar i clicar’ a la sortida PDF. Vegeu Point and click.
preview#fCrea imatges de vista prèvia a més de la sortida normal.

Aquesta opció està contemplada per tots els ‘rerefons’: pdf, png, ps, eps i svg, però no per scm. Genera un fitxer de sortida, en la forma elmeuFitxer.preview.extensió, que conté els títols i el primer sistema de la música. Si s’estan utilitzant blocs \book o \bookpart, apareixen a la sortida els títols de \book, \bookpart o \score, inclòs el primer sistema de cada bloc \score si la variable de \paper print-all-headers està fixada al valor #t.

Per suprimir la sortida actual, utilitzeu les opcions ‘-dprint-pages’ o ‘-dno-print-pages’ segons les vostres necessitats.

print-pages#tGenera pàgines completes (és l’opció predeterminada). És útil ‘-dno-print-pages’ en combinació amb ‘-dpreview’.
profile-property-accesses#fConserva les estadístiques de les crides de funció get_property().
protected-scheme-parsing#tContinua quan es capten a l’analitzador sintàctic errors del Scheme encastat. Si es fixa a #f, detenir-se quan hi hagi errors i imprimir un registre de traça de pila.
read-file-list#f [fitxer]Especifica el nom d’un fitxer que conté una llista de fitxers d’entrada per processar.
relative-includes#fQuan es processa una instrucció \include, cerca el fitxer inclòs de forma relativa al fitxer actual (enlloc del fitxer principal).
resolution101Fixa la resolució per generar imatges de píxels PNG al valor donat (en ppp).
safe#fNo confiïs en l’entrada .ly.

Quan el servei de tipografia està disponible a través d’un servidor web, S’HAN DE passar les opcions ‘--safe’ o ‘--jail’. L’opció ‘--safe’ evita que el codi del Scheme faci un desastre, per exemple:

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

L’opció ‘-dsafe’ funciona avaluant les expressions del Scheme en línia dins d’un mòdul segur especial. Deriva del mòdul ‘safe-r5rs’ del GUILE, però a més afegeix unes quantes funcions de l’API del LilyPond que estan relacionades en ‘scm/safe-lily.scm’.

A més, el mode segur prohibeix les directives \include i desactiva la utilització de barres invertides a les cadene de TeX. A més, no és possible importar variables del LilyPond dins del Scheme quan s’està em mode segur.

-dsafeno detecta la sobreutilitizació de recursos, per la qual cosa encara és possible fer que el programa es pengi indefinidament, per exemple subministrant estructures de dades cícliques en el rerefons. Per això, si esteu usant el LilyPond en un servidor web accessible públicament, el procés s’ha de limitar tant en l’ús de memòria com de CPU.

El mode segur evita que es puguin compilar molts fragments de codi útils.

L’opció ‘--jail’ és una alternativa encara més segura, però requereix més feina per a la seva configuració. Vegeu Opcions bàsiques de la línia d’ordres per al LilyPond.

separate-log-files#fPer als fitxers d’entrada FITXER1.ly, FITXER2.ly, etc., treu les dades de registre cap als fitxers FITXER1.log, FITXER2.log
show-available-fonts#fLlista tots els noms dels tipus tipogràfics de lletra disponibles.
strict-infinity-checking#fForça una terminació abrupta si es troben les excepcions de punt flotant Inf i NaN.
strip-output-dir#tNo usis els directoris dels fitxers d’entrada en construir els noms dels fitxers de sortida.
strokeadjust#fForça l’ajust dels traços de PostScript. Aquesta opció és rellevant principalment quan es genera un PDF a partir de la sortida de PostScript (l’ajust del traç està en general activat automàticament per a dispositius de mapa de punts de baixa resolució). Sense aquesta opció, els visors de PDF tendeixen a produir amplades de plica molt poc consistents a les resolucions típiques de les pantalles d’ordinador. L’opció no afecta de forma molt significativa a la qualitat de la impressió i causa grans increments a la mida del fitxer PDF.
svg-woff#fUsar fitxers de tipus tipogràfic de lletra de woff al rerefons SVG.
verbose#fSortida detallada, és a dir el nivell de registre en DEBUT (sols lectura).
warning-as-error#fCanvia tots els missatges d’advertiment i de ‘error de programació’ a errors.

Variables d’entorn

lilypond reconeix les següents variables d’entorn:

LILYPOND_DATADIR

Especifica un directori en el qual els missatges de localització i de dades es buscaran de forma predeterminada. El directori ha de contenir subdirectoris anomenats ‘ly/’, ‘ps/’, ‘tex/’, etc.

LANG

Selecciona l’idioma dels missatges d’advertiment.

LILYPOND_LOGLEVEL

Nivell de registre predeterminat. Si el LilyPond es crida sense cap nivell de registre explícit (és a dir, sense opció de línia d’ordres ‘--loglevel’), s’usa aquest valor.

LILYPOND_GC_YIELD

Una variable, com a percentatge, que ajusta el comportament de l’administració de memòria. Amb valors més alts, el programa usa més memòria; amb valors més baixos, usa més temps de CPU. El valor predeterminat és 70.


El LilyPond a una gàbia de chroot

La preparació del servidor perquè executi el LilyPond a una gàbia de chroot és una tasca molt complicada. Els passos estan relacionats més avall. Els exemples que apareixen en cadascú dels passos son vàlids per a Ubuntu GNU/Linux, i poden requerir l’ús de sudo segons correspongui.

Guió d’exemple per a l’Ubuntu 8.04 de 32 bits

#!/bin/sh
## aquí es fixen els valors predeterminats

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# prefix (sense la barra inicial!)
lilyprefix=usr/local
# el directori en el qual el LilyPond es troba instal·lat 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

# Ara la màgia de copiar les biblioteques
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

# Els fitxers compartits per al ghostcript...
      cp -L -r /usr/share/ghostscript usr/share
# Els fitxers compartits per a l'ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Ara, suposant que tenim test.ly a /mnt/lilyloop/lilyhome,
### hauríem de poder executar:
### Observeu que /$lilyprefix/bin/lilypond és un guió, que estableix
### un valor per a LD_LIBRARY_PATH : això és crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

Notes a peu de pàgina

[1] L’estat del GUILE no es restableix després de processar un fitxer .ly, per la qual cosa heu de tenir cura de no modificar cap valor predeterminat des de dins del Scheme.


LilyPond — Utilització v2.21.82 (branca de desenvolupament).