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

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Uso normale ]	[ Su : Eseguire lilypond ]	[ Utilizzo di LilyPond > ]

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.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Uso da linea di comando ]	[ Su : Uso da linea di comando ]	[ > ]

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

Nota: Nelle versioni di Windows precedenti a Windows 10 1903, LilyPond non sa gestire i nomi file Unicode.

Quando ‘file.ly’ viene elaborato, lilypond crea ‘file.pdf’ come output predefinito. Possono essere specificati molti file, ognuno dei quali viene elaborato in modo indipendente.¹

Se ‘file.ly’ contiene più di un blocco \book, tutte le altre partiture sono salvate in file numerati, a partire da ‘file-1.pdf’. Inoltre, il valore di output-suffix (suffisso di output) viene inserito tra la base del nome del file e il numero. Per esempio, se ‘file.ly’ contiene

#(define output-suffix "violino")
\score { … }
#(define output-suffix "violoncello")
\score { … }

LilyPond produce come output ‘file-violino.pdf’ e ‘file-violoncello-1.pdf’.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Utilizzo di LilyPond ]	[ Su : Utilizzo di LilyPond ]	[ Opzioni di base della linea di comando per LilyPond > ]

Usare LilyPond con funzionalità standard della shell

Dato che LilyPond è un’applicazione a linea di comando, si possono sfruttare le funzionalità della ‘shell’ usata per lanciare LilyPond.

Per esempio,

lilypond *.ly

elabora tutti i file LilyPond nella directory corrente.

Potrebbe essere utile anche redirigere l’output della console (per esempio, in un file):

lilypond file.ly 1> stdout.txt

lilypond file.ly 2> stderr.txt

lilypond file.ly &> all.txt

Questi comandi redirigono rispettivamente l’output ‘normale’, gli ‘errori’ o ‘tutto’ in file di testo. Consulta la documentazione della tua shell, del prompt dei comandi (Windows), delle applicazioni Terminale o Console (MacOS X), per verificare se la redirezione dell’output è supportata o se la sintassi è diversa.

L’esempio seguente cerca e elabora tutti i file di input nella directory corrente e in tutte le directory inferiori ricorsivamente. I file di output vengono salvati nella stessa directory in cui è stato lanciato il comando, invece delle stesse directory in cui si trovano i file di input.

find . -name '*.ly' -exec lilypond '{}' \;

Questo comando dovrebbe funzionare anche in MacOS X.

Gli utenti Windows devono lanciare questo comando:

forfiles /s /M *.ly /c "cmd /c lilypond @file"

nel prompt dei comandi, che di solito si trova in Avvio > Accessori > Prompt dei comandi, oppure scrivendo ‘prompt dei comandi’ nella finestra di ricerca.

Altrimenti, si può indicare un percorso esplicito alla cartella che contiene tutte le sottocartelle con i file di input tramite l’opzione /p:

forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @file"

Tale percorso, se contiene spazi, deve essere racchiuso tra virgolette doppie:

forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @file"

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < ]	[ Su : Uso da linea di comando ]	[ Opzioni avanzate della linea di comando per LilyPond > ]

Opzioni di base della linea di comando per LilyPond

Sono contemplate le seguenti opzioni.

-d, --define-default=variabile[=valore]

Si veda Opzioni avanzate della linea di comando per lilypond.

-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 viene analizzata nel modulo guile-user, dunque se vuoi usare una definizione come (define-public a 42) in espressione, usa

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

nella linea di comando, e includi

#(use-modules (guile-user))

in cima al file ‘.ly’.

Nota: Gli utenti Windows devono usare i doppi apici invece dei singoli apici.

-E, --eps

Genera file EPS.

Questa opzione è simile a -dseparate-page-formats=ps.

-f, --format=formato

Formato del (principale) file di output. I valori possibili di formato sono ps, pdf, png o svg.

Esempio: lilypond -fpng file.ly

Internamente SVG utilizza un backend specifico e dunque non si può ottenere nella stessa esecuzione usata per altri formati; -fsvg o --svg sono in realtà equivalenti all’opzione -dbackend=svg. Vedi Opzioni avanzate della linea di comando per lilypond.

-h, --help

Mostra una sintesi dell’utilizzo.

-H, --header=CAMPO

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

Per esempio, supponiamo di avere un file di input ‘pippo.ly’ contenente

\header { title = "pluto" }
\score { c1 }

Il comando

lilypond -H title pippo.ly

crea un file di testo semplice ‘pippo.title’ contenente la stringa pluto.

-i, --init=file

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

-I, --include=directory

Aggiunge directory al percorso di ricerca per i file di input con percorsi relativi. Per impostazione predefinita, cerca solo nella directory di lavoro corrente.

È possibile assegnare più opzioni ‘-I’. La ricerca inizia nella directory di lavoro corrente, e se il file da includere non viene trovato la ricerca continua nella directory indicata dalla prima opzione ‘-I’, poi nella directory della seconda opzione ‘-I’ e così via.

Nota: L’uso del carattere tilde (~) con l’opzione ‘-I’ potrebbe causare risultati inaspettati in alcune shell.

Gli utenti Windows devono aggiungere una barra obliqua al termine del percorso della directory.

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

[Questa opzione è disponibile solo per i sistemi operativi che supportano la funzionalità chroot. Windows non la supporta.]

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 (si veda Opzioni avanzate della linea di comando per lilypond).

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 (ad esempio, ‘/usr/share/lilypond’).

Se c’è un problema, il modo più semplice per individuarlo è lanciare LilyPond usando strace, che permette 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 perde 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. Si veda anche LilyPond in una gabbia chroot.

-l, --loglevel=livello

Imposta la verbosità dell’output della console su livello. I valori possibili sono:

NONE: Nessun output, nemmeno i messaggi di errore.
ERROR: Solo i messaggi di errore, niente avvisi o messaggi di elaborazione.
WARN: Avvisi e messaggi di errore, nessun messaggio di elaborazione.
BASIC_PROGRESS: Messaggi di elaborazione di base (riuscita), avvisi e errori.
PROGRESS: Tutti i messaggi di elaborazione, avvisi e errori.
INFO: Messaggi di elaborazione, avvisi, errori e ulteriori informazioni di esecuzione. Questo è il valore predefinito.
DEBUG: Tutti i messaggi possibili, incluso l’output verboso di debug.

-o, --output=file

-o, --output=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 viene aggiunto il suffisso appropriato (ad esempio ‘.pdf’ per il PDF).

-O, --pspdfopt

Imposta l’ottimizzazione dell’output PS/PDF su chiave. I valori possibili sono:

size

Genera un documento PS/EPS/PDF molto piccolo. Questo è il valore predefinito.

L’uso di questo valore è equivalente a impostare le opzioni a linea di comando Scheme di LilyPond -dmusic-font-encodings='#f' e -dgs-never-embed-fonts='#f'.

TeX

Produce file ottimizzati per l’inclusione in documenti pdfTeX, LuaTeX o XeTeX.

L’uso di questo valore è equivalente a impostare le opzioni a linea di comando Scheme di LilyPond -dmusic-font-encodings='#t' e -dgs-never-embed-fonts='#f'.

TeX-GS

Se si desidera includere più di un PDF generato da LilyPond in un documento TeX, usare questa opzione e rielaborare il PDF generato da TeX con Ghostscript.

L’uso di questo valore è equivalente a impostare le opzioni a linea di comando Scheme di LilyPond -dmusic-font-encodings='#t' e -dgs-never-embed-fonts='#t'.

--ps

Questa opzione è equivalente a -fps.

--png

Genera immagini di ogni pagina in formato PNG. Questa opzione è equivalente a -fpng.

La risoluzione dell’immagine può essere impostata in N DPI con

-dresolution=N

--pdf

Genera PDF. Questa è l’opzione predefinita ed è equivalente a -fpdf.

-s, --silent Non mostra il progresso, ma solo i messaggi di errore. È equivalente a -lERROR.

--svg

Genera file SVG per ciascuna pagina. Questa opzione è equivalente a -fsvg.

-v, --version

Mostra informazioni sulla versione.

-V, --verbose

Aumenta la prolissità: mostra i percorsi completi di tutti i file letti, dà informazioni sui tempi, etc. È equivalente a -lDEBUG.

-w, --warranty

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

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Opzioni di base della linea di comando per LilyPond ]	[ Su : Uso da linea di comando ]	[ Variabili d'ambiente > ]

Opzioni avanzate della linea di comando per `lilypond`

L’opzione ‘-d’ è l’interfaccia a linea di comando alla funzione Scheme di LilyPond ly:set-option. Ciò significa che tutte le opzioni elencate qui possono essere impostate anche nei file ‘.ly’.

-d, --define-default=nome-opzione[=valore

-d, --define-default=no-nome-opzione

Imposta l’equivalente simbolo interno di Scheme su nome-opzione. Per esempio, l’opzione da linea di comando

-dbackend=svg

è equivalente a

#(ly:set-option 'backend 'svg)

in un file di input di LilyPond.

Se non viene specificato un valore, viene usato il valore predefinito #t (che potrebbe produrre risultati strani se il valore atteso non è di tipo booleano). Per disabilitare un’opzione, si può usare il prefisso no- prima di nome-opzione. Per esempio:

-dpoint-and-click='#f'

è equivalente a

-dno-point-and-click

[Attenzione: il carattere ‘#’ introduce un commento in molte shell, dunque si raccomanda di racchiudere sempre tra virgolette le espressioni che lo contengono.]

La seguente tabella elenca tutti i nomi delle opzioni supportate insieme ai loro rispettivi valori. All’interno del codice Scheme, i valori delle opzioni possono essere letti usando la funzione ly:get-option.

anti-alias-factor

num Elabora a una risoluzione più alta (usando il fattore num, che deve essere un numero intero positivo ≤8) e ridimensiona il risultato per evitare gli “artefatti” nelle immagini PNG. Predefinito: 1.

aux-files

bool Se bool è #t, crea i file ‘.tex’, ‘.texi’ e ‘.count’. Questa opzione viene usata principalmente da lilypond-book. Predefinito: #f.

backend simbolo

Usa simbolo come backend per l’output di LilyPond. I valori possibili sono:

ps

Questa è l’impostazione predefinita. I file PostScript comprendono 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.

Anche per l’output PDF viene usato il backend ps; i dati PS risultanti sono poi rielaborati dallo script di Ghostscript ps2pdf, che si occupa anche dei sottoinsiemi di font.

svg

Scalable Vector Graphics. Viene creato un singolo file SVG per ogni pagina dell’output. I glifi musicali vengono tradotti in grafica vettoriale, ma i tipi di carattere del testo non sono incorporati nei file SVG. Dunque qualsiasi lettore SVG dovrà avere accesso ai tipi di carattere necessari per rendere in modo adeguato il testo. Si raccomanda di non usare “liste” o “alias” dei tipi di carattere se il lettore SVG non è in grado di gestirli. Se si usano i file Web Open Font Format (WOFF), è richiesta anche l’opzione svg-woff.

clip-systems bool

Se bool è #t, estrae frammenti musicali da una partitura. Per far ciò è necessario che sia stata definita la funzione clip-regions all’interno del blocco \layout. Maggiori informazioni in Estrarre frammenti musicali. Nessun frammento verrà estratto se questa opzione è usata insieme all’opzione ‘-dno-print-pages’. Predefinito: #f.

crop bool

Se bool è #t, viene creato un secondo file PDF (con estensione ‘.cropped.pdf’), insieme a un’immagine (con estensione ‘.cropped.png’). Questo file di output comprime tutta la musica e le intestazioni, senza margini, in una sola pagina, possibilmente alta. Se è impostata l’opzione ‘--svg’, viene prodotto invece un ulteriore file SVG (con estensione ‘.cropped.svg’). Se è impostata l’opzione ‘--eps’ o ‘--ps’, al posto di un file PDF ritagliato viene prodotto invece un EPS ritagliato (con estensione ‘.cropped.eps’). Predefinito: #f.

Si noti che attualmente questa opzione non è adatta all’output con molti sistemi perché viene tolto lo spazio verticale tra i sistemi.

datadir

Prefisso per i file di dati. Questa è un’opzione di sola lettura; la sua impostazione non ha effetto.

debug-eval bool

Se bool è #t, usa l’analizzatore di debug Scheme, che in caso di errori mostra le backtrace con i numeri di linea. Predefinito: #f, o #t quando si usa --verbose.

debug-skylines bool

Se bool è #t, fa il debug dei profili (“skyline”). Predefinito: #f.

delete-intermediate-files bool

Se bool è #t, cancella i file ‘.ps’ intermedi e inutilizzabili creati durante la compilazione. Predefinito: #t.

embed-source-code bool

Se bool è #t, incorpora i file sorgente LilyPond nel documento PDF generato. Predefinito: #f.

eps-box-padding num

Sposta il margine sinistro della cornice EPS dell’output di num millimetri. Predefinito: f (ovvero nessuna cornice).

font-export-dir stringa

Imposta la directory per esportare i font come file PostScript su stringa. È utile quando si desidera creare prima un PDF senza font incorporati e poi incorporarli con Ghostscript come mostrato sotto.

$ lilypond -dfont-export-dir=fontdir -dgs-never-embed-fonts foo.ly
$ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
     -sOutputFile=foo.embedded.pdf foo.pdf fontdir/*.font.ps

Nota: Diversamente da font-ps-resdir, questo metodo non permette di incorporare i font CID con Ghostscript 9.26 e versioni successive.

Nota: Come con font-ps-resdir, questa opzione non agisce sui font TrueType, perché incorporare i font TrueType successivamente produce caratteri confusi. Per evitare che i caratteri siano confusi, usare gs-never-embed-fonts, che a dispetto del nome incorpora i font TrueType.

Predefinito: #f (ovvero non esportare).

font-ps-resdir stringa

Imposta la directory (come stringa) per generare un sottoinsieme della directory delle risorse PostScript da usare successivamente per incorporare i font. È utile quando si desidera creare prima un PDF senza font incorporati e poi incorporarli con Ghostscript come mostrato sotto.

$ lilypond -dfont-ps-resdir=resdir -dgs-never-embed-fonts foo.ly
$ gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite \
     -I resdir -I resdir/Font \
     -sOutputFile=foo.embedded.pdf foo.pdf

Nota: È meglio che la directory specificata non contenga il nome ‘Resource’ perché ha un significato speciale quando utilizzata con l’opzione -I di Ghostscript.

Nota: Diversamente da font-export-dir, questo metodo permette di incorporare i font CID con Ghostscript 9.26 e versioni successive.

Note: Come con font-export-dir, questa opzione non agisce sui font TrueType, perché incorporare i font TrueType successivamente produce caratteri confusi. Per evitare che i caratteri siano confusi, usare gs-never-embed-fonts, che a dispetto del nome incorpora i font TrueType.

Predefinito: #f (ovvero non generare niente).

gs-load-fonts

bool Se bool è #t, carica i font attraverso Ghostscript. Questa opzione fa sì che file di output di LilyPond contengano solo i riferimenti a tutti i font, che devono essere risolti in font reali in un passaggio successivo di elaborazione da parte di Ghostscript. Predefinito: #f.

gs-load-lily-fonts

bool Se bool è #t, carica i font LilyPond attraverso Ghostscript. Questa opzione fa sì che file di output di LilyPond contengano solo i riferimenti ai suoi font musicali, che devono essere risolti in font reali in un passaggio successivo di elaborazione da parte di Ghostscript. Tutti gli altri font sono generati normalmente. Predefinito: #f.

gs-never-embed-fonts

bool Se bool è #t, fa sì che Ghostscript incorpori solo i font TrueType e nessun altro formato per font. Predefinito: #f.

help

bool Se bool è #t, mostra questo aiuto. Predefinito: #f.

include-book-title-preview

bool Se bool è #t, include i titoli dei libri nelle immagini di anteprima. Predefinito: #t.

include-eps-fonts

bool Se bool è #t, include i font in file EPS con sistemi separati. Predefinito: #t.

include-settings

stringa Include il file stringa per le impostazioni globali, che viene incluso prima che la partitura sia elaborata. Predefinito: #f (ovvero nessun file per le impostazioni globali).

job-count

num Elabora in parallelo, usando num lavori. Predefinito: #f (ovvero nessuna elaborazione in parallelo).

log-file

string Redirige l’output nel file di log ‘stringa.log’. Predefinito: #f (ovvero nessun file di log).

max-markup-depth

num Imposta la massima profondità per la struttura del blocco markup sul valore num. Se un blocco markup ha più livelli, assume che non terminerà da solo, stampa un avviso e restituisce al suo posto un markup vuoto. Predefinito: 1024.

midi-extension

string Imposta l’estensione predefinita per il file MIDI su ‘.stringa’. Predefinito: "midi".

music-strings-to-paths

bool Se bool è #t, converte le stringhe di testo in percorsi quando i glifi appartengono a un font musicale. Predefinito: #f.

paper-size

stringa-tra-virgolette Imposta la dimensione predefinita del foglio su stringa-tra-virgolette. Nota che la stringa deve essere racchiusa tra virgolette precedute dal segno di escape. Predefinito: "\"a4\"".

pixmap-format

simbolo Imposta il formato di output di Ghostscript per le immagini raster su simbolo. Predefinito: png16m.

png-width larghezza

png-height altezza

Per l’output PNG, imposta la larghezza e l’altezza (in pixel) del file immagine creato. Se manca una delle opzioni, l’altra dimensione viene calcolata in base al riquadro di delimitazione EPS, mantenendo le proporzioni.

Oltre a ‘--png’, per ottenere una scala corretta dell’immagine senza tagli, si deve usare ‘--eps’, ‘-dcrop’ o ‘-dpreview’.

L’opzione ‘-dresolution’ viene ignorata.

Attenzione, c’è un bug nelle versioni di ghostscript fino alla 9.52 che riguarda queste due opzioni: produce immagini PNG vuote se l’altezza è più grande della larghezza.

point-and-click

bool Se bool è #t, aggiunge i collegamenti “punta e clicca” all’output PDF e SVG. Si veda Punta e clicca. Predefinito: #t.

preview

bool Se bool è #t, crea immagini di anteprima oltre al normale output.

Predefinito: #f.

Questa opzione è supportata da tutti i backend (pdf, png, ps, eps e svg, eccetto scm. Per un file di input chiamato file e backend formato, genera un file di output dal nome ‘file.preview.formato’, contenente i titoli e il primo sistema. Se vengono usati i blocchi \book o \bookpart, i titoli di \book, \bookpart o \score appariranno nell’output, incluso il primo sistema di ogni blocco \score se la variabile print-all-headers di \paper è impostata su #t.

Per impedire il normale output, si usano le opzioni ‘-dprint-pages’ o ‘-dno-print-pages’ in base alle proprie esigenze.

print-pages

bool Se bool è #t, genera le pagine complete. Predefinito: #t.

L’opzione ‘-dno-print-pages’ è utile in combinazione con ‘-dpreview’ o ‘-dcrop’.

protected-scheme-parsing bool

Se bool è #t, continua finché l’analizzatore non coglie degli errori nel codice Scheme interno al file di input. Se impostato su #f, in caso di errore si ferma e mostra la traccia di stack. Predefinito: #t.

relative-includes

bool Quando elabora un comando \include, cerca il file incluso in posizione relativa al file corrente se bool è #t. Se impostato su #f, cerca il file relativo al file root. Predefinito: #t.

resolution

num Imposta la risoluzione per generare immagini PNG su num dpi. Predefinito: 101.

safe

bool Se bool è #t, non si fida dell’input nel file ‘.ly’. Predefinito: #f.

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

% troppo pericoloso per scriverlo correttamente
#(s ystem "rm -rf /")

% malvagio ma non distruttivo
{ c4^$(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.

L’opzione ‘-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. Si veda Opzioni di base della linea di comando per LilyPond.

separate-log-files

bool Per i file di input ‘file1.ly’, ‘file2.ly’, …, salva i dati di log nei file ‘file1.log’, ‘file2.log’, …, se bool è #t. Predefinito: #f.

separate-page-formats simbolo

Elenco separato da virgola di formati (svg, pdf, png o eps) da usare per le immagini di pagini separate in lilypond-book.

show-available-fonts

bool Se bool è #t, elenca i nomi di font disponibili così come li consegna la libreria fontconfig. In fondo a questo elenco LilyPond mostra le impostazioni di configurazione di fontconfig. Predefinito: #f.

strip-output-dir

bool Se bool è #t, non usa le directory dei percorsi dei file di input per costruire i nomi dei file di output. Predefinito: #t.

strokeadjust

bool Se bool è #t, forza l’aggiustamento del tratto da parte di PostScript. Questa opzione è utile quando il PDF è generato dall’output PostScript (l’aggiustamento del tratto di solito è abilitato automaticamente per gli strumenti bitmap a bassa risoluzione). Senza questa opzione, i lettori PDF tendono a produrre larghezze dei gambi molto variabili alle risoluzioni tipiche dei monitor. Tuttavia l’opzione non produce effetti visibili sulla qualità di stampa e causa un notevole aumento della dimensione dei file PDF. Predefinito: #f.

svg-woff

bool Questa opzione è richiesta se si usano i file del formato per font Web Open Font Format (WOFF) col backend svg. Se bool è #t, viene creato un singolo file SVG per ogni pagina di output. Eccetto i glifi musicali di LilyPond, nessun altro tipo di carattere verrà incorporato nel file. Dunque qualsiasi lettore SVG dovrà avere accesso ai tipi di carattere per rendere in modo adeguato il testo. Si raccomanda di non usare gli “alias” o le “liste” dei tipi di carattere se il lettore SVG non è in grado di gestirli. Predefinito: #f.

tall-page-formats simbolo

Elenco separato da virgola di formati (svg, pdf, png o eps) da usare per l’immagine ‘tall page’ (pagina alta) in lilypond-book.

use-paper-size-for-page bool

Se bool è #t (predefinito), ogni pagina è impostata sulla dimensione del foglio, forse tagliando le parti che vanno oltre il foglio. Impostandolo su #f la pagina verrà ridimensionata per racchiudere il contenuto a seconda delle necessità.

verbose

Livello di verbosità. Questa è un’opzione di sola lettura; la sua impostazione non ha effetto.

warning-as-error

bool Se bool è #t, trasforma tutti i messaggi di avviso e di “errore di programmazione” in errori. Predefinito: #f.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Opzioni avanzate della linea di comando per LilyPond ]	[ Su : Uso da linea di comando ]	[ Riposizionamento > ]

Variabili d’ambiente

lilypond riconosce le seguenti variabili d’ambiente:

LILYPOND_DATADIR: Specifica la directory predefinita in cui vengono cercati i messaggi della localizzazione e i file di dati, scavalcando le posizioni definite al momento della compilazione o quelle calcolate dinamicamente all’esecuzione (vedi Riposizionamento). Questa directory deve contenere sottodirectory chiamate ‘ly’, ‘ps’, ‘tex’, etc.
LILYPOND_LOCALEDIR: Specifica la directory dove si trovano file relativi alla localizzazione. Scavalca il valore derivato da LILYPOND_DATADIR.
LILYPOND_RELOCDIR: Specifica la directory dove si trovano i file di “riposizionamento” (relocation). Scavalca il valore derivato dalla posizione del binario lilypond.
LANG: La lingua per i dati LilyPond inviati a stdout e stderr, per esempio relazioni sullo stato di avanzamento, messaggi di avviso o informazioni di debug. Esempio: LANG=de.
LILYPOND_LOGLEVEL: Il livello di log (loglevel) predefinito. Se LilyPond viene chiamato senza un livello di log esplicito (ovvero senza l’opzione ‘--loglevel’ della linea di comando), viene usato questo valore.
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.
TMPDIR: Specifica la directory temporanea in GNU/Linux e Mac. Quella predefinita è ‘/tmp’. È la directory in cui vengono salvati i file intermedi (come i file PostScript) durante la compilazione. Sovrascrivere questa variabile può essere utile, per esempio, se l’utente che esegue lilypond non ha permesso di scrittura alla directory temporanea predefinita. Esempio: TMPDIR=~/foo.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Variabili d'ambiente ]	[ Su : Uso da linea di comando ]	[ File di riposizionamento > ]

Riposizionamento

La maggior parte dei programmi del mondo Unix usa directory predefinite per i dati determinati al momento della configurazione che precede la compilazione. LilyPond non fa eccezione. Per esempio, un’installazione tipica mette il binario ‘lilypond’ in ‘/usr/bin’ e tutti i file specifici di LilyPond in sottodirectory di ‘/usr/share/lilypond/2.21.0/’ (assumendo che la versione corrente sia 2.21.0).

Questo approccio, sebbene funzioni bene in caso di compilazione manuale e di piattaforme che dispongono di gestori di pacchetti standardizzati, può causare problemi laddove tali gestori di pacchetti non siano abituali o non siano attivi per impostazione predefinita. Esempi tipici di tali piattaforme sono Windows e MacOS, i cui utenti si aspettano che le applicazioni bundle possano essere installate ovunque.

L’abituale soluzione a questo problema è il supporto per il riposizionamento (in inglese relocation): invece di usare percorsi prestabiliti ai file di dati, le posizioni dei necessari file di supporto vengono calcolate al momento dell’esecuzione (runtime) del programma in modo relativo al binario eseguito.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Riposizionamento ]	[ Su : Riposizionamento ]	[ Algoritmo di riposizionamento > ]

File di riposizionamento

Esiste in realtà un secondo meccanismo per la configurazione runtime: LilyPond fa ampio ricorso a programmi e librerie esterne, in particolare le librerie ‘FontConfig’ e ‘GUILE’ per trovare i font di sistema e gestire i file Scheme, e al programma gs per convertire i dati PS in file PDF. Tutti questi devono anche essere configurati per individuare i propri file di dati. Per far ciò, il programma lilypond analizza tutti i file presenti in una directory chiamata ‘relocate’ (se esiste; vedi sotto dove si cerca questa directory) per manipolare le variabili d’ambiente, che a loro volta controllano queste librerie e programmi esterni. Il formato di tali file di riposizionamento è semplice; ogni riga ha la sintassi

comando chiave=valore

e le righe vuote vengono ignorate.

La direttiva comando è una delle seguenti.

set: Imposta incondizionatamente la variabile d’ambiente chiave su valore. Sovrascrive un valore impostato precedentemente.
set?: Imposta la variabile d’ambiente chiave su valore solo se chiave non è ancora stata definita. In altre parole, non sovrascrive un valore impostato precedentemente.
setdir: Se valore è una directory, imposta incondizionaramente la variabile d’ambiente chiave su valore. Altrimenti, emette un avviso.
setfile: Se valore è un file, imposta incondizionaramente la variabile d’ambiente chiave su valore. Altrimenti, emette un avviso.
prependdir: Antepone il valore della directory all’elenco delle directory della variabile d’ambiente chiave. Se chiave non esiste viene creata.

Le variabili d’ambiente (precedute dal segno del dollaro) sono permesse dentro il valore e vengono espanse prima che la direttiva sia eseguita.

Ecco due esempi di comandi di riposizionamento dei file.

set? FONTCONFIG_FILE=$INSTALLER_PREFIX/etc/fonts/fonts.conf
prependdir GUILE_LOAD_PATH=$INSTALLER_PREFIX/share/guile/1.8

Nei file di riposizionamento si dovrebbe evitare di inserire molteplici righe che impostano la stessa variabile d’ambiente, perché l’ordine di analisi dei file nella directory ‘relocate’ è arbitrario.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < File di riposizionamento ]	[ Su : Riposizionamento ]	[ LilyPond in una gabbia chroot > ]

Algoritmo di riposizionamento

LilyPond usa il seguente algoritmo per trovare i suoi file di dati.

Calcola la directory in cui si trova il binaio lilypond attualmente eseguito. Chiamiamola bindir. Imposta la variabile d’ambiente (interna) INSTALLER_PREFIX su ‘bindir/..’ (ovvero la directory genitore di bindir).
Controlla la variabile d’ambiente LILYPOND_DATADIR. Se impostata, usa il suo valore per la directory dei dati di LilyPond, datadir. Altrimenti usa ‘$INSTALLER_PREFIX/share/lilypond/versione’ (dove versione è la versione corrente di LilyPond) o ‘$INSTALLER_PREFIX/share/lilypond/current’.
Controlla la variabile d’ambiente LILYPOND_LOCALEDIR. Se impostata, usa il suo valore per la directory dei dati di localizzazione di LilyPond, localedir. Altrimenti usa ‘$INSTALLER_PREFIX/share/locale’.
Controlla la variabile d’ambiente LILYPOND_RELOCDIR. Se impostata, usa il suo valore per la directory di riposizionamento dei file di LilyPond, relocdir. Altrimenti usa ‘$INSTALLER_PREFIX/etc/relocate’.
Se datadir non esiste, usa un valore determinato al momento della compilazione. Idem per localedir (ma non per relocdir, dato che non ha senso averlo).
Se relocdir esiste, elabora tutti i file in questa directory come descritto in File di riposizionamento.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Algoritmo di riposizionamento ]	[ Su : Uso da linea di comando ]	[ Messaggi di errore > ]

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 GNU/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
## Impostazioni predefinite

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# Il prefisso (senza la barra iniziale!)
lilyprefix=usr/local
# La directory di sistema in cui è installato lilypond
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

# Ora la magica ricopiatura della libreria
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

# I file condivisi per Ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# I file condivisi per ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Ora, assumendo di avere test.ly in /mnt/lilyloop/lilyhome,
### si dovrebbe poter eseguire:
### Nota che /$lilyprefix/bin/lilypond è uno script, che imposta la variabile
### LD_LIBRARY_PATH - questo è cruciale
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

Note a piè di pagina

[1] Lo stato di GUILE non viene ripristinato dopo l’elaborazione di un file ‘.ly’: attenzione quindi a non cambiare alcun valore predefinito dall’interno di Scheme.

[ << Eseguire lilypond ]	[Inizio][Contenuti][Indice]	[ Aggiornare i file con convert-ly >> ]
[ < Algoritmo di riposizionamento ]	[ Su : Uso da linea di comando ]	[ Messaggi di errore > ]

<< Torna all'indice della documentazione

LilyPond — Utilizzo v2.24.4 (ramo stabile).