7.2. Понимание make-файлов в дереве документации

7.2.1. Make-файлы в подкаталоге

Эти Makefile обычно имеют такой вид:

SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

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

Обзорно, первые четыре непустые строчки задают make-переменные, SUBDIR, COMPAT_SYMLINK и DOC_PREFIX.

Первая декларация SUBDIR, как и COMPAT_SYMLINK, показывает, как присваивать значение переменной, переопределяя все ранее определенные значения.

Вторая инструкция SUBDIR показывает, как значение добавляется к текущему значению переменной. Значение переменной SUBDIR теперь соответствует articles books.

Присвоение DOC_PREFIX показывает, как значение присваивается переменной, но только если оно еще не определено. Это полезно, если DOC_PREFIX не соответствует тому, что полагает об этом Makefile - пользователь может переопределить это значение и дать правильное значение.

Так что все это значит? SUBDIR определяет, в какие вложенные подкаталоги должна быть передана работа по построению.

COMPAT_SYMLINK касается исключительно символических ссылок для достижения совместимости (достаточно удивительно) языков с их официальной кодировкой (doc/en должна указывать на en_US.ISO-8859-1).

DOC_PREFIX является маршрутом к корню дерева Проекта Документирования FreeBSD. Его не всегда легко найти и легко переопределить для достижения гибкости. .CURDIR является встроенной make-переменной, хранящей путь к текущему каталогу.

В последней строке включается системный make-файл doc.project.mk Проекта Документирования FreeBSD, доступный всем проектам, который является связующим звеном, преобразующим эти переменные во встроенные инструкции.

7.2.2. Make-файлы для документации

Эти make-файлы задают набор make-переменных, которые описывают, как построить документацию, расположенную в этом каталоге.

Вот пример:

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"

Переменная MAINTAINER очень важна. Эта переменная дает возможность указать владельца документа в Проекте Документирования FreeBSD, когда вы становитесь ответственным за его поддержку.

DOC является именем (предполагается расширение .sgml) главного документа, создаваемого в этом каталоге. В SRCS перечисляются все отдельные файлы, которые составляют документ. Сюда также должны быть включены важные файлы, изменение которых должно приводить к перестроению.

FORMATS указывает используемые по умолчанию форматы, которые применяются при построении этого документа. INSTALL_COMPRESSED является списком методов компрессии, которые должны использоваться при построении документа. INSTALL_ONLY_COMPRESS, пустая по умолчанию, должна быть непустой, если требуется построить только скомпрессированные документы.

Переменная DOC_PREFIX у включающие директивы должны быть вам уже известны.