| A FreeBSD Dokumentációs Projekt irányelvei kezdőknek | ||
|---|---|---|
| Előző | Fejezet 7. A dokumentáció előállításának folyamata | Következő |
Ezek az állományok legjobban talán önmagukon keresztül mutathatóak be. A következő rendszerszintű .mk állományokat használjuk a FreeBSD Dokumentációs Projektben:
A doc.project.mk a központi .mk állomány, amely szükség szerint hivatkozik az összes többi .mk állományra.
Az előállítás és a telepítés során a doc.subdir.mk felelős a dokumentumokat tároló könyvtárak bejárásért.
A doc.install.mk tartalmazza a karbantartóval és a telepítéssel kapcsolatos változókat.
A doc.docbook.mk állomány csak akkor kerül feldolgozásra, ha a DOCFORMAT értéke docbook és a DOC változónak van értéke.
Nézzünk bele:
DOCFORMAT?= docbook MAINTAINER?= [email protected] PREFIX?= /usr/local PRI_LANG?= en_US.ISO8859-1 .if defined(DOC) .if ${DOCFORMAT} == "docbook" .include "doc.docbook.mk" .endif .endif .include "doc.subdir.mk" .include "doc.install.mk"
Ha nem állítjuk be a dokumentum Makefile állományában, akkor a DOCFORMAT és a MAINTAINER változók ezen a helyen kapnak értéket.
A PREFIX adja azt a könyvtárat, amelyen belül elérhetőek a dokumentáció előállításához szükséges eszközök. A csomagok és portok átlagos használata esetén ez a /usr/local.
A PRI_LANG adja meg azt a nyelvet és kódolást, amely a dokumentációt olvasó felhasználó számára elsődlegesként leginkább elfogadott. Alapértelmezés szerint ez az amerikai angol.
Megjegyzés: A PRI_LANG változó semmilyen hatással nincs a dokumentumok előállítására. Egyedül a FreeBSD dokumentáció telepítésekor a leggyakrabban hivatkozott dokumentumokhoz létrehozandó szimbolikus linkek készítésénel van szerepe.
A .if defined(DOC) sorban a Makefile állományokban megadható elágazásokra láthatunk példát. Hasonlóan más programokhoz, a Makefile működését tudjuk meghatározni egy logikai kifejezés igazságértéktől függően. Ebben a kifejezésben a defined függvény, amely megadja, hogy a paramétereként megadott változó definiált-e.
A következő elágazásban, vagyis az .if ${DOCFORMAT} == "docbook" utasításban azt vizsgáljuk meg, hogy a DOCFORMAT változó értéke "docbook" vagy sem. Amennyiben a válasz erre igen (vagyis “igaz”), beemeljük a doc.docbook.mk tartalmát.
Az előbb említett két elágazást rendre az .endif kulcsszóval zárjuk le.
Ez az állomány már túlságosan nagy ahhoz, hogy a fejezeten belül könnyen ki lehessen elemezni. Ezért az előző szakaszok alapján a részleteket a kedves Olvasóra bízzuk, ehhez adunk még itt némi segítséget.
A SUBDIR tartalmazza azokat az alkönyvtárakat, amelyeket a feldolgozás során be kell járnunk.
A ROOT_SYMLINKS a dokumentáció főkönyvtárából szimbolikusan linkelendő könyvtárak neveit adja meg, amennyiben az adott nyelv (a PRI_LANG változó szerint) az elsődleges.
A COMPAT_SYMLINK változót már korábban bemutattuk az alkönyvtári Makefile állományok című szakaszban.
A függőségi viszonyokat cél: függőség1 függőség2 ... formában írjuk fel, ahol így megmondjuk, hogy a cél létrehozásához először milyen elemeknek kell létezniük. Ezeket nevezzük függőségeknek.
A függőségi viszony megadása alatt lehetőségünk van részletezni a függőségekből a cél előállításához szükséges utasításokat. Ezt akkor kell megtenni, ha a cél és a függőségek közti átalakítást előzőleg még nem definiáltuk, vagy ha az adott esetben az átalakítás eltér a korábbiaktól.
A .USE nevű speciális függőség egy makróval egyenértékű eszköz használatára ad lehetőséget.
_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===> ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} && \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endforA fenti kódrészletben tehát a _SUBDIRUSE most már egy “makró” lesz, amely ha megjelenik a függőségek között, akkor a törzsében megadott parancsokat hajtja végre.
Mi különbözteti meg ezt a makrót a többi céltól? Két lényeges eltérés: először is, a benne megadott utasítások a rá függőségként hivatkozó célhoz társított átalakítást végző utasítások után fognak lefutni, másrészt nem befolyásolja a jelenleg feldolgozás alatt álló cél nevét tároló .TARGET változó értékét.
clean: _SUBDIRUSE
rm -f ${CLEANFILES}Ebben a kódrészletben a tehát clean esetében csak az rm -r ${CLEANFILES} parancs lefutása után fog végrehajtódni a _SUBDIRUSE makró tartalma. Ennek hatására a clean megy egyre lentebb és lentebb a könyvtárszerkezetben, miközben törli a előzőleg előállított állományokat.
Az install és a package célok egyaránt folyamatosan haladnak lefelé a könyvtárszerkezetben és az alkönyvtárakban hívják saját maguk tényleges változatát (ezek a realinstall és realpackage).
A clean eltávolítja a folyamat során keletkezett állományokat (és az előbbiekhez hasonlóan lefele halad a könyvtárszerkezetben). A cleandir ugyanezt csinálja, de ha talál a tárgykódokhoz tartozó könyvtárat, akkor azt is törli.
Az exists egy másik logikai függvény, amellyel lekérdezhetjük, hogy a paramétereként megadott állomány létezik-e.
Az empty logikai függvény igaz értékű, ha a paramétereként megadott változó értéke üres.
A target logikai függvény igaz értékű, ha a paraméterként megadott cél még nem létezik.
A .for utasítás segítségével adott utasításokat tudunk elvégezni egy változó tartalmaként megadott, szóközökkel határolt elemekre. A ciklus belsejében egy változóból érhetjük el az aktuálisan feldolgozott elemet.
_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@${ECHO} "===> ${DIRPRFX}${entry}"
@(cd ${.CURDIR}/${entry} && \
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endforA fenti kódrészletben ha a SUBDIR üres, akkor nem történik semmi. Ha viszont egy vagy több elemet is tartalmaz, akkor a .for és az .endfor között megadott utasítások megismétlődnek minden egyes elem esetén. Ezek értékét a ciklus belsejében rendre a entry változóban veszi fel.
Ha kérdése van a FreeBSD-vel kapcsolatban, a következő
címre írhat (angolul): <[email protected]>.
Ha ezzel a dokumentummal kapcsolatban van kérdése,
kérjük erre a címre írjon: <[email protected]>.