There are three main types of Makefiles
in the FreeBSD Documentation Project tree.
Subdirectory
Makefiles simply pass
commands to those directories below them.
Documentation
Makefiles describe the
document(s) that should be produced from this directory.
Make
includes are the glue that perform the document production,
and are usually of the form
doc.xxx.mk.
These Makefiles usually take the form of:
SUBDIR =articles
SUBDIR+=books
COMPAT_SYMLINK = en
DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"In quick summary, the first four non-empty lines define the
make variables,
SUBDIR, COMPAT_SYMLINK,
and DOC_PREFIX.
The first SUBDIR statement, as well as
the COMPAT_SYMLINK statement, shows how to
assign a value to a variable, overriding any previous
value.
The second SUBDIR statement shows how a
value is appended to the current value of a variable. The
SUBDIR variable is now articles
books.
The DOC_PREFIX assignment shows how a
value is assigned to the variable, but only if it is not already
defined. This is useful if DOC_PREFIX is not
where this Makefile thinks it is - the user
can override this and provide the correct value.
Now what does it all mean? SUBDIR
mentions which subdirectories below this one the build process
should pass any work on to.
COMPAT_SYMLINK is specific to
compatibility symlinks (amazingly enough) for languages to their
official encoding (doc/en would point to
en_US.ISO-8859-1).
DOC_PREFIX is the path to the root of the
FreeBSD Document Project tree. This is not always that easy to
find, and is also easily overridden, to allow for flexibility.
.CURDIR is a make
builtin variable with the path to the current directory.
The final line includes the FreeBSD Documentation Project's
project-wide make system file
doc.project.mk which is the glue which
converts these variables into build instructions.
These Makefiles set a bunch of
make variables that describe how to
build the documentation contained in that directory.
Here is an example:
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"The MAINTAINER variable is a very
important one. This variable provides the ability to claim
ownership over a document in the FreeBSD Documentation
Project, whereby you gain the responsibility for maintaining
it.
DOC is the name (sans the
.xml extension) of the main document
created by this directory. SRCS lists all
the individual files that make up the document. This should
also include important files in which a change should result
in a rebuild.
FORMATS indicates the default formats
that should be built for this document.
INSTALL_COMPRESSED is the default list of
compression techniques that should be used in the document
build. INSTALL_ONLY_COMPRESS, empty by
default, should be non-empty if only compressed documents are
desired in the build.
We covered optional variable assignments in the previous section.
The DOC_PREFIX and include statements
should be familiar already.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.