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

@translationof Command-line usage

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 (web)MacOS X section ‘MacOS X’ in Informació general.

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

@translationof Invoking 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 independent(1).

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

@translationof Basic command line options for 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

@translationof Advanced command line options for 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:

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.

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.

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.

Variables d’entorn

@translationof Environment variables

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

@translationof LilyPond in chroot jail

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

This document was generated by gub on Juliol 13, 2020 using texi2html 1.82.

Altres idiomes: English, deutsch, español, français, magyar, italiano, 日本語.
Quant a la selecció automàtica de la llengua.