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
documents that are 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"The first four non-empty lines define the make(1)
variables SUBDIR,
COMPAT_SYMLINK, and
DOC_PREFIX.
The SUBDIR statement and
COMPAT_SYMLINK statement show 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.
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(1)
builtin variable with the path to the current
directory.
The final line includes the FreeBSD Documentation Project's
project-wide make(1) system file
doc.project.mk which is the glue which
converts these variables into build instructions.
These Makefiles set make(1)
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 allows
committers to claim ownership of a document in the FreeBSD
Documentation Project, and take 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.
The DOC_PREFIX and include statements
should be familiar already.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.