GNU LilyPond – Utilisation des programmes: 1.2 Utilisation en ligne de commande

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Utilisation habituelle ]	[Plus haut: Exécution de lilypond ]	[ Lancement de LilyPond > ]

1.2 Utilisation en ligne de commande

Nous nous intéresserons ici aux spécificités de LilyPond employé en ligne de commande. La ligne de commande permet de faire appel à certaines options particulières. D’autre part, certains utilitaires associés, tel que midi2ly, ne sont disponibles qu’en ligne de commande.

Par « ligne de commande », nous entendons l’interface de commande du système. Les utilisateurs de Windows seront certainement plus familiers des termes « fenêtre DOS » ou « invite de commande ». Quant aux utilisateurs de MacOS X, ils connaissent assurément les termes « console » et « terminal ».

Notre propos n’est pas ici d’expliquer ce qu’est l’interface de commande pour un système informatique ni comment elle fonctionne. Aussi, si vous ne savez de quoi il retourne, nous vous renvoyons aux nombreuses documentations que vous pourrez trouver sur ce sujet.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Utilisation en ligne de commande ]	[Plus haut: Utilisation en ligne de commande ]	[ > ]

Lancement de LilyPond

L’exécutable lilypond en ligne de commande se lance ainsi :

lilypond [option]… fichier…

Lorsque le fichier est fourni sans extension, LilyPond présume qu’il s’agit de ‘.ly’. Pour interpréter directement l’entrée standard (stdin), fournissez un tiret (-) en lieu et place de fichier.

Note : En ce qui concerne les versions de Windows antérieures à Windows 10 1903, LilyPond est incapable de gérer les noms de fichier Unicode.

Le traitement de ‘monfichier.ly’ produira ‘monfichier.pdf’ par défaut. Vous pouvez spécifier plusieurs fichiers à la fois ; ils seront traités indépendamment les uns des autres.¹

Lorsque ‘monfichier.ly’ contient plus d’une section \book, les fichiers produits – à partir du deuxième – seront numérotés. Par ailleurs, la valeur affectée à output-suffix sera insérée entre la racine et le numéro. Par exemple, un fichier racine qui contiendrait

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

fournira grâce à LilyPond ‘racine-violon.pdf’ et ‘racine-cello-1.pdf’.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Lancement de LilyPond ]	[Plus haut: Lancement de LilyPond ]	[ Options basiques de lilypond > ]

Utilisation de LilyPond avec les fonctionnalités standard de l’interpréteur

Dans la mesure où LilyPond est une application qui fonctionne en ligne de commande, les fonctionnalités de l’interpréteur utilisé pour lancer LilyPond peuvent se révéler utiles.

Par exemple,

lilypond *.ly

traite tous les fichiers LilyPond présents dans le répertoire en cours.

Rediriger, par exemple dans un fichier, ce qui est émis à l’écran peut s’avérer utile.

lilypond fichier.ly 1> stdout.log
lilypond fichier.ly 2> stderr.log
lilypond fichier.ly &> tous.log

Les commandes ci-dessus redirigeront respectivement le « verbiage normal », les erreurs ou tout, dans un fichier texte.

Consultez avant tout la documentation de votre interpréteur habituel – terminal, console, etc. – pour vérifier qu’il prend en charge les options dans cette syntaxe.

Voici comment traiter un jeu de fichiers répartis dans un répertoire donné ainsi que tous ses différents sous-répertoires. Les fichiers résultants sont regroupés dans le répertoire à partir duquel la commande a été exécutée, non selon l’emplacement des fichiers sources.

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

Cette commande, bien qu’effective uniquement dans un terminal, devrait être fonctionnelle aussi pour les utilisateurs de MacOS X.

Les utilisateurs de windows utiliseront l’instruction

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

dans l’interpréteur de commandes, qui se trouve normalement sous Démarrer > Accessoires > Interpréteur de commandes ou, pour la version 8, en faisant une recherche sur « interpréteur de commande ».

Par ailleurs, il est possible de spécifier de manière explicite le chemin d’accès au dossier comportant des sous-répertoires où se trouvent les fichiers sources, à l’aide de l’option /p :

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

Dans le cas où ce chemin d’accès comporte des espaces, l’intégralité de ce chemin devra être borné par des guillemets informatiques :

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

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < ]	[Plus haut: Utilisation en ligne de commande ]	[ Options avancées de lilypond > ]

Options basiques de `lilypond`

Différentes options sont disponibles en ligne de commande :

-d, --define-default=var[=val]

Voir Options avancées de lilypond.

-e, --evaluate=expr

Évalue l’expression Scheme expr avant d’analyser tout fichier ‘.ly’. Lorsque vous spécifiez l’option ‘-e’ à plusieurs reprises, l’évaluation est faite en séquence.

Dans la mesure où l’expression est évaluée par le module guile-user, vous devez, dès lors que expr utilise des définitions telles que (define-public a 42), spécifier

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

en ligne de commande, et ajouter la ligne

#(use-modules (guile-user))

en tête de votre fichier ‘.ly’.

Note : Les utilisateurs de Windows doivent utiliser des guillemets doubles " en lieu et place des guillemets simples '.

-E, --eps

Génère des fichiers EPS.

Cette option est équivalente à -dseparate-page-formats=ps.

-f, --format=format

Détermine le format à produire. Il peut s’agir de ps, pdf, png ou svg.

Exemple : lilypond -fpng monfichier.ly

SVG utilisant en interne un moteur spécifique, il ne peut donc s’obtenir de la même manière que les autres formats ; l’utilisation de -fsvg ou --svg revient en fait à utiliser l’option -dbackend=svg – voir Options avancées de lilypond.

-h, --help

Affiche un résumé des commandes.

-H, --header=CHAMP

Recopie le champ d’entête dans le fichier ‘RACINE.CHAMP’.

Par exemple, si un fichier ‘toto.ly’ contient

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

La commande

lilypond -H title toto.ly

produit un fichier texte plat ‘toto.title’ contenant la chaîne tutu.

-i, --init=fichier

Définit fichier (par défaut ‘init.ly’) en tant que fichier d’initialisation.

-I, --include=répertoire

Ajoute répertoire, de façon relative, au chemin de recherche pour les inclusions. Par défaut, seul le répertoire courant est consulté.

Vous pouvez mentionner plusieurs fois l’option ‘-I’, auquel cas la recherche commencera dans le premier répertoire inclus et, si le fichier en question ne s’y trouve pas, les répertoires suivants seront examinés l’un après l’autre.

Note : L’utilisation du tilde (~) avec l’option ‘-I’ peut produire des résultats inattendus selon le shell.

Les utilisateurs de Windows doivent ajouter une oblique (/ finale au chemin d’accès.

-j, --jail=user,group,jail,dir

[Cette option n’est disponible que dès lors que l’environnement dispose de la fontionnalité chroot. Windows, plus particulièrement, ne le prend pas en charge.] Lance lilypond dans un environnement protégé.

L’option ‘--jail’ peut s’utiliser pour des raisons de sécurité lorsque LilyPond est installé sur un serveur web ou traite des fichiers externes – voir Options avancées de lilypond. Dans la mesure où LilyPond procure de quoi faire tourner des programmes Guile, il est primordial, en pareil cas, que ce soit dans un environnement contraint de telle sorte que les fichiers alors compilés ne mettent pas en péril l’intégrité du système comme, par exemple, avec un

% trop dangereux à écrire sans faute
#(s yste m "rm -rf /")
% malveillant mais pas destructeur
{ c4^$(ly:gulp-file "/etc/passwd") }

L’option ‘--jail’ permet d’obtenir une telle incarcération. Un autre moyen consiste à utiliser LilyPond dans un conteneur Docker.

L’option ‘--jail’ va détourner la racine de lilypond sur jail juste avant d’effectuer la compilation à proprement parler. L’utilisateur et le groupe sont modifiés en conséquence, et le répertoire en cours devient dir. Ces réglages assurent – du moins en théorie – l’impossibilité de s’échapper de la cellule. Notez cependant que, pour que l’option ‘--jail’ soit fonctionnelle, lilypond doit être lancé en tant qu’administrateur – ce qui se réalise aisément à l’aide de la commande sudo.

La création d’un environnement sécurisé requiert quelques précautions dans la mesure où LilyPond doit disposer de tout ce dont il a besoin pour compiler le fichier source à l’intérieur de la cellule. L’ermitage, avant d’être viable, requiert donc les étapes suivantes :

Création d’un système de fichiers indépendant

L’intérêt d’un système de fichiers dédié à LilyPond réside dans le fait qu’on peut le brider à l’aide des options noexec, nodev et nosuid. Il sera de fait impossible de lancer des exécutables ou d’écrire sur un périphérique à partir de LilyPond. Si vous n’avez pas l’intention de créer un tel système sur une partition séparée, vous pouvez avoir recours à un pseudo-périphérique (loop device) monté à partir d’un simple fichier de taille raisonnable. D’autre part, le recours à un système de fichiers indépendant permet de limiter l’espace dévolu à LilyPond.

Création d’un utilisateur spécifique

L’utilisation de LilyPond au sein de la cellule devrait être réservé à un utilisateur aux droits restreints. Il faudra donc créer un utilisateur et un groupe spécifiques – disons lily/lily – qui n’aura accès en écriture qu’à un unique répertoire déterminé par la valeur de dir.

Agencement des lieux

LilyPond a besoin d’un certain nombre de fichiers pour pouvoir tourner correctement. Ces fichiers devront donc tous se retrouver dans l’environnement protégé, distribués selon la même arborescence que dans le système d’origine. Ainsi l’intégralité de l’installation de LilyPond (en principe ‘/usr/share/lilypond’) doit y être dupliquée.

En cas de problème, lancer LilyPond en utilisant strace vous permettra de déterminer quels fichiers manquent à l’appel.

Lancement de LilyPond

Dans un environnement protégé monté avec l’option noexec, il est impossible de lancer un quelconque programme extérieur. LilyPond ne saurait donc avoir recours à un moteur de traitement qui le mettrait dans cette situation. Comme nous l’avons vu plus haut, LilyPond sera lancé avec les privilèges de l’administrateur – privilèges qu’il perd aussitôt –, ce qui peut nécessiter le recours à la commande sudo. Il est par ailleurs judicieux de limiter le temps processeur alloué à LilyPond – grâce à ulimit -t par exemple – ainsi que, si votre système le permet, la taille de la mémoire. Voir aussi Exécution de LilyPond en mode protégé.

-l, --loglevel=degré

Règle le niveau de verbosité des messages console à degré. Les différentes valeurs sont :

NONE: Aucun verbiage, même pas les messages d’erreur.
ERROR: Uniquement les messages d’erreur ; pas de message d’avertissement ni de progression.
WARN: Messages d’avertissement ou d’erreur ; pas d’information de progression.
BASIC_PROGRESS: Information de progression basique (réussite) et avertissements ou erreurs.
PROGRESS: Toutes les informations de progression, avertissements et erreurs.
INFO: Informations de progression, avertissements et erreurs, ainsi que d’autres informations relatives à l’exécution. Ceci est la valeur par défaut.
DEBUG: Tout ce qui peut être affiché, y compris le verbiage utile au débogage.

-o, --output=FICHIER

-o, --output=RÉPERTOIRE

Détermine le nom par défaut du fichier résultant à FICHIER ; lorsque l’argument RÉPERTOIRE correspond à un répertoire déjà existant, c’est là que les fichiers résultants seront déposés. Le suffixe adéquat sera ajouté (par ex. ‘.pdf’ pour du PDF) dans tous les cas.

-O, --pspdfopt=clé

Détermine l’optimisation des PS/PDF résultants à clé. Les valeurs possibles sont :

size

Génère un un document PS, EPS ou PDF le plus léger possible. Il s’agit de la valeur par défaut.

L’utilisation de cette valeur revient à lancer les commandes Scheme de LilyPond -dmusic-font-encodings='#f' et -dgs-never-embed-fonts='#f'.

TeX

Produit des fichiers optimisés pour leur inclusion dans des documents pdfTeX, LuaTeX ou XeTeX.

L’utilisation de cette valeur revient à lancer les commandes Scheme de LilyPond -dmusic-font-encodings='#t' et -dgs-never-embed-fonts='#f'.

TeX-GS

L’inclusion de plusieurs PDF générés par LilyPond dans un document TeX nécessite l’utilisation de cette option et un retraitement du PDF généré par TeX à l’aide de Ghostscript.

L’utilisation de cette valeur revient à lancer les commandes Scheme de LilyPond -dmusic-font-encodings='#t' et -dgs-never-embed-fonts='#t'.

--ps

Génère du PostScript. Cette option est équivalente à -fps.

--png

Génère une image par page, au format PNG. Cette option est équivalente à -fpng.

La résolution de l’image peut se régler à N DPI en ajoutant

-dresolution=N

--pdf

Génère du PDF. Ceci est la valeur par défaut, et est équivalant à -fpdf.

-s, --silent

N’affiche rien de plus que les messages d’erreur. Ceci est équivalent à -lERROR.

--svg

Génère un fichier SVG par page. Cette option est équivalente à -fsvg.

-v, --version

Affiche le numéro de version.

-V, --verbose

Active le mode verbeux : affichage de l’intégralité du chemin d’accès de chaque fichier, et information des temps de traitement. Ceci est équivalent à -lDEBUG.

-w, --warranty

Affiche les informations de garantie applicables à GNU LilyPond – il est livré SANS GARANTIE !

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Options basiques de lilypond ]	[Plus haut: Utilisation en ligne de commande ]	[ Variables d'environnement > ]

Options avancées de `lilypond`

L’option ‘-d’ est l’interface de la ligne de commande à la fonction Scheme de LilyPond ly:set-option. Par voie de conséquence, toutes les options listées ci-après peuvent aussi se définir au sein même des fichiers ‘.ly’.

-d, --define-default=nom-option[=valeur]

-d, --define-default=no-nom-option

Affecte la valeur Scheme valeur à l’option interne nom-option du programme. Par exemple, l’option en ligne de commande

-dbackend=svg

équivaut à

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

dans un fichier source LilyPond.

En l’absence de valeur, le programme utilisera #t, ce qui peut conduire à des résultats inescomptés dès lors que le type escompté de valeur n’est pas boléen. Préfixer nom-option d’un no- permet de désactiver une option, autrement dit affecte #f à valeur. Ainsi,

-dno-point-and-click

revient au même que

-dpoint-and-click='#f'

[Note : le caractère ‘#’ introduit un commentaire dans de nombreux shells ; c’est pourquoi nous recommandons de toujours borner par des ' les expressions qui le contiennent.]

Voici les différentes options disponibles, ainsi que leur valeur par défaut. Au sein de code Scheme, la valeur des options est interprétée par la fonction ly:get-option.

anti-alias-factor num

Adopte une résolution supérieure, selon le facteur num donné (entier positif inférieur ou égal à 8), puis réduit au niveau du résultat afin d’éviter les « distorsions » des images PNG. La valeur par défaut est de 1.

aux-files bool

Si bool est fixé à #t, génère les fichiers .tex, .texi et .count pour le moteur de rendu eps. Cette option est principalement destinée à lilypond-book. La valeur par défaut est #t.

backend symbole

Détermine symbole comme moteur de traitement de LilyPond. Les valeurs possibles sont :

ps

Il s’agit du réglage par défaut. Les fichiers PostScript incluent les fontes TTF, Type1 et OTF, et ce en intégralité. Si vous utilisez des jeux de caractères orientaux, le fichier aura vite fait d’atteindre une taille conséquente.

Pour l’obtention d’un fichier PDF, c’est aussi le moteur ps qui est utilisé. Les données PS sont ensuite retraitées par ps2pdf, script de Ghostscript, qui par défaut extrait des sous-ensembles des fontes.

svg

Génère du Scalable Vector Graphics. Cette option permet de créer un fichier SVG par page. Les glyphes musicaux sont codés en tant que graphiques vectoriels mais les fontes textuelles ne sont pas incorporées aux fichiers ‘SVG’ résultants. Quel que soit le programme utilisé pour visionner ces fichiers, il devra avoir accès aux fontes en question pour pouvoir afficher correctement les textes et paroles. Il est préférable de ne pas recourir aux « alias de police » ni aux listes de fontes si la visionneuse de fichier SVG ne peut le traîter correctement. L’option supplémentaire --svg-woff – voir ci-après – permet d’utiliser les fontes WOFF (Web Open Font Format) avec le moteur svg.

clip-systems bool

Si bool est déterminé à #t, extrait des fragments musicaux d’une partition. Ceci requiert que la fonction clip-regions a été définie au sein du bloc \layout – voir Extraction de fragments musicaux. Bien entendu, aucun fragment ne sera extrait si l’on utilise l’option ‘-dno-print-pages’. La valeur par défaut est #f.

compile-scheme-code bool

Utilise le compilateur de Guile pour traiter du code Scheme, au lieu de l’évaluateur. Pour de plus amples informations, voir Débogage de code Scheme.

crop bool

Si bool est déterminé à #t, un second fichier PDF sera créé (avec l’extension ‘.cropped.pdf’) ainsi que son rendu sous forme d’image (avec l’extension ‘.cropped.png’). Ce fichier résultant (musique et entêtes) sera à la taille de l’image générée, sans marge. Dans le cas où est utilisée l’option ‘--svg’ sera alors produit un fichier SVG (avec l’extension ‘.cropped.svg’). Dès lors que sont utilisées les options ‘--eps’ ou ‘--ps’, un fichier réduit PS (avec l’extension ‘.cropped.eps’) sera généré en lieu et place d’un PDF réduit. La valeur par défaut est #f.

Notez bien que cette option n’est, à ce jour, pas très adaptée dans le cadre d’une sortie comportant plusieurs systèmes puisque l’espace les séparant est supprimé.

datadir

Détermine le préfixe des fichiers de données (lecture seule).

debug-eval bool

Si bool est déterminé à #t, LilyPond utilisera le l’évaluateur de déboguage Scheme qui affichera les traçage et les numéros de ligne en cas d’erreur. La valeur par défaut est #f, mais #t lorsque --verbose est utilisé.

debug-skylines bool

Si bool est déterminé à #t, permet le débogage des lignes d’horizon. La valeur par défaut est #f.

delete-intermediate-files bool

Si bool est déterminé à #t, supprime les fichiers ‘.ps’ inutiles créés lors de la compilation. La valeur par défaut est #t.

embed-source-code bool

Si bool est déterminé à #t, intègre les fichiers source LilyPond au document PDF généré. La valeur par défaut est #f.

eps-box-padding num

Décale le bord gauche du typon EPS d’une valeur num donnée en millimètres. La valeur par défaut est #f, autrement dit sans décalage.

font-export-dir chaîne

Détermine à chaîne le répertoire dans lequel exporter les fontes en tant que fichiers PostScript. Ceci est tout à fait approprié lorsque l’on crée un fichier PDF sans y incorporer les fontes dans un premier temps, et laisse Ghostscript le faire par la suite comme indiqué ci-dessous.

$ 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

Note : Contrairement à font-ps-resdir, cette méthode ne permet pas d’incorporer de fonte CID avec une version de Ghostscript égale ou supérieure à 9.26.

Note : Identique à font-ps-resdir, cette option ignore les fontes TrueType dans la mesure où les incorporer a posteriori cause une altération des caractères. L’utilisation de gs-never-embed-fonts, dans la mesure où elle incorpore les fontes TrueType en dépit de ce qu’elle prétend d’après son nom, permet d’éviter les caractères altérés.

La valeur par défaut est #f, autrement dit absence d’export.

font-ps-resdir chaîne

Détermine à chaîne le répertoire dans lequel sera construit le sous-ensemble des ressources PostScript utilisé pour l’incoporation ultérieure des fontes. Ceci est tout à fait approprié lorsque l’on crée un fichier PDF sans y incorporer les fontes dans un premier temps, et laisse Ghostscript le faire par la suite comme indiqué ci-dessous.

$ 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

Note : Il vaut mieux éviter que le nom du répertoire contienne le mot ‘Resource’, qui a une signification particulière lorsqu’utilisé avec une option -I de Ghostscript.

Note : Contrairement à font-export-dir, cette méthode permet l’incorporation de fontes CID avec une version de Ghostscript égale ou supérieure à 9.26.

Note : Identique à font-export-dir, cette option ignore les fontes TrueType dans la mesure où les incorporer a posteriori cause une altération des caractères. L’utilisation de gs-never-embed-fonts, dans la mesure où elle incorpore les fontes TrueType en dépit de ce qu’elle prétend d’après son nom, permet d’éviter les caractères altérés.

La valeur par défaut est #f, autrement dit absence de construction d’un sous-ensemble.

gs-load-fonts bool

Si bool est déterminé à #t, charge les fontes grâce à Ghostscript. Cette option a pour conséquence que les fichiers générés par LilyPond ne contiendront que les références des fontes, qui seront ensuite résolues en fontes réelles lors de l’étape de retraitement par Ghostscript. La valeur par défaut est #f.

gs-load-lily-fonts bool

Si bool est déterminé à #t, limite les fontes chargées par Ghostscript aux seules fontes LilyPond. Cette option a pour conséquence que les fichiers générés par LilyPond ne contiendront les références que des fontes musicales de LilyPond, qui seront ensuite résolues en fontes réelles lors de l’étape de retraitement par Ghostscript. Les autres fontes sont générées normalement. La valeur par défaut est #f.

gs-never-embed-fonts bool

Si bool est déterminé à #t, intime à Ghostscript d’embarquer les fontes uniquement au format TrueType, sans exception. La valeur par défaut est #f.

help bool

Si bool est déterminé à #t, affiche cette aide. La valeur par défaut est #f.

include-book-title-preview bool

Si bool est déterminé à #t, inclut les titres de l’ouvrage dans les images de prévisualisation. La valeur par défaut est #t.

include-eps-fonts bool

Si bool est déterminé à #t, inclut les fontes dans chaque fichier EPS contenant un système. La valeur par défaut est #t.

include-settings chaîne

Inclut le fichier chaîne contenant les réglages globaux, qui sera inclus avant traitement de la partition. La valeur par défaut est #f, autrement dit absence de fichier de réglages.

job-count num

Traite plusieurs fichiers en parallèle, selon le nombre num de jobs. La valeur par défaut est #f, autrement dit sans traitement parallèle.

log-file chaîne

Redirige la sortie dans le fichier journal ‘chaîne.log’. La valeur par défaut est #f, autrement dit absence de fichier de journalisation.

max-markup-depth num

Détermine à num la profondeur maximale de l’arborescence de markups. Si un markup était plus profond, part du principe qu’on n’aboutira pas, émet un avertissement et renvoie alors un markup vide. La valeur par défaut est 1024.

midi-extension chaîne

Détermine à chaîne l’extension par défaut des fichiers MIDI.La valeur par défaut est "midi".

music-strings-to-paths bool

Si bool est déterminé à #t, convertit les chaînes textuelles en chemins lorsque les glyphes font partie d’une fonte musicale. La valeur par défaut est #f.

paper-size chaîne-entre-guillemets

Détermine la taille par défaut du papier à chaîne-entre-guillemets. Veillez à ne pas oublier d’encadrer la valeur par des guillemets échappés (\").La valeur par défaut est "\"a4\"".

pixmap-format symbole

Détermine le format de sortie en images pixélisées pour Ghostscript à symbole. La valeur par défaut est png16m.

png-width largeur

png-height hauteur

Dans le cas d’une sortie PNG, détermine la largeur et la hauteur, en pixels, des images créées. En l’absence de l’une de ces options, l’autre dimension sera calculée relativement à la boîte EPS englobante tout en maintenant le ration d’aspect.

En comlément de l’option ‘--png’, les options ‘--eps’, ‘-dcrop’ ou ‘-dpreview’ devraient permettre une mise à l’échelle correcte sans détourage.

L’option ‘-dresolution’ est ignorée.

Notez la présence d’un bogue dans les versions de ghostscript inférieures à 9.52 avec ces deux options : l’image PNG produite sera vide dès lors que la hauteur est supérieure à la largeur.

point-and-click bool

Si bool est déterminé à #t, ajoute les liens « point & click » à la sortie PDF ou SVG – voir Pointer-cliquer. La valeur par défaut est #t.

preview bool

Si bool est déterminé à #t, génère une prévisualisation en plus de la sortie normale. La valeur par défaut est #f.

Cette option, disponible dans tous les formats de sortie imprimables – rendus pdf, png, ps, eps et svg – génère un fichier de la forme ‘fichierSource.preview.rendu’ comprenant le titrage et le premier système. S’il existe plusieurs sections \book ou \bookpart, ce fichier contiendra les titrage et premier système de chacun des \book, \bookpart et \score, dès lors que la variable print-all-headers du bloc \paper est activée.

Pour l’éviter, utilisez conjointement l’une des options ‘-dprint-pages’ ou ‘-dno-print-pages’ selon vos besoins.

print-pages bool

Si bool est déterminé à #t, génère l’intégralité des pages de la partition. La valeur par défaut est #t.

L’option ‘-dno-print-pages’ est particulièrement utile lorsqu’utilisée conjointement avec les options ‘-dpreview’ et ‘-dcrop’.

protected-scheme-parsing bool

Si bool est déterminé à #t, continue en dépit des erreurs que l’analyseur syntaxique détecterait dans du code Scheme inclus. Lorsque basculé sur #f, stoppe le traitement s’il y a erreur et affiche une trace de la pile. La valeur par défaut est #t.

relative-includes bool

Face à une instruction \include, recherche les fichiers à inclure relativement à l’endroit où se trouve le fichier en cours de traitement si bool est déterminé à #t, plutôt que par rapport au fichier maître. La valeur par défaut est #t.

resolution num

Détermine la résolution des pixmaps PNG à générer à num dpi. La valeur par défaut est 101.

separate-log-files bool

Pour les fichiers ‘fichier1.ly’, ‘fichier2.ly’, etc. enregistre le déroulement dans les journaux ‘fichier1.log’, ‘fichier2.log’… si bool est déterminé à #t. La valeur par défaut est #f.

separate-page-formats symbole

Liste des formats (svg, pdf, png, ou eps), séparés par des virgules, à utiliser pour les images séparées des pages pour lilypond-book.

show-available-fonts bool

Si bool est déterminé à #t, liste le nom des fontes disponibles tel que le ressort la bibliothèque fontconfig. LilyPond ajoute à cette liste les réglages et la configuration de fontconfig. La valeur par défaut est #t.

strip-output-dir bool

Si bool est déterminé à #t, supprime, lors du nommage des fichiers résultants, la partie correspondant au répertoire des fichiers sources. La valeur par défaut est #t.

strokeadjust bool

Si bool est déterminé à #t, force l’ajustement des traits PostScript. Cette option trouve toute son utilité pour générer du PDF à partir de PostScript – l’ajustement des traits est en principe automatiquement activé pour les périphériques bitmap à faible résolution. Sans cette option, les visionneurs de PDF ont tendance à ne pas rendre de manière constante l’épaisseur des hampes dans les résolutions habituelles des écrans. Bien que n’affectant pas notoirement la qualité d’impression, cette option accroit notablement la taille des fichiers PDF. La valeur par défaut est #f.

svg-woff bool

Cette option est obligatoire dès lors que sont utilisées, avec le moteur svg, les fontes Web Open Font Format (WOFF). Un fichier SVG sera généré pour chacune des pages produites. En dehors des glyphes musicaux propres à LilyPond, aucune autre information ne sera incluse. Quelque soit le visionneur de SVG utilisé, il devra avoir à disposition les fontes requises pour pouvoir afficher les éléments textuels et les paroles. Dans la mesure où le visionneur pourrait ne pas savoir le gérer, mieux vaut s’abstenir de recourir aux alias ou listes de fontes. La valeur par défaut est #f.

Lorsque celles-ci sont utilisées correctement, nul n’est besoin d’installer les fontes que les fichiers SVG utiliseront dans l’environnement du visionneur. Néanmoins, LilyPond ne dispose pas de fichier de fonte woff textuelle. La présence du fichier de fonte woff est un prérequis.

tall-page-formats symbole

Liste des formats (svg, pdf, png, ou eps), séparés par des virgules, à utiliser pour l’image pleine page pour lilypond-book.

use-paper-size-for-page bool

Si bool est déterminé à #t (valeur par défaut), chaque page est dimensionnée au format du papier, tout en éliminant les parties qui pourraient déborder. Lorsque cette option est déterminée à #f, la feuille sera redimsensionnée pour contenir autant que nécessaire.

verbose

Passe en mode verbeux, ce qui correspond à un niveau de journalisation DEBUG (lecture seule).

warning-as-error bool

Si bool est déterminé à #t, considère tous les messages d’avertissement et « erreur de programmation » comme étant de véritables erreurs. La valeur par défaut est #f.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Options avancées de lilypond ]	[Plus haut: Utilisation en ligne de commande ]	[ Réadressage > ]

Variables d’environnement

lilypond reconnaît les variables d’environnement suivantes :

LILYPOND_DATADIR: Cette variable spécifie le répertoire où sont recherchés par défaut les différentes versions des messages ainsi qu’un certain nombre de fichiers nécessaires au traitement, dérogeant ainsi aux endroits définis soit lors de la compilation, soit calculés dynamiquement lors de l’exécution – voir Réadressage. Il devrait contenir les sous-répertoires ‘ly/’, ‘ps/’, ‘tex/’, etc.
LILYPOND_LOCALEDIR: Cette variable spécifie le répertoire où sont situés les fichiers liguistiques, dérogeant ainsi aux valeurs dérivées de LILYPOND_DATADIR.
LILYPOND_RELOCDIR: Cette variable spécifie le répertoire dans lequel résident les fichiers de réadressage. Ceci constitue une dérogation aux endroits définis à partir d’où réside le binaire lilypond.
LANG: Cette variable détermine la langue dans laquelle sont émises les données sur stdout (sortie standard) et stderr (sortie des erreurs), pour afficher la progession, les avertissements ou messages de débogage. Par exemple : LANG=de.
LILYPOND_LOGLEVEL: Cette variable détermine le niveau par défaut de verbosité. En l’absence de niveau explicite – autrement dit la ligne de commande ne comporte pas de ‘--loglevel’ – c’est cette valeur qui sera utilisée.
LILYPOND_GC_YIELD: Cette variable permet d’ajuster l’empreinte mémoire et le rendement de la machine. Il s’agit en fait d’un pourcentage d’allocation de mémoire : lorsqu’il est élevé, le programme favorisera l’utilisation de la mémoire ; une faible valeur consommera plus de temps processeur. Par défaut, cette valeur est fixée à 70.
TMPDIR: Cette variable permet de déterminer, sur GNU/Linux et Mac, le répertoire temporaire. La valeur par défaut est ‘/tmp’. Il s’agit du répertoire dans lequel seront enregitrés, durant la compilation, les fichiers intermédiaires tels que les fichiers PostScript. Apporter une dérogation à cette variable peut s’avérer utile lorsque, par exemple, l’utilisateur qui lance lilypond n’a pas les droits en écriture sur le répertoire temporaire par défaut. Exemple : TMPDIR=~/toto.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Variables d'environnement ]	[Plus haut: Utilisation en ligne de commande ]	[ Fichiers de réadressage > ]

Réadressage

La plupart des programmes dans le monde Unix utilise des répertoires par défaut pour leurs données, déterminés au moment de leur configuration avant même leur compilation. LilyPond n’y fait pas exception ; par exemple, une installation typique met le fichier binaire ‘lilypond’ dans le répertoire ‘/usr/bin’ et tous les fichiers propres à LilyPond dans des sous-répertoires de ‘/usr/share/lilypond/2.21.0/’ si tant est que la version en cours soit 2.21.0.

Alors que cette approche est tout à fait fonctionnelle dans le cadre d’une compilation manuelle et des plateformes disposant de gestionnaires de paquetages standardisés, elle peut entraîner des problèmes lorsque de tels gestionnaires ne sont pas courants ou pas utilisés par défaut – on peut citer à titre d’exemple Windows et MacOS pour lesquels les utilisateurs s’attendent à ce que l’installation des programmes se fasse n’importe où.

La solution habituelle en pareil cas est la prise en charge du réadressage : au lieu d’utiliser des chemins codés en dur pour les fichiers de données, la localisation des fichiers de support nécéssaires est calculée lors de l’exécution relativement au binaire lancé.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Réadressage ]	[Plus haut: Réadressage ]	[ Algorithme de réadressage > ]

Fichiers de réadressage

Un deuxième mécanisme intervient en fait pour la configuration de l’exécution : LilyPond dépend fortement de programme ou bibloithèques externes, en particulier les bibliothèques FontConfig et GUILE pour trouver respectivement les fontes du système et les traitement des fichiers Scheme, ainsi que le programme gs pour convertir les données PostScript en fichiers PDF. Tout ceci doit aussi être configuré pour retrouver ses propres fichiers de données. Pour y parvenir, le programme lilypond analyse tous les fichiers d’un répertoire dénommé ‘relocate’, s’il existe – voir ci-après les endroits où ce repertoire est recherché – afin de manipuler les variables d’environnement ce qui, en retour, contrôlera ces programmes et bibliothèques externes. Les format de ces fichiers de réadressage est simple, chaque ligne répondant à la syntaxe

commande clé=valeur

et les lignes vides y seront ignorées

La directive commande est l’une des suivantes :

set: Définit de manière inconditionnelle la variable d’environnement clé à valeur. Ceci écrase la valeur précédemment définie.
set?: Définit la variable d’environnement clé à valeur uniquement si clé n’est pas déjà définie. En d’autres termes, une valeur précédemment définie ne sera pas écrasée.
setdir: Lorsque valeur est un répertoire, définit inconditionnellement clé à valeur. Un message d’avertissement est émis dans le cas contraire.
setfile: Lorsque valeur est un fichier, définit inconditionnellement clé à valeur. Un message d’avertissement est émis dans le cas contraire.
prependdir: Ajoute le répertoire valeur à la liste des répertoires de la variable d’environnement clé. Dans le cas où clé n’existe pas, celle-ci sera créée.

Les variables d’environnement, identifiables au signe dollar qui les préfixe, sont permises en tant que valeur et seront expansées avant l’exécution de la directive.

Voici deux exemples d’entrée d’un fichier de réadresssage.

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

Dans la mesure où l’ordre d’analyse des fichiers du répertoire ‘relocate’ est arbitraire, mieux vaut s’abstenir de définir une même variable d’environnement à de multiples lignes des fichiers de réadressage.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Fichiers de réadressage ]	[Plus haut: Réadressage ]	[ Exécution de LilyPond en mode protégé > ]

Algorithme de réadressage

Afin de trouver ses fichiers de données, LilyPond utilise l’algorithme suivant.

Localisation du répertoire où se trouve le binaire lilypond actuellement exécuté et nommage en bindir. Détermination, en interne, de la variable d’environnement INSTALLER_PREFIX à ‘bindir/..’ – autrement dit le répertoire parent de bindir.
Contrôle de la variable d’environnement LILYPOND_DATADIR. Si elle est définie, utilisation de sa valeur pour le répertoire de données – datadir – de LilyPond. Dans le cas contraire, utilisation soit de ‘$INSTALLER_PREFIX/share/lilypond/version’ (avec version étant la version courante de LilyPond), soit ‘$INSTALLER_PREFIX/share/lilypond/current’.
Contrôle de la variable d’environement LILYPOND_LOCALEDIR. Si elle est définie, utilisation de sa valeur pour le répertoire de données linguistiques – localedir – de LilyPond. Dans le cas contraire, ce sera ‘$INSTALLER_PREFIX/share/locale’.
Contrôle de la variable d’environnement LILYPOND_RELOCDIR. Si elle existe, utilisation de sa valeur pour le répertoire des fichiers de réadressage – relocdir – de LilyPond. Dans le cas contraire, ce sera ‘$INSTALLER_PREFIX/etc/relocate’.
En l’absence de datadir, utilisation d’une valeur déterminée au fil de la compilation. Idem pour localedir, mais pas pour relocdir (cela n’a aucun sens de le faire).
Si relocdir existe, traiter tous les fichiers dans ce répertoire, comme indiqué dans Fichiers de réadressage.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Algorithme de réadressage ]	[Plus haut: Utilisation en ligne de commande ]	[ Messages d'erreur > ]

Exécution de LilyPond en mode protégé

Paramétrer un serveur afin qu’il puisse faire fonctionner LilyPond en mode protégé sur un pseudo-périphérique est une tâche sensible. Les différentes étapes à suivre sont répertoriées ci-dessous. Les exemples qu’elle comportent proviennent d’une distribution GNU/Linux Ubuntu et nécessiteront l’utilisation de sudo autant que de besoin.

Installation des paquetages nécessaires : LilyPond, Ghostscript et ImageMagick.
Création de l’utilisateur lily :
```
adduser lily
```
Ceci, par la même occasion, créera un groupe spécifique pour l’utilisateur lily ainsi que son répertoire personnel /home/lily.
Création, dans le répertoire personnel de l’utilisateur lily, d’un espace agissant en tant que système de fichiers :
```
dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
```
Cette commande a créé un fichier de 200 MB utilisable par le « système protégé ».

Création d’un pseudo-périphérique, génération d’un système de fichiers et chargement de celui-ci, puis création d’un répertoire accessible en écriture pour l’utilisateur 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

Affectation, au niveau configuration du serveur, de /mnt/lilyloop en tant que JAIL et /lilyhome en tant que DIR.

Création d’une arborescence, dans l’espace protégé, et recopie de tous les fichiers nécessaires – voir le script plus loin.

Le recours à l’utilitaire sed permet de créer les commandes de copie de tout ce qui est nécessaire à un exécutable donné :

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

Exemple de script fonctionnel en 32-bit sur Ubuntu 8.04

#!/bin/sh
## les réglages par défaut

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# le préfixe (sans slash au début !)
lilyprefix=usr/local
# le répertoire du système où lilypond est installé
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

# la formule magique de recopie des bibliothèques
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

# les fichiers partagés pour Ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# les fichiers partagés pour ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Partant du principe que test.ly est dans /mnt/lilyloop/lilyhome,
### on devrait pouvoir lancer :
### Attention : /$lilyprefix/bin/lilypond est un script qui
### définit LD_LIBRARY_PATH - c'est primordial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

Notes de bas de page

[1] Le statut de GUILE n’étant pas réinitialisé après traitement d’un fichier ‘.ly’, veillez à ne pas modifier les réglages par défaut du système à partir d’assertions en Scheme.

[ << Exécution de lilypond ]	[Racine][Table des matières][Index]	[ Mise à jour avec convert-ly >> ]
[ < Algorithme de réadressage ]	[Plus haut: Utilisation en ligne de commande ]	[ Messages d'erreur > ]

<< Retour à l'accueil de la documentation

LilyPond — Utilisation des programmes v2.24.4 (branche stable).