Há três tipos principais de
Makefiles na árvore do projeto de
documentção do FreeBSD.
Os
Makefiles de subdiretório
simplesmente passam comandos para os diretórios
abaixo dele.
Os
Makefiles de
documentação descrevem o(s)
documento(s) que deve(m) ser produzido(s) a partir deste
diretório.
Os
Make includes são
os responsáveis pela produção do
documento, e geralmente possuem o nome no formato
doc.xxx.mk.
Estes Makefiles geralmente tem a
forma:
SUBDIR =articles
SUBDIR+=books
COMPAT_SYMLINK = en
DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"Resumidamente, as primeiras quatro
linhas não vazias definem as variáveis do
make, SUBDIR,
COMPAT_SYMLINK, e
DOC_PREFIX.
A primeira declaração da variável
SUBDIR, tanto quanto a
declaração da variável
COMPAT_SYMLINK,
mostra como atribuir um valor a uma variável,
sobrescrevendo qualquer valor anterior que a mesma
contenha.
A segunda declaração da variável
SUBDIR mostra como um valor é
adicionado ao valor atual de uma variável. A
variável SUBDIR agora é
composta por articles books.
A declaração do
DOC_PREFIX mostra como um valor é
atribuído para uma variável, mas somente se
ela ainda não estiver definida. Isto é
útil se o DOC_PREFIX não
for onde este Makefile pensa que
é - o usuário pode cancelar e fornecer
o valor correto.
Agora o que tudo isso significa? O
SUBDIR lista quais subdiretórios
abaixo do atual devem ser incluídos no processo de
compilação durante a geração
do documento.
O COMPAT_SYMLINK é
específico para compatibilizar os links
simbólicos que ligam os idiomas a sua
codificação oficial (por exemplo o
doc/en deve apontar para
en_US.ISO-8859-1).
O DOC_PREFIX é o caminho para a
raíz da árvore do projeto de
documentação do FreeBSD. O qual nem sempre
é facil de encontrar, e que também pode ser
facilmente sobrescrito, para permitir flexibilidade. O
.CURDIR é uma variável
interna do make que contém
o caminho para o diretório atual.
A linha final inclui o arquivo principal do projeto de
documentação do FreeBSD, o
doc.project.mk, ele é o
responsável por converter estas variáveis em
instruções de compilação para
uso do make.
Estes Makefiles ajustam várias
variáveis do make as quais
descrevem como construir a documentação
contida em um determinado diretório.
Aqui está um exemplo:
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"A variável MAINTAINER é
uma muito importante. Esta variável fornece a
habilidade de reivindicar a propriedade sobre um documento no
projeto de documentação do FreeBSD, é
por meio dela que você recebe a responsabilidade de
mantê-lo.
DOC é o nome (sem a
extensão .xml) do principal
documento criado por este diretório. A variável
SRCS lista todos os arquivos individuais
que compõem o documento. Ela também deve
incluir os arquivos importantes, nos quais qualquer
mudança deve resultar em uma
reconstrução.
O FORMATS indica os formatos
nos quais o documento deve ser gerado por padrão.
O INSTALL_COMPRESSED contém a lista
padrão das técnicas de compressão que
devem ser usadas no documento depois que ele é gerado.
A variável INSTALL_ONLY_COMPRESS,
nula por padrão, deve ser definida para um valor
não nulo apenas se você desejar gerar
exclusivamente a versão compactada do documento.
Nós abordamos a atribuição das variáveis opcionais na seção anterior.
Você também já deve estar
familiarizado com a atribuição da
variável DOC_PREFIX e com as
instruções de include.
Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/
Para perguntas sobre FreeBSD, leia a
documentação antes de contatar
<questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para
<doc@FreeBSD.org>.