LilyPond Használati útmutató: 1.2 Parancssori használat

## 1.2 Parancssori használat

Ez a szakasz a LilyPond parancssori futtatásáról tartalmaz plusz információkat, arra az esetre, ha a programnak plusz paramétereket szeretnénk átadni. Ráadásul bizonyos segédprogramok (mint pl. a `midi2ly`) csak parancssorból érhetőek el.

Parancssor alatt az operációs rendszer megfelelő parancssorát értjük. A Windows-felhasználók ezt „DOS-parancssor” néven, a Mac OS X felhasználok „Terminal” néven ismerhetik.

Az operációs rendszer parancssorának használatának leírása kívül esik a LilyPond dokumentációjának hatáskörén; az ebben kevésbé járatos felhasználók az operációs rendszerhez tartozó dokumentációban olvashatnak erről.

### A `lilypond` futtatása

A `lilypond` program a következő módon futtatható parancssorból:

>     lilypond [opció]… fájlnév…

Ha nem adunk meg kiterjesztést, az alapértelmezett ‘`.ly`’ kiterjesztéssel próbálkozik a LilyPond. A szabványos bemenetről való beolvasáshoz a `-` karakter használandó fájlnév gyanánt.

Amikor a ‘`fájlnév.ly`’ fájl feldolgozásra kerül, egy ‘`fájlnév.ps`’ és egy ‘`fájlnév.pdf`’ fájlt kapunk kimenetként. Több fájlt is feldolgoztathatunk egyszerre; ezek egymástól függetlenül kerülnek feldolgozásra. 1

Ha a ‘`fájlnév.ly`’ több `\book` blokkot tartalmaz, minden blokkból egy-egy, számozott kimeneti fájl keletkezik, ‘`fájlnév.pdf`’, ‘`fájlnév-1.pdf`’, ‘`fájlnév-2.pdf`’ stb. formában. Az `output-suffix` változó értéke fog szerepelni a fájlnév és a számozás között. Például a következő bemeneti fájlból:

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

egy ‘`fájlnév-violino.pdf`’ és egy ‘`fájlnév-cello-1.pdf`’ nevű fájl keletkezik.

### A `lilypond` parancssori paraméterei

A következő parancssori opciók támogatottak:

`-e, --evaluate=kifejezés`

  A Scheme kifejezés kiértékelése az ‘`.ly`’ fájlok beolvasása előtt. Több `-e` opció is megadható, ezek a megadott sorrendben lesznek végrehajtva.

  A kifejezés kiértékelése a `guile-user` modulban történik, így ha definíciókat kell használni a kifejezésben, a parancssorban a következőt kell megadni:

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

  a forrásfájl elejére pedig a következőt kell beszúrni:

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

`-f, --format=formátum`

  A kimenet formátuma. Lehetőségek: `ps`, `pdf` vagy `png`.

  Példa: `lilypond -fpng fájlnév.ly`

`-d, --define-default=azonosító=érték`

  Az azonosító nevű belső változó beállítása az érték Scheme értékre. Ha az érték nincs megadva, az alapértelmezett `#t` lesz a változó értéke. Egy opció kikapcsolásához a `no-` prefixumot kell az azonosító elé írni, pl.

  >     -dno-point-and-click

  ugyanaz, mint

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

  Íme pár hasznos opció:

  ‘`help`’

    A `lilypond -dhelp` parancs futtatása kilistázza az összes elérhető `-d` opciót.

  ‘`paper-size`’

    Az alapértelmezett papírméret beállítása.

    >     -dpaper-size=\"letter\"

    Ügyelni kell arra, hogy a méretet `\"` jelek közé írjuk.

  ‘`safe`’

    A LilyPond futtatása biztonsági módban, megbízhatatlan bemenet esetén.

    Amikor a LilyPond egy webszerveren keresztül érhető el, vagy a `-dsafe`, vagy a `--jail` opciót MINDENKÉPPEN KÖTELEZŐ megadni. A `-dsafe` opcióval megelőzhető, hogy a forrásfájlban szereplő rosszindulatú Scheme kód kárt okozzon. Például:

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

    `-dsafe` módban a Scheme kifejezések kiértékelése egy speciális biztonsági modulban történik. Ez a modul a GUILE ‘`safe-r5rs`’ modulján alapul, de a LilyPond API néhány függvényének meghívását lehetővé teszi. Ezek a függvények a ‘`scm/safe-lily.scm`’ fájlban találhatóak.

    Ezenkívül biztonsági módban tilos az `\include` parancsok alkalmazása és a \ karakter használata TeX karakterláncokban.

    Biztonsági módban ezenfelül nem lehetséges LilyPond változók importálása Scheme-be.

    A `-dsafe` mód nem figyeli az erőforrások túlzott használatát. Továbbra is elérhető, hogy a program tetszőlegesen hosszú ideig fusson, például ciklikus adatstruktúrák használatával. Így ha a LilyPond publikus webszerveren fut, a folyamat processzor- és memóriafelhasználását korlátozni kell!

    Biztonsági módban sok hasznos LilyPond kódrészlet nem fog lefordulni. A `--jail` mód egy több lehetőséget biztosító alternatíva, de előkészítése több munkát igényel.

  ‘`backend`’

    A szedés kimeneti formátuma. Lehetőségek:

    `ps`

      PostScript.

      A PostScript fájlok teljes egészükben tartalmazzák a megjelenítéshez szükséges TTF, Type1 és OTF betűkészleteket. Keleti karakterkészletek használata esetén ez nagy fájlokhoz vezethet.

    `eps`

      Encapsulated PostScript.

      Minden oldal külön ‘`EPS`’ fájlba kerül, betűtípusok nélkül, valamint egy összesített ‘`EPS`’ fájl is létrejön, amely az összes oldalt tartalmazza betűtípusokkal együtt.

      A `lilypond-book` alapértelmezetten ezt a formátumot használja.

    `svg`

      SVG (Scalable Vector Graphics).

      Oldalanként egy SVG fájl keletkezik, beágyazott betűtípusok nélkül. Így megtekintésükhöz érdemes feltelepíteni a Century Schoolbook betűtípusokat. Ezeket tartalmazza a LilyPond. Például UNIX alatt egyszerűen csak be kell másolni ezeket a program könyvtárából (tipikusan ‘`/usr/share/lilypond/VERZIÓ/fonts/otf/`’) a ‘`~/.fonts/`’ könyvtárba. Az SVG kimenet szabványos, így bármilyen, ezt a formátumot olvasni képes programmal megnyitható.

    `scm`

      A belső Scheme rajzolóparancsok szó szerinti kiírása.

    `null`

      Nincs kimenet; ugyanaz a hatása, mint a `-dno-print-pages` opciónak.

    Példa: `lilypond -dbackend=svg fájlnév.ly`

  ‘`preview`’

    A fejléc és az első szisztéma fog szerepelni a kimenetben.

  ‘`print-pages`’

    Teljes oldalak generálása, ez az alapbeállítás. A `-dno-print-pages` opció a `-dpreview` opcióval együtt hasznos.

`-h, --help`

  Összegzés az alkalmazás használatáról.

`-H, --header=mező`

  A megadott fejlécmező kiírása a ‘`fájlnév.mező`’ nevű fájlba.

`--include, -I=könyvtár`

  A könyvtár hozzáadása a bemeneti fájlok keresési útvonalához.

`-i, --init=fájl`

  Az inicializáló fájl beállítása a megadott fájlra. (Alapértelmezett: ‘`init.ly`’.)

`-o, --output=fájl`

  Kimeneti fájl megadása. A megfelelő kiterjesztés automatikusan hozzáfűzésre kerül (pl. `.pdf` PDF kimenet esetén).

`--ps`

  PostScript kimenet generálása.

`--png`

  Oldalanként egy-egy PNG kép létrehozása. Ez a `--ps` opció hatását vonja maga után. A kép DPI-ben mért felbontása (alapértelmezett értéke 110) a következőképpen állítható be:

  >     -dresolution=110

`--pdf`

  PDF generálása. A `--ps` opció hatását vonja maga után.

`-j, --jail=felhasználó,csoport,börtön,könyvtár`

  A `lilypond` futtatása ún. börtönben.

  A `--jail` opció egy rugalmasabb alternatíva a `-dsafe` módnál abban az esetben, amikor a LilyPond forrás megbízhatatlan forrásból származik, pl. amikor webszerveren keresztül érhető el a LilyPond szolgáltatásként.

  A `--jail` módban a `lilypond` gyökere a börtön lesz, mielőtt a fordítási folyamat elkezdődne. Ezután a LilyPond átvált a megadott felhasználóra, csoportra és könyvtárba. Ezáltal garantálható, hogy (legalábbis elméletben) lehetetlen kitörni a börtönből. A `--jail` mód csak akkor működik, ha a `lilypond` alkalmazást root felhasználóként futtatjuk. Ez általában biztonságosan történik, pl. a `sudo` parancs használatával.

  A börtön előkészítése egy bonyolult folyamat, mivel biztosítani kell, hogy a LilyPond a börtönben mindent megtaláljon, ami a fordításhoz szükséges. Egy tipikus előkészítés a következő lépésekből áll:

  Különálló fájlrendszer létrehozása

    A LilyPond számára létre kell hozni egy fájlrendszert, amelyet a biztonságos `noexec`, `nodev` és `nosuid` opciókkal tudunk felcsatolni. Így lehetetlen a LilyPondból programokat futtatni vagy közvetlenül eszközökre írni. Ha egy külön partíció létrehozása nem kívánatos, egy elegendően nagy fájl létrehozása és loop eszközként való használata is megfelelő. A külön fájlrendszer azt is megelőzi, hogy a LilyPond többet írjon a lemezre, mint amennyi megengedett.

  Különálló felhasználó létrehozása

    Egy, kevés jogosultsággal rendelkező (pl. `lily`/`lily` nevű) felhasználó és csoport nevében kell, hogy fusson a LilyPond. Ennek a felhasználónak csak egy könyvtárhoz lehet írási joga, amit a könyvtár paraméterben kell megadni.

  A börtön előkészítése

    A LilyPond futásához szükséges összes fájlt be kell másolni a börtönbe, megtartva az eredeti elérési utakat. Az egész LilyPond telepítés (pl. a ‘`/usr/share/lilypond`’ könyvtár tartalmának) másolása szükséges.

    Ha mégis probléma lépne fel, a forrását legegyszerűbben az `strace` paranccsal határolhatjuk be, amellyel meghatározható, hogy mely fájlok hiányoznak.

  A LilyPond futtatása

    A `noexec` kapcsolóval csatolt börtönben lehetetlen külső programot futtatni. Így csak olyan kimeneti formátumok érhetőek el, amelyek ezt nem igénylik. Mint már említettük, superuser privilégiumokkal kell futtatni a LilyPondot (amelyeket természetesen egyből elveszít), lehetőleg `sudo` használatával. Ajánlott a LilyPond által elfoglalt processzoridő korlátozása (pl. az `ulimit -t` parancs segítségével), illetve a memóriafoglalásáé is.

`-v, --version`

  Verzióinformáció kijelzése.

`-V, --verbose`

  Bőbeszédűség bekapcsolása: az összes beolvasott fájl elérési útjának, futásidőknek és egyéb információknak a kijelzése.

`-w, --warranty`

  A GNU LilyPond garanciavállalásának kijelzése. (A LilyPond fejlesztői SEMMIFÉLE GARANCIÁT nem vállalnak!)

### Környezeti változók

A `lilypond` a következő környezeti változókat veszi figyelembe:

`LILYPOND_DATADIR`

  Annak a könyvtárnak a megadására szolgál, ahol a LilyPond üzeneteit és adatfájljait keresni fogja. Tartalmaznia kell a szükséges alkönyvtárakat (‘`ly/`’, ‘`ps/`’, ‘`tex/`’ stb.).

`LANG`

  A program kimeneti üzeneteinek nyelve.

`LILYPOND_GC_YIELD`

  A program memóriaigénye és futásideje közötti finomhangolást lehet elvégezni ezzel a változóval. Százalékos érték; minél nagyobb, annál több memóriát használ a program, minél alacsonyabb, annál több processzoridőt. Az alapértelmezett érték `70`.

### Lábjegyzet

[1] A GUILE megelőző állapota nem áll vissza feldolgozás után, így elővigyázatosnak kell lenni, hogy ne változtassuk meg a rendszer alapbeállításait Scheme kódból.

#### LilyPond — Használat v2.22.2 (stable-branch).