[ << Execució del LilyPond ] | [Part superior][Continguts][Índex] | [ Actualització de fitxers amb convert-ly >> ] |
[ < Utilització normal ] | [ Amunt : Execució del LilyPond ] | [ Invocació del LilyPond > ] |
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 | ||
Opcions bàsiques de la línia d’ordres per al LilyPond | ||
Opcions avançades de la línia d’ordres per al LilyPond | ||
Variables d’entorn | ||
El LilyPond a una gàbia de chroot |
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:
-
lilypond fitxer.ly 1>sortidaestandard.log
per redirigir la sortida normal -
lilypond fitxer.ly 2>sortidaderror.log
per redirigir els missatges d’error -
lilypond fitxer.ly &>tot.log
per redirigir tota la sortida
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’utilitzarlilypond -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ónps
,pdf
, ipng
.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’executarlilypond
com root, cosa que normalment es pot fer d’una forma segura utilitzantsudo
.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
inosuid
. 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 usantsudo
. També de CPU que el LilyPond pot usar (per exemple usantulimit -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ímbol | Valor | Explicació/Opcions |
anti-alias-factor (factor d’antiàlies) | 1 | Renderitza 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) | #t | Crea fitxeres .tex , .texi , .count al
‘back-end’ EPS . |
backend | ps | Selecciona 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. |
svg | Grà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. | |
clip-systems (retalla els sistemes de pentagrames) | #f | Genera framents d’imatge retallats d’una partitura. |
datadir (directori de dades) | Prefix dels fitxers de dades (sols lectura). | |
debug-skylines | #f | Depuració de les línies de horitzó. |
delete-intermediate-files | #t | Elimina els fitxers intermedis .ps inútils que es
creen durant la compilació. |
eps-box-padding | #f | Omple la vora esquerra de la capsa contenidora de l’EPS de sortida en la quantitat donada (en mm). |
gs-load-fonts | #f | Carrega els tipus tipogràfics de lletra a través del Ghostscript. |
gs-load-lily-fonts | #f | Carrega sols els tipus de lletra del LilyPond per mitjà del Ghostscript. |
help | #f | Mostra aquesta ajuda |
include-book-title-preview | #t | Inclou els títols de llibre a les imatges de vista prèvia. |
include-eps-fonts | #t | Incloure els tipus tipogràfics de fonts als fitxers EPS de cadascú dels sistemes. |
include-settings | #f | Inclou el fitxer dels ajustos globals, s’inclou abans que la partitura es processi. |
job-count | #f | Processa 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-depth | 1024 | Profunditat 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 | #f | Converteix 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-format | png16m | Fixa el format de sortida del Ghostsript per a les imatges de píxels. |
point-and-click | #f | Afegeix enllaços d’‘apuntar i
clicar’ a la sortida PDF . Vegeu
Point and click. |
preview | #f | Crea 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 | #t | Genera pàgines completes (és l’opció predeterminada). És útil ‘-dno-print-pages’ en combinació amb ‘-dpreview’. |
protected-scheme-parsing | #t | Continua 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. |
relative-includes | #f | Quan es processa una instrucció \include , cerca el
fitxer inclòs de forma relativa al fitxer actual (enlloc del
fitxer principal). |
resolution | 101 | Fixa la resolució per generar imatges de píxels PNG al
valor donat (en ppp). |
safe | #f | No 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.
‘-dsafe’ no 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 | #f | Per als fitxers d’entrada FITXER1.ly ,
FITXER2.ly , etc., treu les dades de registre cap als
fitxers FITXER1.log , FITXER2.log … |
show-available-fonts | #f | Llista tots els noms dels tipus tipogràfics de lletra disponibles. |
strip-output-dir | #t | No usis els directoris dels fitxers d’entrada en construir els noms dels fitxers de sortida. |
strokeadjust | #f | Forç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 | #f | Usar fitxers de tipus tipogràfic de lletra de woff al rerefons SVG. |
verbose | #f | Sortida detallada, és a dir el nivell de registre en DEBUT (sols lectura). |
warning-as-error | #f | Canvia 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.
- Instal·leu els paquets necessaris: el LilyPond, el Ghostscript i l’ImageMagick.
- Creeu un usuari nou amb el nom de
lily
:adduser lily
Això també crearà un nou grup per a l’usuari
lily
, i una carpeta personal,/home/lily
- A la carpeta personal de l’usuari
lily
, creeu un fitxer per usar-lo com a sistema de fitxers separat:dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
Aquest exemple crea un fitxer de 200MB per al seu ús com el sistema de fitxers de la gàbia.
- Creeu un dispositiu loop, feu un sistema de fitxers i munteu-lo,
després creeu una carpeta que es pugui escriure per l’usuari
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ó dels servidors, JAIL serà
/mnt/lilyloop
i DIR serà/lilyhome
. - Creeu un gran arbre de directoris dins de la gàbia copiant els
fitxers necessaris, com es mostra en el guió d’exemple que apareix
més avall.
Podeu usar
sed
per crear els fitxeres de còpia necessaris per a un executable donat: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ó 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.