FreeBSD 文件計畫入門書
Prev | Chapter 7 The Documentation Build Process | Next

# 7.2 Understanding Makefiles in the Documentation tree

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

## 7.2.1 Subdirectory Makefiles

These `Makefile`s 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.

## 7.2.2 Documentation Makefiles

These `Makefile`s 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.sgml

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

> Note: We covered optional variable assignments in the previous section.

The `DOC_PREFIX` and include statements should be familiar already.

Prev | Home | Next
The Documentation Build Process | Up | FreeBSD Documentation Project make includes

本文及其他文件，可由此下載：ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/。

若有 FreeBSD 方面疑問，請先閱讀 FreeBSD 相關文件，如不能解決的話，再洽詢 <questions@FreeBSD.org>。
關於本文件的問題，請洽詢 <doc@FreeBSD.org>。