@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-

@ignore
   Translation of GIT committish: 2c13b5ef49e689c809888465e23f874b5c4f62d7

   When revising a translation, copy the HEAD committish of the
   version that you are working on.  For details, see the Contributors'
   Guide, node Updating translation committishes..
@end ignore

@c \version "2.17.6"

@c Translators: Jean-Charles Malahieude
@c Translation checkers:


@node Exécution de lilypond
@chapter Exécution de @command{lilypond}
@translationof Running lilypond

Ce chapitre passe en revue ce qui se passe lorsque vous lancez LilyPond.

@menu
* Utilisation habituelle::
* Utilisation en ligne de commande::
* Messages d'erreur::
* Quelques erreurs des plus courantes::
@end menu

@node Utilisation habituelle
@section Utilisation habituelle
@translationof Normal usage

La plupart des utilisateurs de LilyPond le font au travers d'une
interface graphique (@emph{GUI} pour @emph{graphical user interface}).
Si vous ne l'avez pas encore parcouru, lisez le @rlearning{Tutoriel}.
Si vous utilisez un éditeur alternatif pour rédiger vos fichiers
LilyPond, référez-vous à la documentation de celui-ci.


@node Utilisation en ligne de commande
@section Utilisation en ligne de commande
@translationof Command-line usage

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 @code{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.

@menu
* Lancement de LilyPond::
* Options basiques de lilypond::
* Options avancées de lilypond::
* Variables d'environnement::
* Réadressage::
* Exécution de LilyPond en mode protégé::
@end menu


@node Lancement de LilyPond
@unnumberedsubsec Lancement de LilyPond
@translationof Invoking LilyPond

L'exécutable @command{lilypond} en ligne de commande se lance ainsi :

@example
lilypond [@var{option}]@dots{} @var{fichier}@dots{}
@end example

Lorsque le fichier est fourni sans extension, LilyPond présume qu'il
s'agit de @file{.ly}.  Pour interpréter directement l'entrée standard
(@emph{stdin}), fournissez un tiret (@code{-}) en lieu et place de
@var{fichier}.

@warning{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 @file{monfichier.ly} produira @file{monfichier.pdf} par
défaut.  Vous pouvez spécifier plusieurs fichiers à la fois ; ils seront
traités indépendamment les uns des autres.@footnote{Le statut de GUILE
n'étant pas réinitialisé après traitement d'un fichier @file{.ly},
veillez à ne pas modifier les réglages par défaut du système à partir
d'assertions en Scheme.}

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

@example
#(define output-suffix "violon")
\score @{ @dots{} @}
#(define output-suffix "cello")
\score @{ @dots{} @}
@end example

@noindent
fournira grâce à LilyPond @file{racine-violon.pdf} et
@file{racine-cello-1.pdf}.


@unnumberedsubsubsec Utilisation de LilyPond avec les fonctionnalités standard de l'interpréteur
@translationof Using LilyPond with standard shell features

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,

@example
lilypond *.ly
@end example

@noindent
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.

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

@noindent
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.

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

@noindent
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

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

@noindent
dans l'@code{interpréteur de commandes}, qui se trouve normalement sous
@code{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 @code{/p} :

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

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 :

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


@node Options basiques de lilypond
@unnumberedsubsec Options basiques de @command{lilypond}
@translationof Basic command line options for LilyPond

@cindex lancement de @command{lilypond}
@cindex ligne de commande, options pour @command{lilypond}
@cindex options, ligne de commande
@cindex switches
@cindex commutateurs

Différentes options sont disponibles en ligne de commande :

@table @asis

@item @code{-d}, @code{--define-default=}@var{var}[@code{=}@var{val}]
Voir @ref{Options avancées de lilypond}.

@cindex Scheme, évaluation d'expression
@cindex expression Scheme, évaluation

@item @code{-e}, @code{--evaluate=}@var{expr}
Évalue l'expression Scheme @var{expr} avant d'analyser tout fichier
@file{.ly}.  Lorsque vous spécifiez l'option @option{-e} à plusieurs
reprises, l'évaluation est faite en séquence.

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

@example
lilypond -e '(define-public a 42)'
@end example

@noindent
en ligne de commande, et ajouter la ligne

@example
#(use-modules (guile-user))
@end example

@noindent
en tête de votre fichier @file{.ly}.

@warning{Les utilisateurs de Windows doivent utiliser des guillemets
doubles @code{"} en lieu et place des guillemets simples @code{'}.}
@c Match " in context-sensitive editors

@item @code{-E}, @code{--eps}
Génère des fichiers EPS.

Cette option est équivalente à @code{-dseparate-page-formats=ps}.

@cindex sortie, format
@cindex format de sortie
@item @code{-f}, @code{--format=}@var{format}
Détermine le format à produire.  Il peut s'agir de @code{ps},
@code{pdf}, @code{png} ou @code{svg}.

Exemple : @code{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
@w{@code{-fsvg}} ou @code{--svg} revient en fait à utiliser l'option
@code{-dbackend=svg} -- voir @ref{Options avancées de lilypond}.

@item @code{-h}, @code{--help}
Affiche un résumé des commandes.

@item @code{-H}, @code{--header=}@var{CHAMP}
Recopie le champ d'entête dans le fichier @file{RACINE.@var{CHAMP}}.

Par exemple, si un fichier @file{toto.ly} contient

@example
\header @{ title = "tutu" @}
\score @{ c1 @}
@end example

@noindent
La commande

@example
lilypond -H title toto.ly
@end example

@noindent
produit un fichier texte plat @file{toto.title} contenant la chaîne
@code{tutu}.

@item @code{-i}, @code{--init=}@var{fichier}
Définit @var{fichier} (par défaut @file{init.ly}) en tant que fichier
d'initialisation.

@cindex recherche de fichier
@cindex chemin de recherche
@cindex inclusion, chemin
@item @code{-I}, @code{--include=}@var{répertoire}
Ajoute @var{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 @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.

@warning{L'utilisation du tilde (@code{~}) avec l'option @option{-I}
peut produire des résultats inattendus selon le @emph{shell}.

Les utilisateurs de Windows doivent ajouter une oblique (@code{/}
finale au chemin d'accès.}

@cindex chroot jail, fonctionnement
@item @code{-j}, @code{--jail=}@var{user}@code{,}@var{group}@code{,}@var{jail}@code{,}@var{dir}
[Cette option n'est disponible que dès lors que l'environnement dispose
de la fontionnalité @code{chroot}. Windows, plus particulièrement, ne le
prend pas en charge.]
Lance @command{lilypond} dans un environnement protégé.

L'option @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 @ref{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

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

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

L'option @option{--jail} va détourner la racine de @command{lilypond}
sur @var{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 @var{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 @option{--jail} soit fonctionnelle,
@command{lilypond} doit être lancé en tant qu'administrateur -- ce qui
se réalise aisément à l'aide de la commande @command{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 @strong{à l'intérieur de la cellule}.
L'ermitage, avant d'être viable, requiert donc les étapes
suivantes :

@table @asis

@item 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 @code{noexec}, @code{nodev} et
@code{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 (@emph{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.

@item 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
@w{@code{lily}/@code{lily}} -- qui n'aura accès en écriture qu'à un
unique répertoire déterminé par la valeur de @var{dir}.

@item 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 @file{/usr/share/lilypond}) doit y être dupliquée.

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

@item Lancement de LilyPond
Dans un environnement protégé monté avec l'option @code{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
@code{sudo}.  Il est par ailleurs judicieux de limiter le temps
processeur alloué à LilyPond -- grâce à @command{ulimit -t} par
exemple -- ainsi que, si votre système le permet, la taille de la
mémoire.  Voir aussi @ref{Exécution de LilyPond en mode protégé}.
@end table

@cindex loglevel
@cindex verbosité, définir le degré de
@item @code{-l}, @code{--loglevel=}@var{degré}
Règle le niveau de verbosité des messages console à @var{degré}.  Les
différentes valeurs sont :

@table @code
@item NONE
Aucun verbiage, même pas les messages d'erreur.

@item ERROR
Uniquement les messages d'erreur ; pas de message d'avertissement
ni de progression.

@item WARN
Messages d'avertissement ou d'erreur ; pas d'information de
progression.

@item BASIC_PROGRESS
Information de progression basique (réussite) et avertissements ou
erreurs.

@item PROGRESS
Toutes les informations de progression, avertissements et erreurs.

@item INFO
Informations de progression, avertissements et erreurs, ainsi que
d'autres informations relatives à l'exécution. Ceci est la valeur par
défaut.

@item DEBUG
Tout ce qui peut être affiché, y compris le verbiage utile au débogage.

@end table

@cindex redirection
@cindex répertoire de destination
@cindex fichier de destination
@item @code{-o}, @code{--output=}@var{FICHIER}
@itemx @code{-o}, @code{--output=}@var{RÉPERTOIRE}
Détermine le nom par défaut du fichier résultant à @var{FICHIER} ;
lorsque l'argument @var{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. @file{.pdf} pour du PDF) dans tous
les cas.

@cindex pspdfopt
@item @code{-O}, @code{--pspdfopt=}@var{clé}
Détermine l'optimisation des PS/PDF résultants à @var{clé}. Les valeurs
possibles sont :

@table @code

@item 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 @code{-dmusic-@/font-@/encodings=@/'#f'} et
@code{-dgs-@/never-@/embed-@/fonts=@/'#f'}.

@item TeX
Produit des fichiers optimisés pour leur inclusion dans des documents
pdf@TeX{}, Lua@TeX{} ou Xe@TeX{}.

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

@item 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 @code{-dmusic-@/font-@/encodings=@/'#t'} et
@code{-dgs-@/never-@/embed-@/fonts=@/'#t'}.

@end table

@cindex PostScript, output
@cindex PS (PostScript), output
@item @code{--ps}
Génère du PostScript. Cette option est équivalente à @code{-fps}.

@cindex Portable Network Graphics (PNG), output
@cindex PNG (Portable Network Graphics), output
@item @code{--png}
Génère une image par page, au format PNG. Cette option est équivalente à
@w{@code{-fpng}}.

La résolution de l'image peut se régler à @var{N}@tie{}DPI en ajoutant
@example
-dresolution=@var{N}
@end example

@cindex Portable Document Format (PDF), output
@cindex PDF (Portable Document Format), output
@item @code{--pdf}
Génère du PDF.  Ceci est la valeur par défaut, et est équivalant à
@w{@code{-fpdf}}.

@item @code{-s}, @code{--silent}
N'affiche rien de plus que les messages d'erreur. Ceci est équivalent à
@code{-lERROR}.

@cindex SVG (Scalable Vector Graphics), sortie
@cindex sortie, SVG (Scalable Vector Graphics)
@cindex HTML, partitions SVG empaquetables
@cindex pages internet, partitions SVG empaquetables

@item @code{--svg}
Génère un fichier SVG par page.  Cette option est équivalente à
@w{@code{-fsvg}}.

@item @code{-v}, @code{--version}
Affiche le numéro de version.

@item @code{-V}, @code{--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 à @code{-lDEBUG}.

@item @code{-w}, @code{--warranty}
Affiche les informations de garantie applicables à GNU LilyPond -- il
est livré @strong{SANS GARANTIE} !

@end table


@node Options avancées de lilypond
@unnumberedsubsec Options avancées de @command{lilypond}
@translationof Advanced command line options for LilyPond

L'option @option{-d} est l'interface de la ligne de commande à la
fonction Scheme de LilyPond @code{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 @file{.ly}.

@table @asis

@item @code{-d}, @code{--define-default=}@var{nom-option}[@code{=}@var{valeur}]
@itemx @code{-d}, @code{--define-default=no-}@var{nom-option}
Affecte la valeur Scheme @var{valeur} à l'option interne
@var{nom-option} du programme. Par exemple, l'option en ligne de commande

@example
-dbackend=svg
@end example

@noindent
équivaut à

@example
#(ly:set-option 'backend 'svg)
@end example

@noindent
dans un fichier source LilyPond.

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

@cindex point and click, ligne de commande
@cindex pointer-cliquer, ligne de commande

@example
-dno-point-and-click
@end example

@noindent
revient au même que
@example
-dpoint-and-click='#f'
@end example
@end table

[Note : le caractère @samp{#} introduit un commentaire dans de nombreux
@emph{shells} ; c'est pourquoi nous recommandons de toujours borner par
des @code{'} 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 @code{ly:get-option}.

@table @asis

@item @code{anti-alias-factor} @var{num}
Adopte une résolution supérieure, selon le facteur @var{num} donné
(entier positif inférieur ou égal à 8), puis réduit au niveau du
résultat afin d'éviter les « distorsions » des images @code{PNG}. La
valeur par défaut est de @code{1}.

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

@item @code{backend} @var{symbole}
Détermine @var{symbole} comme moteur de traitement de LilyPond. Les
valeurs possibles sont :

@table @code

@item ps
Il s'agit du réglage par défaut. Les fichiers PostScript incluent les
fontes @code{TTF}, @code{Type1} et @code{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 @code{ps} qui
est utilisé. Les données PS sont ensuite retraitées par @code{ps2pdf},
script de Ghostscript, qui par défaut extrait des sous-ensembles des
fontes.

@item svg
Génère du @emph{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 @b{ne sont pas}
incorporées aux fichiers @file{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 @w{@code{--svg-woff}} --
voir ci-après -- permet d'utiliser les fontes WOFF (@emph{Web Open Font
Format}) avec le moteur @code{svg}.

@end table

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

@item @code{compile-scheme-code} @var{bool}
Utilise le compilateur de Guile pour traiter du code Scheme, au lieu de
l'évaluateur. Pour de plus amples informations, voir
@rextend{Débogage de code Scheme}.

@item @code{crop} @var{bool}
Si @var{bool} est déterminé à @code{#t}, un second fichier PDF sera créé
(avec l'extension @file{.cropped.pdf}) ainsi que son rendu sous forme
d'image (avec l'extension @file{.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 @option{--svg} sera alors produit
un fichier SVG (avec l'extension @file{.cropped.svg}). Dès lors que sont
utilisées les options @option{--eps} ou @option{--ps}, un fichier réduit
PS (avec l'extension @file{.cropped.eps}) sera généré en lieu et place
d'un PDF réduit. La valeur par défaut est @code{#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é.

@item @code{datadir}
Détermine le préfixe des fichiers de données (lecture seule).

@item @code{debug-eval} @var{bool}
Si @var{bool} est déterminé à @code{#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 @code{#f}, mais
@code{#t} lorsque @code{--verbose} est utilisé.

@item @code{debug-skylines} @var{bool}
Si @var{bool} est déterminé à @code{#t}, permet le débogage des lignes
d'horizon. La valeur par défaut est @code{#f}.

@item @code{delete-intermediate-files} @var{bool}
Si @var{bool} est déterminé à @code{#t}, supprime les fichiers
@file{.ps} inutiles créés lors de la compilation. La valeur par défaut
est @code{#t}.

@item @code{embed-source-code} @var{bool}
Si @var{bool} est déterminé à @code{#t}, intègre les fichiers source
LilyPond au document PDF généré. La valeur par défaut est @code{#f}.

@item @code{eps-box-padding} @var{num}
Décale le bord gauche du typon EPS d'une valeur @var{num} donnée en
millimètres. La valeur par défaut est @code{#f}, autrement dit sans décalage.

@item @code{font-export-dir} @var{chaîne}
Détermine à @var{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.

@example
$ 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
@end example

@noindent
Note : Contrairement à @code{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.

@noindent
Note : Identique à @code{font-ps-resdir}, cette option ignore les fontes
TrueType dans la mesure où les incorporer @i{a posteriori} cause une
altération des caractères. L'utilisation de @code{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.

@noindent
La valeur par défaut est @code{#f}, autrement dit absence d'export.

@item @code{font-ps-resdir} @var{chaîne}
Détermine à @var{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.

@example
$ 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
@end example

@noindent
Note : Il vaut mieux éviter que le nom du répertoire contienne le mot
@file{Resource}, qui a une signification particulière lorsqu'utilisé avec
une option @code{-I} de Ghostscript.

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

@noindent
Note : Identique à @code{font-export-dir}, cette option ignore les
fontes TrueType dans la mesure où les incorporer @i{a posteriori} cause
une altération des caractères. L'utilisation de
@code{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.

@noindent
La valeur par défaut est @code{#f}, autrement dit absence de
construction d'un sous-ensemble.

@item @code{gs-load-fonts} @var{bool}
Si @var{bool} est déterminé à @code{#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 @code{#f}.

@item @code{gs-load-lily-fonts} @var{bool}
Si @var{bool} est déterminé à @code{#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 @code{#f}.

@item @code{gs-never-embed-fonts} @var{bool}
Si @var{bool} est déterminé à @code{#t}, intime à Ghostscript
d'embarquer les fontes uniquement au format TrueType, sans exception. La
valeur par défaut est @code{#f}.

@item @code{help} @var{bool}
Si @var{bool} est déterminé à @code{#t}, affiche cette aide. La valeur
par défaut est @code{#f}.

@item @code{include-book-title-preview} @var{bool}
Si @var{bool} est déterminé à @code{#t}, inclut les titres de l'ouvrage
dans les images de prévisualisation. La valeur par défaut est @code{#t}.

@item @code{include-eps-fonts} @var{bool}
Si @var{bool} est déterminé à @code{#t}, inclut les fontes dans chaque
fichier EPS contenant un système. La valeur par défaut est @code{#t}.

@item @code{include-settings} @var{chaîne}
Inclut le fichier @var{chaîne} contenant les réglages globaux, qui sera
inclus avant traitement de la partition. La valeur par défaut est
@code{#f}, autrement dit absence de fichier de réglages.

@item @code{job-count} @var{num}
Traite plusieurs fichiers en parallèle, selon le nombre @var{num} de
@emph{jobs}. La valeur par défaut est @code{#f}, autrement dit sans
traitement parallèle.

@item @code{log-file} @var{chaîne}
Redirige la sortie dans le fichier journal @file{@var{chaîne}.log}. La
valeur par défaut est @code{#f}, autrement dit absence de fichier de
journalisation.

@item @code{max-markup-depth} @var{num}
Détermine à @var{num} la profondeur maximale de l'arborescence de
@emph{markups}. Si un @emph{markup} était plus profond, part du principe
qu'on n'aboutira pas, émet un avertissement et renvoie alors un
@emph{markup} vide. La valeur par défaut est @code{1024}.

@item @code{midi-extension} @var{chaîne}
Détermine à @var{chaîne} l'extension par défaut des fichiers MIDI.La
valeur par défaut est @code{"midi"}.

@item @code{music-strings-to-paths} @var{bool}
Si @var{bool} est déterminé à @code{#t}, convertit les chaînes
textuelles en chemins lorsque les glyphes font partie d'une fonte
musicale. La valeur par défaut est @code{#f}.

@cindex paper-size, ligne de commande
@item @code{paper-size} @var{chaîne-entre-guillemets}
Détermine la taille par défaut du papier à
@var{chaîne-entre-guillemets}. Veillez à ne pas oublier d'encadrer la
valeur par des guillemets échappés (@code{\"}).La valeur par défaut est
@code{"\"a4\""}.
@c Match " in context-sensitive editors

@item @code{pixmap-format} @var{symbole}
Détermine le format de sortie en images pixélisées pour Ghostscript à
@var{symbole}. La valeur par défaut est @code{png16m}.

@item @code{png-width} @var{largeur}
@itemx @code{png-height} @var{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 @option{--png}, les options @option{--eps},
@option{-dcrop} ou @option{-dpreview} devraient permettre une mise à
l'échelle correcte sans détourage.

L'option @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.

@item @code{point-and-click} @var{bool}
Si @var{bool} est déterminé à @code{#t}, ajoute les liens « point &
click » à la sortie PDF ou SVG -- voir @ref{Pointer-cliquer}. La valeur
par défaut est @code{#t}.

@cindex format de sortie, définition
@cindex preview, ligne de commande
@item @code{preview} @var{bool}
Si @var{bool} est déterminé à @code{#t}, génère une prévisualisation en
plus de la sortie normale. La valeur par défaut est @code{#f}.

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

Pour l'éviter, utilisez conjointement l'une des options
@option{-dprint-pages} ou @option{-dno-print-pages} selon vos besoins.

@item @code{print-pages} @var{bool}
Si @var{bool} est déterminé à @code{#t}, génère l'intégralité des pages
de la partition. La valeur par défaut est @code{#t}.

L'option @option{-dno-print-pages} est particulièrement
utile lorsqu'utilisée conjointement avec les options @option{-dpreview}
et @option{-dcrop}.

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

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

@item @code{resolution} @var{num}
Détermine la résolution des pixmaps @code{PNG}  à générer à @var{num}
@code{dpi}. La valeur par défaut est @code{101}.

@item @code{separate-log-files} @var{bool}
Pour les fichiers @file{fichier1.ly}, @file{fichier2.ly}, etc.
enregistre le déroulement dans les journaux @file{fichier1.log},
@file{fichier2.log}@dots{} si @var{bool} est déterminé à @code{#t}. La
valeur par défaut est @code{#f}.

@item @code{separate-page-formats} @var{symbole}
Liste des formats (@code{svg}, @code{pdf}, @code{png}, ou @code{eps}),
séparés par des virgules, à utiliser pour les images séparées des pages pour
@code{lilypond-book}.

@item @code{show-available-fonts} @var{bool}
Si @var{bool} est déterminé à @code{#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 @code{#t}.

@item @code{strip-output-dir} @var{bool}
Si @var{bool} est déterminé à @code{#t}, supprime, lors du nommage des
fichiers résultants, la partie correspondant au répertoire des fichiers
sources. La valeur par défaut est @code{#t}.

@item @code{strokeadjust} @var{bool}
Si @var{bool} est déterminé à @code{#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 @code{#f}.

@item @code{svg-woff} @var{bool}
Cette option est obligatoire dès lors que sont utilisées, avec le
moteur @code{svg}, les fontes @emph{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 @code{#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 @code{woff} textuelle.  La présence du fichier de fonte
@code{woff} est un prérequis.

@item @code{tall-page-formats} @var{symbole}
Liste des formats (@code{svg}, @code{pdf}, @code{png}, ou @code{eps}),
séparés par des virgules, à utiliser pour l'image pleine page pour
@code{lilypond-book}.

@item @code{use-paper-size-for-page} @var{bool}
Si @var{bool} est déterminé à @code{#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 à @code{#f}, la
feuille sera redimsensionnée pour contenir autant que nécessaire.

@item @code{verbose}
Passe en mode verbeux, ce qui correspond à un niveau de journalisation
@code{DEBUG} (lecture seule).

@item @code{warning-as-error} @var{bool}
Si @var{bool} est déterminé à @code{#t}, considère tous les messages
d'avertissement et « erreur de programmation » comme étant de véritables
erreurs. La valeur par défaut est @code{#f}.

@end table


@node Variables d'environnement
@unnumberedsubsec Variables d'environnement
@translationof Environment variables

@cindex LANG
@cindex LILYPOND_DATADIR
@cindex LILYPOND_LOCALEDIR
@cindex LILYPOND_RELOCDIR
@cindex LILYPOND_LOGLEVEL

@command{lilypond} reconnaît les variables d'environnement
suivantes :

@table @code
@item 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 @ref{Réadressage}. Il devrait contenir les
sous-répertoires @file{ly/}, @file{ps/}, @file{tex/}, etc.

@item 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
@code{LILYPOND_DATADIR}.

@item 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 @command{lilypond}.

@item LANG
Cette variable détermine la langue dans laquelle sont émises les
données sur @code{stdout} (sortie standard) et @code{stderr} (sortie des
erreurs), pour afficher la progession, les avertissements ou messages de
débogage. Par exemple : @code{LANG=de}.

@item 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 @option{--loglevel} -- c'est cette valeur qui sera
utilisée.

@item 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 à @code{70}.

@item TMPDIR
Cette variable permet de déterminer, sur GNU/Linux et Mac, le répertoire
temporaire. La valeur par défaut est @file{/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 @command{lilypond} n'a pas les droits en
écriture sur le répertoire temporaire par défaut. Exemple :
@code{TMPDIR=~/toto}.

@end table


@node Réadressage
@unnumberedsubsec Réadressage
@translationof Relocation

@cindex relocation
@cindex 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 @file{lilypond}
dans le répertoire @file{/usr/@/bin} et tous les fichiers propres à
LilyPond dans des sous-répertoires de
@file{/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 @emph{relativement au binaire lancé}.

@menu
* Fichiers de réadressage::
* Algorithme de réadressage::
@end menu


@node Fichiers de réadressage
@unnumberedsubsubsec Fichiers de réadressage
@translationof Relocation files

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 @command{FontConfig} et
@command{GUILE} pour trouver respectivement les fontes du système et les
traitement des fichiers Scheme, ainsi que le programme @command{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 @command{lilypond} analyse tous les fichiers d'un
répertoire dénommé @file{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

@example
@var{commande} @var{clé}=@var{valeur}
@end example

@noindent
et les lignes vides y seront ignorées

La directive @var{commande} est l'une des suivantes :

@table @code

@item set
Définit de manière inconditionnelle la variable d'environnement
@var{clé} à @var{valeur}. Ceci écrase la valeur précédemment définie.

@item set?
Définit la variable d'environnement @var{clé} à @var{valeur} uniquement
si @var{clé} n'est pas déjà définie. En d'autres termes, une valeur
précédemment définie ne sera pas écrasée.

@item setdir
Lorsque @var{valeur} est un répertoire, définit inconditionnellement
@var{clé} à @var{valeur}. Un message d'avertissement est émis dans le
cas contraire.

@item setfile
Lorsque @var{valeur} est un fichier, définit inconditionnellement
@var{clé} à @var{valeur}. Un message d'avertissement est émis dans le
cas contraire.

@item prependdir
Ajoute le répertoire @var{valeur} à la liste des répertoires de la
variable d'environnement @var{clé}. Dans le cas où @var{clé} n'existe
pas, celle-ci sera créée.

@end table

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

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

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

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


@node Algorithme de réadressage
@unnumberedsubsubsec Algorithme de réadressage
@translationof Relocation algorithm

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

@enumerate

@item
Localisation du répertoire où se trouve le binaire @command{lilypond}
actuellement exécuté et nommage en @code{bindir}. Détermination, en
interne, de la variable d'environnement @code{INSTALLER_PREFIX} à
@file{@var{bindir}/..} -- autrement dit le répertoire parent de
@code{bindir}.

@item
Contrôle de la variable d'environnement @code{LILYPOND_DATADIR}. Si
elle est définie, utilisation de sa valeur pour le répertoire de données
-- @code{datadir} -- de LilyPond. Dans le cas contraire,
utilisation soit de
@file{$INSTALLER_PREFIX/@/share/@/lilypond/@/@var{version}} (avec
@var{version} étant la version courante de LilyPond), soit
@file{$INSTALLER_PREFIX/@/share/@/lilypond/@/current}.

@item
Contrôle de la variable d'environement @code{LILYPOND_LOCALEDIR}.
Si elle est définie, utilisation de sa valeur pour le répertoire
de données linguistiques -- @code{localedir} --  de LilyPond. Dans
le cas contraire, ce sera @file{$INSTALLER_PREFIX/@/share/@/locale}.

@item
Contrôle de la variable d'environnement @code{LILYPOND_RELOCDIR}.
Si elle existe, utilisation de sa valeur pour le répertoire des
fichiers de réadressage -- @code{relocdir} -- de LilyPond. Dans le
cas contraire, ce sera @file{$INSTALLER_PREFIX/@/etc/@/relocate}.

@item
En l'absence de @code{datadir}, utilisation d'une valeur déterminée au
fil de la compilation. Idem pour @code{localedir}, mais pas pour
@code{relocdir} (cela n'a aucun sens de le faire).

@item
Si @code{relocdir} existe, traiter tous les fichiers dans ce
répertoire, comme indiqué dans @ref{Fichiers de réadressage}.

@end enumerate


@node Exécution de LilyPond en mode protégé
@unnumberedsubsec Exécution de LilyPond en mode protégé
@translationof LilyPond in chroot jail

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 @code{sudo} autant que de besoin.

@itemize

@item Installation des paquetages nécessaires : LilyPond, Ghostscript et
ImageMagick.

@item Création de l'utilisateur @code{lily} :

@example
adduser lily
@end example

@noindent
Ceci, par la même occasion, créera un groupe spécifique pour
l'utilisateur @code{lily} ainsi que son répertoire personnel
@code{/home/lily}.

@item Création, dans le répertoire personnel de l'utilisateur
@code{lily}, d'un espace agissant en tant que système de fichiers :

@example
dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
@end example

@noindent
Cette commande a créé un fichier de 200 MB utilisable par le
« système protégé ».

@item 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 @code{lily} :

@example
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
@end example

@item Affectation, au niveau configuration du serveur, de
@code{/mnt/lilyloop} en tant que JAIL et @code{/lilyhome} en tant que
DIR.

@item 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 @code{sed} permet de créer les commandes de
copie de tout ce qui est nécessaire à un exécutable donné :

@example
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
@end example

@end itemize

@subheading Exemple de script fonctionnel en 32-bit sur Ubuntu 8.04

@example
#!/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
@end example


@node Messages d'erreur
@section Messages d'erreur
@translationof Error messages

@cindex erreur, messages

Différents messages d'erreur sont susceptibles d'apparaître au cours de
la compilation d'un fichier :

@table @emph

@item Warning -- Avertissement
@cindex warning
@cindex avertissement
Ce type de message est émis lorsque LilyPond détecte quelque chose de
suspect.  Si vous avez demandé quelque chose qui sort de l'ordinaire,
vous saurez probablement ce à quoi il est fait référence et ignorerez de
tels messages sans remord.  Néanmoins, les messages d'avertissement
indiquent la plupart du temps une incohérence dans le fichier source.

@item Error -- Erreur
@cindex error
LilyPond a détecté une erreur.  L'étape en cours, qu'il s'agisse de
l'analyse, de l'interprétation des données ou bien du formatage, sera
menée à son terme, puis LilyPond s'arrêtera.

@item Fatal error -- Erreur fatale
@cindex fatal error
LilyPond est confronté à une anomalie bloquante.  Ceci ne se produit que
très rarement, et la plupart du temps en raison d'une installation
défectueuse des fontes.

@item Scheme error -- Erreur Scheme
@cindex trace, Scheme
@cindex call trace
@cindex Scheme error
Les erreurs qui interviennent lors de l'exécution de code Scheme sont
gérées par l'interpréteur Scheme.  L'utilisation du mode verbeux
(options @option{-V} ou @option{--verbose}) vous permettra de localiser
l'appel de fonction délictueux.

@item Programming error -- Erreur de programmation
@cindex Programming error
@cindex Erreur de programmation
LilyPond est confronté à une incohérence interne.  Ce type de message
est destiné à venir en aide aux développeurs et débogueurs.  En règle
générale, vous pouvez tout simplement les ignorer.  Parfois, il y en a
tant qu'ils masquent ce qui pourrait vous intéresser@dots{}

@item Aborted (core dumped) -- Abandon
@cindex Aborted (core dumped)
Ce type de message indique que LilyPond a planté en raison d'une grave
erreur de programmation.  La survenance d'un tel message est considérée
comme de la plus haute importance.  Si vous y étiez confronté,
transmettez un rapport de bogue.
@end table

@cindex erreur, format du message
Lorsque l'avertissement ou l'erreur est directement lié au fichier
source, le message est libellé sous la forme

@example
@var{fichier}:@var{ligne}:@var{colonne}: @var{message}
@var{contenu de la ligne litigieuse}
@end example

Un saut de ligne est placé dans la ligne de code, indiquant l'endroit
précis du problème, comme ici :

@example
test.ly:2:19: erreur: n'est pas une durée: 5
  @{ c'4 e'
           5 g' @}
@end example

Notez que ces coordonnées constituent l'approximation au mieux par
LilyPond dans le code ayant déclenché l'avertissement ou l'erreur.  En
règle générale, erreurs et avertissements surviennent lorsque LilyPond
rencontre quelque chose d'inattendu.  Lorsque la ligne indiquée ne vous
semble pas comporter d'élément litigieux, remontez de quelques lignes
dans votre code.

Par ailleurs, des diagnostics peuvent être déclenchés à n'importe quel
moment au cours des différentes étapes du traitement.  Par exemple,
lorsque certaines parties de la source sont traitées plusieurs fois --
sortie MIDI et sortie imprimable -- ou qu'une même variable musicale est
utilisée dans plusieurs contextes, peut apparaître le même message à
plusieurs reprises.  Les diagnostics effectués à une étape avancée du
traitement, tels que les contrôles de mesure, sont aussi susceptibles
d'apparaître plusieurs fois.

Vous trouverez d'autres informations sur les erreurs au chapitre
@ref{Quelques erreurs des plus courantes}.


@node Quelques erreurs des plus courantes
@section Quelques erreurs des plus courantes
@translationof Common errors

Les conditions amenant aux erreurs qui suivent sont fréquentes, bien
qu'elles ne soient pas évidentes ni facilement localisables.  Nous
espérons que ces explications vous aideront à les résoudre plus
facilement.

@menu
* La musique déborde de la page::
* Apparition d'une portée supplémentaire::
* Message d'erreur Unbound variable %::
* Message d'erreur FT_Get_Glyph_Name::
* staff-affinities devraient aller en ordre décroissant::
* Message d'erreur unexpected new::
* Cette voix requiert un voiceXx ou un réglage shiftXx::
@end menu


@node La musique déborde de la page
@unnumberedsubsec La musique déborde de la page
@translationof Music runs off the page

Lorsque la musique s'épanche au delà de la marge droite ou bien semble
anormalement comprimée, la raison en est le plus souvent une note à la
durée erronée ; cela finit par provoquer le débordement de la
dernière note d'une mesure.  Rien ne s'oppose à ce que la dernière note
d'une mesure ne s'arrête avant la barre de mesure ; on considère
simplement qu'elle se prolonge sur la mesure suivante.  Des débordements
à répétition finissent par générer une musique comprimée ou qui sort de
la page, pour la simple et bonne raison que les sauts de ligne
automatiques ne peuvent intervenir qu'à la fin d'une mesure complète,
autrement dit lorsque toutes les notes sont terminées avant la fin de la
mesure.

@warning{Une durée erronée peut empêcher les sauts de ligne, ce qui
conduit à une musique compressée, voire à un débordement de la page.}

Une erreur de durée sera bien plus facilement localisable si vous
positionnez régulièrement des contrôles de barre de mesure -- voir
@ruser{Vérification des limites et numéros de mesure}.

Si vous tenez absolument à enchaîner de tels débordements, vous devrez
insérer des barres de mesure invisibles là où vous souhaitez positionner
un saut de ligne.  Consultez le chapitre @ruser{Barres de mesure} pour
plus de détails.


@node Apparition d'une portée supplémentaire
@unnumberedsubsec Apparition d'une portée supplémentaire
@translationof An extra staff appears

Lorsque les contextes ne sont pas créés explicitement par la commande
@code{\new}, ils le seront si la commande à exécuter n'est pas censée
s'appliquer au contexte en cours.  Pour des partitions simples, le fait
que les contextes soient automatiquement créés rend bien des services,
et c'est d'ailleurs le cas pour la majorité des exemples contenus dans
les manuels de LilyPond.  Cependant, la création implicite d'un contexte
peut aboutir à l'apparition d'une portée « parasite ».  On s'attend par
exemple, en lisant le code qui suit, à ce que toutes les têtes de note
soient en rouge, alors que le résultat nous présente deux portées et que
les notes, placées sur la portée inférieure, restent en noir.

@lilypond[quote,verbatim,fragment]
\override Staff.NoteHead.color = #red
\new Staff { a' }
@end lilypond

Étant donné qu'aucun contexte @code{Staff} n'existe lorsque la
dérogation est introduite, LilyPond le crée implicitement pour lui
appliquer la directive considérée.  Survient alors la commande
@code{\new Staff} qui, à son tour, crée une nouvelle portée pour
contenir les notes qui suivent.  Voici la syntaxe correcte pour obtenir
ces notes en rouge :

@lilypond[quote,verbatim]
\new Staff {
  \override Staff.NoteHead.color = #red
  a'
}
@end lilypond


@node Message d'erreur Unbound variable %
@unnumberedsubsec Message d'erreur @code{Unbound variable %}
@translationof Error message Unbound variable %

Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
fichier journal, est associé à un message du type « GUILE a signalé
une erreur@dots{} ». Il survient à chaque fois qu'un commentaire
@emph{LilyPond} est indûment placé dans une routine @emph{Scheme}.

Un commentaire LilyPond est introduit par le signe pourcent (@code{%})
et ne doit en aucun cas se trouver dans une routine Scheme.  En Scheme,
les commentaires s'introduisent par un point-virgule (@code{;}).


@node Message d'erreur FT_Get_Glyph_Name
@unnumberedsubsec Message d'erreur @code{FT_Get_Glyph_Name}
@translationof Error message FT_Get_Glyph_Name

Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
fichier journal, survient lorsqu'un fichier source contient des
caractères non ASCII et qu'il n'a pas été enregistré avec un encodage
UTF-8.  Pour plus de détails, reportez-vous au chapitre
@ruser{Caractères spéciaux}.


@node staff-affinities devraient aller en ordre décroissant
@unnumberedsubsec @emph{staff-affinities} devraient aller en ordre décroissant
@translationof Warning staff affinities should only decrease

Cet avertissement est émis lorsque la partition ne comporte pas de
portée, comme par exemple une feuille de chant avec un contexte
@code{ChordName} et un contexte @code{Lyrics}.  Ce message disparaîtra
dès lors que vous autoriserez l'un de ces contextes à se comporter comme
une portée, à l'aide de l'instruction

@example
\override VerticalAxisGroup.staff-affinity = ##f
@end example

@noindent
que vous insérerez dès sa création.  Pour plus d'information,
reportez-vous à la rubrique
@ruser{Espacement des lignes rattachées à des portées}.


@node Message d'erreur unexpected new
@unnumberedsubsec Message d'erreur @code{unexpected \new}
@translationof Error message unexpected new

Un bloc @code{\score} ne peut contenir qu'@strong{une seule} expression
musicale. Si, par contre, il comporte plusieurs @code{\new Staff},
@code{\new StaffGroup} ou autres contextes introduits par une commande
@code{\new} qui ne seraient pas bornés par des accolades
@code{@{ @dots{} @}} ou des doubles chevrons @code{<< @dots{} >>} comme
ici :

@example
\score @{
  % Invalide ! Génère l'erreur : syntax error, unexpected \new
  % en français : erreur de syntaxe : \new inattendu
  \new Staff @{ @dots{} @}
  \new Staff @{ @dots{} @}
@}
@end example

@noindent
vous obtiendrez ce message d'erreur.

Cette erreur sera évitée dès lors que toutes les instances de
@code{\new} sont bornées par des accolades ou des doubles chevrons.

Des accolades placeront ces clauses @code{\new} en séquence :

@lilypond[quote,verbatim]
\score {
  {
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  }
}
@end lilypond

@noindent
alors que des doubles chevrons les placeront en parallèle ; autrement
dit, LilyPond les traitera simultanément :

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  >>
}
@end lilypond


@node Cette voix requiert un voiceXx ou un réglage shiftXx
@unnumberedsubsec Cette voix requiert un @code{\voiceXx} ou un réglage @code{\shiftXx}
@translationof Warning this voice needs a voiceXx or shiftXx setting

Lorsque des notes affectées à des voix différentes et ayant la même
orientation de hampe interviennent au même instant musical et qu'aucun
décalage spécifique à la voix n'a été spécifié, LilyPond émet
@code{Avertissement : Cette voix requiert un voiceXx ou un réglage
shiftXx} (@emph{warning: this voice needs a \voiceXx or \shiftXx
setting}).  Cet avertissement est émis même lorsque ces notes n'ont pas
de hampe visible, comme par exemple des rondes, si les hampes des durées
inférieures à ces mêmes hauteurs avaient la même orientation.

N'oublions pas que l'orientation des hampes dépend de la position des
notes sur la portée à moins que cette orientation n'ait été spécifiée,
par exemple à l'aide d'un @code{\voiceOne} ou autre clause.  En pareil
cas, l'avertissement ne sera émis que lorsque les hampes auront la même
orientation, autrement dit lorsque les notes seront dans la même moitié
de la portée.

Le fait de placer les notes dans des voix auxquelles sont attachés
orientation de hampe et décalage, comme @code{\voiceOne} ou autre, peut
permettre d'éviter ces avertissements.

Les notes se trouvant dans des voix au numéro plus élévé --
@code{\voiceThree} ou @code{\voiceFour} -- sont automatiquement décalées
pour éviter que les empilements se chevauchent.  Ceci aura pour résultat
de visuellement décaler les notes affublées de hampe sans toutefois
bouger les rondes, hormis dans le cas d'un réel chevauchement ou lorsque
ces voix se croisent (@code{\voiceThree} au dessus de@code{\voiceOne}).

@morerefs
Manuel d'initiation :
@rlearning{Instanciation explicite des voix},
@rlearning{Exemple concret}.

Manuel de notation :
@ruser{Polyphonie sur une portée},
@ruser{Résolution des collisions}.
@endmorerefs
