7.2. Die Makefiles des Dokumentationsbaums verstehen

7.2.1. Unterverzeichnis-Makefiles

Derartige Makefiles sind in der Regel wie folgt aufgebaut:

SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

Die ersten vier nicht-leeren Zeilen definieren die make-Variablen SUBDIR, COMPAT_SYMLINK, und DOC_PREFIX.

Die erste SUBDIR-Anweisung weist (ebenso wie die COMPAT_SYMLINK-Anweisung) einer Variable einen Wert zu und überschreibt dabei deren ursprünglichen Wert.

Die zweite SUBDIR-Anweisung zeigt, wie man den aktuellen Wert einer Variable ergänzen kann. Nach der Ausführung dieser Anweisung hat die Variable SUBDIR den Wert articles books.

Die Anweisung DOC_PREFIX zweigt, wie man einer Variable einen Wert zuweist (vorausgesetzt, die Variable ist nicht bereits definiert). Eine derartige Anweisung ist beispielsweise sinnvoll, wenn sich DOC_PREFIX nicht dort befindet, wo es vom Makefile erwartet wird. Durch das Setzen dieser Variable kann der korrekte Wert an das Makefile übergeben werden.

Was heißt dies nun konkret? Mit den SUBDIR-Anweisungen legen Sie fest, welche Unterverzeichnisse beim Bau der Dokumentation eingeschlossen werden müssen.

COMPAT_SYMLINK wird zur Erstellung von symbolischen Links zwischen den jeweiligen Dokumentsprachen und deren offizieller Kodierung benötigt (so wird beispielsweise doc/en nach en_US.ISO-8859-1 verlinkt).

DOC_PREFIX gibt den Pfad zum Wurzelverzeichnis des Quellcode-Baums des FreeBSD Documentation Projects an. Diese Vorgabe kann jederzeit durch einen eigenen Wert ersetzt werden. Bei .CURDIR handelt es sich um eine in make eingebaute Variable, die den Pfad des aktuellen Verzeichnisses enthält.

Die letzte Zeile bindet doc.project.mk, die zentrale, projektweite make-Datei des FreeBSD Documentation Projects, in den Bau ein. Diese Datei enthält den "Klebstoff", der die diversen Variablen in Anweisungen zum Bau der Dokumentation konvertiert.

7.2.2. Dokument-Makefiles

Diese Makefiles definieren diverse make-Variablen mit Vorgaben zum Bau der im Verzeichnis enthaltenen Dokumentation.

Dazu ein Beispiel:

MAINTAINER=nik@FreeBSD.org

DOC?= book

FORMATS?= html-split html

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# SGML content
SRCS=  book.xml

DOC_PREFIX?= ${.CURDIR}/../../..

.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

Die Variable MAINTAINER ist von zentraler Bedeutung. Sie legt fest, wer für ein bestimmtes Dokument des FreeBSD Documentation Projects verantwortlich ist.

DOC (ohne die Erweiterung .xml) ist der Name des Hauptdokuments des Verzeichnisses, in dem sich das Makefile befindet. Mit SRCS-Anweisungen geben Sie alle Dokumente an, aus denen das Dokument besteht. Zusätzlich binden Sie damit wichtige Dateien ein, deren Änderung einen erneuten Bau der Dokumentation erforderlich macht.

Mit FORMATS geben Sie an, in welchen Formaten die Dokumentation gebaut werden soll. INSTALL_COMPRESSED enthält die Standardvorgaben, die beim Bau komprimierter Pakte der Dokumentation verwendet werden sollen. Der Variable INSTALL_ONLY_COMPRESS (die in der Voreinstellung leer ist) wird nur dann ein Wert zugewiesen, wenn ausschließlich komprimierte Pakete der Dokumentation erstellt werden sollen.

Die Variable DOC_PREFIX und die verschiedenen Include-Anweisungen sollten Ihnen ebenfalls bereits vertraut sein.