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ő

# 7.3. A FreeBSD Dokumentációs Projekt `.mk` állományai

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.

## 7.3.1. A `doc.project.mk` állomány

Nézzünk bele:

    DOCFORMAT?=	docbook
    MAINTAINER?=	doc@FreeBSD.org

    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"

### 7.3.1.1. Változók

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.

### 7.3.1.2. Elágazások

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.

## 7.3.2. A `doc.subdir.mk` állomány

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.

### 7.3.2.1. Változók

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

### 7.3.2.2. Célok és makrók

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}/ )
    .endfor

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

#### 7.3.2.2.1. Definiált célok

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

### 7.3.2.3. Bővebben a feltételes kifejezésekről

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

### 7.3.2.4. Ciklusszerverzési lehetőségek (`.for`)

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}/ )
    .endfor

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

Előző | Tartalom | Következő
A dokumentációt tároló könyvtárban található `Makefile` állományok | Fel | A honlap

Ha kérdése van a FreeBSD-vel kapcsolatban, a következő címre írhat (angolul): <freebsd-questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése, kérjük erre a címre írjon: <gabor@FreeBSD.org>.