7.2 Entendendo Makefiles na árvore da documentação

7.2.1 Makefiles de Subdiretórios

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.

7.2.2 Makefiles de Documentação

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.

Você também já deve estar familiarizado com a atribuição da variável DOC_PREFIX e com as instruções de include.