There are three main types of Makefile
s
in the FreeBSD Documentation Project tree.
Subdirectory
Makefile
s simply pass
commands to those directories below them.
Documentation
Makefile
s 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 Makefile
s usually take the form
of:
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 Makefile
s set a bunch of
make variables that describe how to
build the documentation contained in that directory.
Here is an example:
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.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.