LilyPond: manuale d'uso del programma: 1.2 Uso da linea di comando

## 1.2 Uso da linea di comando

Questa sezione contiene informazioni aggiuntive sull’uso di LilyPond da linea di comando. Questo può essere utile per assegnare opzioni aggiuntive al programma. Inoltre, ci sono alcuni programmi complementari di ‘aiuto’ (come `midi2ly`) che funzionano solo da linea di comando.

Con ‘linea di comando’ si intende la linea di comando del sistema operativo. Gli utenti Windows avranno più familiarità con i termini ‘shell DOS’ o ‘shell dei comandi’. Gli utenti MacOS X avranno più familiarità con i termini ‘terminale’ o ‘console’. Una configurazione ulteriore è necessaria per gli utenti MacOS X; si veda MacOS X.

Descrivere come usare questa parte di un sistema operativo non rientra negli obiettivi di questo manuale; si prega di consultare altra documentazione su questo argomento se non si conosce la linea di comando.

### Invocare `lilypond`

L’eseguibile `lilypond` può essere lanciato dalla linea di comando nel seguente modo.

>     lilypond [opzione]… file…

Se invocato con un nome di file senza estensione, viene tentata per prima l’estensione ‘`.ly`’. Per leggere l’input da stdin, usare un trattino (`-`) al posto di file.

Quando ‘`file.ly`’ viene elaborato, lilypond creerà ‘`file.ps`’ e ‘`file.pdf`’ come output. Possono essere specificati molti file; ognuno di essi sarà elaborato in modo indipendente. 1

Se ‘`file.ly`’ contiene più di un blocco `\book`, allora tutte le altre partiture verranno salvate in file numerati, a partire da ‘`file-1.pdf`’. Inoltre, il valore di `output-suffix` (suffisso di output) sarà inserito tra la base del nome del file e il numero. Un file di input che contiene

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

produrrà come output base‘`-violin.pdf`’ e base‘`-cello-1.pdf`’.

#### Comandi standard da shell

Se la shell (ovvero la finestra dei comandi) utilizzata supporta le normali redirezioni, potrebbe essere utile usare i seguenti comandi per dirigere l’output di una console in un file:

- `lilypond file.ly 1>stdout.log` per redirigere l’output normale
- `lilypond file.ly 2>stderr.log` per redirigere i messaggi di errore
- `lilypond file.ly &>all.log` per redirigere tutto l’output

Consulta la documentazione della tua shell per vedere se supporta queste opzioni o se la sintassi è diversa. Nota che questi sono comandi shell e non hanno niente a che fare con lilypond.

### Opzioni della linea di comando per `lilypond`

Sono contemplate le seguenti opzioni:

`-e,--evaluate=espressione`

  Valuta l’espressione di Scheme prima di analizzare qualsiasi file ‘`.ly`’. Si possono specificare varie opzioni `-e`; saranno analizzate in modo sequenziale.

  L’espressione sarà analizzata nel modulo `guile-user`, dunque se vuoi usare delle definizioni in espressione, usa

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

  nella linea di comando, e includi

  >     #(use-modules (guile-user))

  in cima al file `.ly`.

`-f,--format=formato`

  Formati di output. Come `formato` si può scegliere tra `ps`, `pdf`, e `png`.

  Esempio: `lilypond -fpng file.ly`

`-d,--define-default=variabile=valore`

  Imposta l’opzione interna del programma, variabile, al valore di Scheme valore. Se valore non viene specificato, allora viene usato #t. Per disabilitare un’opzione, si può usare il prefisso `no-` prima della variabile, ad esempio

  >     -dno-point-and-click

  è equivalente a

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

  Di seguito alcune opzioni interessanti.

  ‘`help`’

    L’esecuzione di `lilypond -dhelp` mostrerà tutte le opzioni disponibili di `-d`.

  ‘`paper-size`’

    Questa opzione imposta la dimensione predefinita del foglio,

    >     -dpaper-size=\"letter\"

    Nota che la stringa deve essere compresa tra virgolette precedute dal segno di escape ( `\"` ).

  ‘`safe`’

    Non si fida dell’input nel file `.ly`.

    Quando la formattazione di LilyPond viene messa a disposizione tramite un server web, si DEVE passare l’opzione `--safe` o l’opzione `--jail`. L’opzione `--safe` impedirà che il codice Scheme presente nell’input possa fare uno scempio, ad esempio

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

    L’opzione `-dsafe` serve a valutare le espressioni Scheme presenti nell’input in uno speciale modulo di sicurezza. Questo modulo di sicurezza è derivato dal modulo GUILE ‘`safe-r5rs`’, ma aggiunge alcune funzioni del LilyPond API. Queste funzioni sono elencate in ‘`scm/safe-lily.scm`’.

    Inoltre, la modalità sicura non permette le direttive `\include` e disabilita l’uso del backslash nelle stringhe TeX.

    In modalità sicura, non è possibile importare le variabili di LilyPond in Scheme.

    `-dsafe` non rileva il sovrautilizzo di risorse. È ancora possibile far sì che il programma rimanga in sospeso per un tempo indefinito, ad esempio alimentando il backend con strutture di dati cicliche. Dunque se si vuole usare LilyPond su un server web pubblicamente accessibile, si deve limitare il processo nell’uso della CPU e della memoria.

    La modalità sicura bloccherà la compilazione di molti utili frammenti di codice LilyPond. L’opzione `--jail` è un’alternativa più sicura, ma richiede più lavoro per configurarla.

  ‘`backend`’

    il formato di output da usare per il back-end. Per il `formato` si può scegliere tra

    `ps`

      per PostScript.

      I file Postscript includono i tipi di carattere TTF, Type1 e OTF. Non vengono inclusi i sottoinsiemi di questi tipi. Se si usa un set di caratteri orientali, si possono ottenere file di grosse dimensioni.

    `eps`

      per PostScript incapsulato. Invia ogni pagina (sistema) in un file ‘`EPS`’ separato, senza font, e in un unico file ‘`EPS`’ con tutte le pagine (sistemi) inclusi i font.

      Questa è la modalità predefinita di `lilypond-book`.

    `svg`

      per ottenere SVG (Scalable Vector Graphics).

      Crea un singolo file SVG, senza font incorporati, per ogni pagina dell’output. Si raccomanda di installare i font Century Schoolbook, inclusi nell’installazione di LilyPond, per una resa ottimale. In UNIX basta copiare questi font dalla directory di LilyPond (solitamente ‘`/usr/share/lilypond/VERSION/fonts/otf/`’) in ‘`~/.fonts/`’. L’output SVG dovrebbe essere compatibile con qualsiasi editor SVG o user agent.

    `scm`

      per estrarre i comandi di disegno grezzi e interni, basati su Scheme.

    `null`

      non produce la stampa della partitura; ha lo stesso effetto di `-dno-print-pages`.

    Esempio: `lilypond -dbackend=svg filename.ly`

  ‘`preview`’

    Genera un file di output che contiene i titoli e il primo sistema del brano musicale. Se si usano i blocchi `\bookpart`, i titoli e il primo sistema di ogni `\bookpart` apparirà nell’output. I backend `ps`, `eps`, e `svg` supportano questa opzione.

  ‘`print-pages`’

    Genera tutte le pagine, come da impostazione predefinita. `-dno-print-pages` è utile in combinazione con `-dpreview`.

`-h,--help`

  Mostra una sintesi dell’utilizzo.

`-H,--header=CAMPO`

  Estrae un campo dell’intestazione nel file ‘`NOME.CAMPO`’.

`--include, -I=directory`

  Aggiunge directory al percorso di ricerca per i file di input.

  È possibile assegnare più opzioni -I. La ricerca inizierà nella prima directory definita, e se il file da includere non viene trovato la ricerca continuerà nelle directory seguenti.

`-i,--init=file`

  Imposta il file di inizializzazione su file (predefinito: ‘`init.ly`’).

`-o,--output=FILE or CARTELLA`

  Imposta il file di output predefinito FILE oppure, se una cartella con quel nome esiste già, dirige l’output in CARTELLA, prendendo il nome del file dal file di input. In entrambi i casi verrà aggiunto il suffisso appropriato (ad esempio `.pdf` per il pdf).

`--ps`

  Genera PostScript.

`--png`

  Genera immmagini di ogni pagina in formato PNG. Questo implica `--ps`. La risoluzione in DPI dell’immagine può essere impostata con

  >     -dresolution=110

`--pdf`

  Genera PDF. Questo implica `--ps`.

`-j,--jail=utente,gruppo,gabbia,directory`

  Esegue `lilypond` in una gabbia chroot.

  L’opzione `--jail` fornisce un’alternativa più flessibile a `--safe` quando la formattazione di LilyPond è messa a disposizione attraverso un server web o quando LilyPond esegue sorgenti provenienti dall’esterno.

  L’opzione `--jail` modifica la radice di `lilypond` in gabbia appena prima di iniziare il vero processo di compilazione. L’utente e il gruppo vengono poi modificati per corrispondere a quelli forniti, e la directory corrente viene spostata in directory. Questa configurazione garantisce che non sia possibile (almeno in teoria) uscire dalla gabbia. Si noti che perché `--jail` funzioni `lilypond` deve essere eseguito come root; di solito questo si fa in modo sicuro col comando `sudo`.

  Configurare una gabbia è una questione un po’ delicata, perché bisogna essere sicuri che LilyPond possa trovare tutto quello di cui ha bisogno per compilare il sorgente dentro la gabbia. Una configurazione tipica comprende i seguenti elementi:

  Impostare un filesystem distinto

    Si dovrebbe creare un filesystem separato LilyPond, così che possa essere montato con opzioni di sicurezza come `noexec`, `nodev`, e `nosuid`. In questo modo è impossibile lanciare degli eseguibili o scrivere su un dispositivo direttamente da LilyPond. Se non si vuole creare una partizione separata, si può creare un file di dimensioni ragionevoli e usarlo per montare un dispositivo di loop. Un filesystem separato garantisce inoltre che LilyPond non possa scrivere su uno spazio maggiore di quanto permesso.

  Impostare un altro utente

    Per eseguire LilyPond in una gabbia si dovrebbe usare un altro utente e gruppo (ad esempio, `lily`/`lily`) con pochi privilegi. Ci dovrebbe essere una sola directory scrivibile da questo utente, che dovrebbe essere passata in dir.

  Preparare la gabbia

    LilyPond ha bisogno di leggere alcuni file quando viene lanciato. Tutti questi file devono essere copiati nella gabbia, sotto lo stesso percorso in cui appaiono nel vero filesystem principale. Si deve copiare l’intero contenuto dell’installazione LilyPond installation (ad esempio, ‘`/usr/share/lilypond`’).

    Se c’è un problema, il modo più semplice per individuarlo è lanciare LilyPond usando `strace`, che permetterà di scoprire quali file mancano.

  Eseguire LilyPond

    In una gabbia montata con `noexec` è impossibile eseguire qualsiasi programma esterno. Dunque LilyPond deve essere eseguito con un backend che non richieda tale programma. Come è già stato detto, deve essere eseguito con privilegi di superutente (che ovviamente perderà immediatamente), possibilmente con l’uso di `sudo`. È una buona idea limitare il numero di secondi di tempo della CPU che LilyPond può usare (ad esempio con `ulimit -t`), e, se il sistema operativo lo permette, la quantità di memoria che può essere allocata.

`-v,--version`

  Mostra informazioni sulla versione.

`-V,--verbose`

  Aumenta la prolissità: mostra i percorsi completi di tutti i file letti, e dà informazioni sui tempi.

`-w,--warranty`

  Mostra la garanzia con cui viene distribuito GNU LilyPond. (Distribuito con NESSUNA GARANZIA!)

### Variabili d’ambiente

`lilypond` riconosce le seguenti variabili d’ambiente:

`LILYPOND_DATADIR`

  Specifica la directory predefinita in cui saranno cercati i messaggi della localizzazione e i file di dati. Questa directory deve contenere sottodirectory chiamate ‘`ly/`’, ‘`ps/`’, ‘`tex/`’, etc.

`LANG`

  Determina la lingua per i messaggi di avviso.

`LILYPOND_GC_YIELD`

  Una variabile, in forma di percentuale, che regola il modo in cui viene gestita la memoria. Con valori più alti il programma usa più memoria, con valori più bassi usa più tempo della CPU. Il valore predefinito è `70`.

### LilyPond in una gabbia chroot

Configurare un server perché esegua LilyPond in una gabbia chroot è un lavoro complesso. La procedura è spiegata sotto. Gli esempi si riferiscono a Ubuntu Linux e potrebbero richiedere l’uso di `sudo` in alcune situazioni.

- Installa i pacchetti necessari: LilyPond, GhostScript e ImageMagick.
- Crea un nuovo utente dal nome `lily`:

  >     adduser lily

  Questo comando creerà anche un nuovo gruppo per l’utente `lily`, e una cartella home, `/home/lily`

- Nella cartella home dell’utente `lily` crea un file da usare come filesystem separato:

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

  In questo esempio è stato creato un file di 200MB da usare come filesystem della gabbia.

- Crea un dispositivo di loop, crea e monta un filesystem, quindi crea una cartella scrivibile dall’utente `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

- Nella configurazione dei server, JAIL sarà `/mnt/lilyloop` e DIR sarà `/lilyhome`.
- Crea un grande albero delle directory nella gabbia copiando i file necessari, come mostrato nello script di esempio più in basso.

  Puoi usare `sed` per creare i comandi di copia necessari per un certo eseguibile:

  >     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

### Script di esempio per Ubuntu 8.04 a 32-bit

>     #!/bin/sh
>     ## defaults set here

>     username=lily
>     home=/home
>     loopdevice=/dev/loop0
>     jaildir=/mnt/lilyloop
>     # the prefix (without the leading slash!)
>     lilyprefix=usr/local
>     # the directory where lilypond is installed on the system
>     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

>     # Now the library copying magic
>     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

>     # The shared files for ghostscript...
>           cp -L -r /usr/share/ghostscript usr/share
>     # The shared files for ImageMagick
>           cp -L -r /usr/lib/ImageMagick* usr/lib

>     ### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
>     ### you should be able to run:
>     ### Note that /$lilyprefix/bin/lilypond is a script, which sets the
>     ### LD_LIBRARY_PATH - this is crucial
>           /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

### Note a piè di pagina

[1] Lo status di GUILE non viene resettato dopo l’elaborazione di un file `.ly`: attenzione a non cambiare alcun valore predefinito dall’interno di Scheme.

Other languages: English, deutsch, español, français, magyar, 日本語.

#### LilyPond — Utilizzo