Options basiques de lilypond

Gardez bien à l’esprit que lorsque l’argument à une option contient des espaces, il doit être encadré par des guillemets. Par exemple, pour écrire la sortie de LilyPond dans un répertoire ‘foo bar’, il faudra ajouter -o "foo bar" (ou --output="foo bar") aux arguments de lilypond en ligne de commande. Ces guillemets informatiques encadrant des arguments sont reconnus par pratiquement tous les interpréteurs en ligne de commande, que ce soit sur Windows ou les différents type d’Unix (y compris macOS).

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.

-E, --eps

Génère des fichiers EPS.

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

-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

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 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 !


GNU LilyPond – Utilisation des programmes v2.25.20 (branche de développement).