GNU LilyPond Programmbenutzung: 1.2.2 Optionen auf der Kommandozeile für lilypond

### 1.2.2 Optionen auf der Kommandozeile für `lilypond`

Die folgenden Kommandozeilenoptionen werden von `lilypond` unterstützt:

`-e,--evaluate=expr`

  Wertet den Scheme-Ausdruck expr aus, bevor die ‘`.ly`’ Dateien gelesen und interpretiert werden. Die `-e` Option kann auch mehrfach angegeben werden, die Ausdrücke werden nacheinander ausgewertet.

  Da der Ausdruck im `guile-user` Modul ausgewertet wird, ist bei der Definitionen innerhalb von expr folgendes Vorgehen nötig. An der Kommandozeile wird z.B. `a` im `guile-user` Modul definiert:

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

  Am Beginn der ‘`.ly`’-Datei muss dann das `guile-user` Modul noch geladen werden, bevor die Definition von a verfügbar ist:

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

`-f,--format=Format`

  Bestimmt das Ausgabeformat. Mögliche Werte von Format sind `svg`, `ps`, `pdf` und `png`.

  Beispiel: `lilypond -fpng Dateiname.ly`

`-d,--define-default=Variable=Wert`

  Damit wird die interne Programmoption Variable auf den Scheme-Wert Wert gesetzt. Wird kein Wert angegeben, so wird #t benutzt. Um eine Option auszuschalten, kann der Präfix `no-` dem Namen Variable der Variable vorangestellt werden. So ist etwa

  >     -dno-point-and-click

  dasselbe wie

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

  Hier sind ein paar interessante Optionen:

  ‘`help`’

    Die Ausführung von `lilypond -dhelp` zeigt alle verfügbaren `-d` Optionen.

  ‘`paper-size`’

    Setzt das Standard-Papierformat,

    >     -dpaper-size=\"letter\"

    Die Zeichenkette, die das Format angibt, muss in Anführungszeichen mit Backslash ( `\"` ) stehen.

  ‘`safe`’

    Vertraut der ‘`.ly`’ Datei nicht.

    Wenn LilyPond über einen Webserver verfügbar gemacht wird, MUSS unbedingt eine die Optionen `--safe` oder `--jail` angegeben werden. Die `--safe` Option verhindert, dass in der ‘`.ly`’-Datei angegebener Scheme-Code das System gefährden kann, wie etwa in folgendem Beispiel:

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

    Mit der `-dsafe` Option werden alle Scheme-Ausdrücke einem speziellen sicheren Modus ausgewertet. Dieser Modus ist vom GUILE ‘`safe-r5rs`’ Modul abgeleitet und fügt noch zahlreiche weitere erlaubte Funktionen der LilyPond Programm-Schnittstelle hinzu. Diese Funktionen sind in ‘`scm/safe-lily.scm`’ angegeben.

    Zusätzliche verbietet der sichere Modus auch `\include` Befehle.

    Im sicheren Modus ist es nicht möglich, LilyPond-Variablen nach Scheme zu exportieren.

    `-dsafe` erkennt jedoch KEINE Überbeanspruchung der verfügbaren Ressourcen. In diesem Modus ist es also trotzdem möglich, dass LilyPond in einer Endlosschleife hängt, z.B. wenn zyklische Datenstrukturen an das Backend übergeben werden. Wenn LilyPond also auf einem öffentlich zugänglichen Webserver verfügbar gemacht wird, sollte der Prozess sowohl in der CPU- als auch in der Speichernutzung limitiert werden.

    Der sichere Modus verhindert auch, dass zahlreiche nützliche Musikfragmente von LilyPond verarbeitet werden. Die `--jail` Option ist eine sicherere Alternative, benötigt allerdings auch mehr Aufwand zur Einrichtung.

  ‘`backend`’

    Gibt an, welches Ausgabeformat das LilyPond Backend benutzt. Mögliche Werte für diese Option sind:

    `ps`

      PostScript-Ausgabeformat.

      Postscript-Dateien enthalten auch TTF-, Type1- und OTF-Schriften. Allerdings wird die gesamte Schriftart eingefügt und nicht nur die benötigten Zeichen. Vor allem wenn nicht-westliche Zeichensätze benutzt werden, kann dies zu sehr großen Dateien führen.

    `eps`

      Erzeugt ‚encapsulated PostScript‘ (EPS). Jede Seite (oder jedes System) wird als eigene ‘`EPS`’-Datei ausgegeben, inklusive Schriftarten. Außerdem wird eine Datei mit allen Seiten (bzw. Systemen) und Schriftarten erzeugt.

      Dies ist die Standardeinstellung von `lilypond-book`.

    `svg`

      SVG-Ausgabe (Scalable Vector Graphics).

      Hiermit wird eine einzelne SVG-Datei ohne eingebundene Schriften für jede Seite der Partitur erstellt. Es wird empfohlen, Century Schoolbook-Schriftarten zu installieren, die auch in der LilyPond-Installation enthalten sind, um optimales Rendern zu erhalten. Unter UNIX können diese Schriftarten einfach aus dem LilyPond-Verzeichnis (normalerweise ‘`/usr/share/lilypond/VERSION/fonts/otf/`’) nach ‘`~/.fonts`’ kopiert werden. Die SVG-Ausgabe sollte mit allen SVG-Editoren oder Betrachtungsprogrammen kompatibel sein.

    `scm`

      gibt die rohen Scheme-basierenden Zeichenbefehle aus, wie sie intern von LilyPond benutzt werden.

    `null`

      Keine Partitur wird ausgegeben, hat gleichen Effekt wie `-dno-print-pages`.

    Beispiel: `lilypond -dbackend=svg Dateiname.ly`

  ‘`preview`’

    Erzeugt eine Ausgabedatei, die nur die Titelzeilen und das erste System enthält. Wenn `\bookpart`-Umgebungen benutzt werden, erscheinen die Titel und ersten Systeme jedes `\bookpart`-Abschnitts in der Datei. Die Backends `ps`, `eps` und `svg` unterstützen diese Option.

  ‘`print-pages`’

    Erzeugt vollständige Seiten (Standardeinstellung). `-dno-print-pages` ist in Verbindung mit `-dpreview` nützlich.

`-h,--help`

  Zeigt eine Zusammenfassung der Programmbenutzung und der Optionen.

`-H,--header=FELD`

  Gibt den Inhalt eines Feldes aus dem `\header`-Block in die Datei ‘`Dateiname.FELD`’ aus.

`--include, -I=Verzeichnis`

  Fügt Verzeichnis zur Liste der Suchpfade hinzu.

  Mehrere -I-Optionen können angegeben werden. Die Suche beginnt mit dem ersten definierten Verzeichnis und setzt in den weiteren Verzeichnissen fort, wenn die gesuchte Datei nicht in dem Verzeichnis gefunden wird.

`-i,--init=Initialisierungsdatei`

  Benutzt Initialisierungsdatei zur gesamten Programminitialisierung. Der Standardwert ist ‘`init.ly`’.

`-o,--output=DATEI`

  Schreibt das Ergebnis der Verarbeitung mit LilyPond in die Ausgabedatei DATEI. Wenn ein Verzeichnis mit dem Namen existiert, werden die Ausgabedateien in dieses Verzeichnis gespeichert, wobei der Dateiname der Eingabedatei benutzt wird. Die entsprechende Dateinamenserweiterung wird angehängt (z.B. `.pdf` für pdf).

`--ps`

  Erzeugt PostScript.

`--png`

  Erzeugt eine Grafik-Datei im PNG-Format von jeder Seite. Diese Option impliziert auch `--ps`. Die Auflösung in DPI der Grafik kann festgelegt werden durch

  >     -dresolution=110

`--pdf`

  Erzeugt PDF-Dateien. Dies impliziert `--ps`.

`-j,--jail=Benutzer,Gruppe,Jail-Verzeichnis,Arbeitsverzeichnis`

  Führt `lilypond` in einem chroot-Jail aus.

  Die `--jail` Option ist eine flexiblere Alternative zu `--safe`, wenn LilyPond über das Internet verfügbar gemacht wird oder LilyPond-Quelldateien von Dritten automatisch verarbeitet werden.

  Sie funktioniert dergestalt, dass das Wurzelverzeichnis von `lilypond` auf Jail-Verzeichnis gesetzt wird, bevor die tatsächliche Kompilierung der ‘`.ly`’-Datei beginnt. Der Benutzer und die Gruppe werden auf die angegebenen Werte gesetzt und das aktuelle Arbeitsverzeichnis wird ebenfalls auf den angegebenen Wert Arbeitsverzeichnis gesetzt. Diese Einstellungen garantieren (zumindest in der Theorie), dass es nicht möglich ist, aus dem Jail auszubrechen. Damit `--jail` funktioniert, muss `lilypond` allerdings als root ausgeführt werden, was normalerweise auf sichere Art mit dem Kommando `sudo` erreicht werden kann.

  Das Jail-Verzeichnis zu erstellen ist etwas heikel, da LilyPond alle zur Ausführung nötigen Bibliotheken und Dateien innerhalb des Jail-Verzeichnisses finden muss. Ein typisches Setup besteht aus folgenden Punkten:

  Erstellung eines getrennten Dateisystems

    Ein eigenes Dateisystem muss für LilyPond erstellt werden, sodass es mit sicheren Einstellungen wie `noexec`, `nodev` und `nosuid` eingebunden werden kann. Damit ist es unmöglich, Programme von diesem Dateisystem auszuführen oder direkt auf eine Hardware-Schnittstelle zuzugreifen. Wenn Sie keine eigene Partition erstellen möchten, können Sie auch eine Datei der entsprechenden Größe erstellen und sie als ‚loop‘-Gerät einbinden. Ein getrenntes Dateisystem garantiert auch, dass LilyPond nicht mehr Festplattenspeicher benutzt als erlaubt.

  Erstellung eines eigenen Benutzerkontos

    Es sollte ein eigener Benutzer und eine eigene Gruppe (z. B. `lily`/`lily`) mit geringen Rechten für die Ausführung von LilyPond innerhalb des Jails benutzt werden. Nur ein einziges Verzeichnis des Jails sollte für den Benutzer schreibbar sein und als Arbeitsverzeichnis an `lilypond` übergeben werden.

  Einrichtung des Jails

    LilyPond muss zahlreiche Dateien für die Ausführung einlesen. All diese Dateien müssen in das Jail-Verzeichnis kopiert werden (mit denselben Pfaden wie im tatsächlichen Wurzel-Dateisystem). Die gesamte LilyPond-Installation (typischerweise ‘`/usr/share/lilypond`’) sollte kopiert werden.

    Falls Probleme auftreten, ist es am einfachsten, Lilypond mittels `strace` zu starten, wodurch Sie relativ leicht feststellen können, welche Dateien im Jail noch fehlen.

  Ausführung von LilyPond

    In einem mit `noexec` eingebundenen Jail ist es nicht möglich, externe Programme auszuführen. Daher muss LilyPond auf eine Art gestartet werden, die keine weitere Ausführung von Programmen benötigt. Wie bereits erwähnt muss LilyPond mit Administrator-Rechten gestartet werden (die es allerdings sofort wieder abgibt), beispielsweise mittels `sudo`. Außerdem ist es eine gute Idee, die LilyPond zur Verfügung stehende CPU-Zeit zu limitieren (z. B. mit `ulimit -t`) und – falls das Betriebssystem dies unterstützt – auch den zur Verfügung stehenden Hauptspeicher.

`-v,--version`

  Gibt die Versionsnummer aus.

`-V,--verbose`

  Gibt ausführliche informative Meldungen aus: Zeigt die vollen Dateipfade aller gelesenen Dateien sowie Informationen über die Laufzeit.

`-w,--warranty`

  Zeigt die Garantiebedingungen an, unter denen GNU LilyPond steht. (Es besteht KEINERLEI GARANTIE!)

#### LilyPond – Usage