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.

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ó.

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.24.4 (stable-branch).