Este capítulo descreve as convenções para escrever Makefiles destinados a programas GNU. Usar o Automake ajuda você a escrever um Makefile que segue essas convenções. Para mais informações sobre Makefiles portáveis, consulte a especificação POSIX e a seção Portable Make Programming do manual Autoconf.
DESTDIR: suporte a instalações em etapasTodo Makefile deve conter a seguinte linha:
SHELL = /bin/sh
Isso evita problemas em sistemas onde a variável SHELL poderia ser herdada do ambiente. (Com o GNU make, esse problema nunca ocorre.)
Diferentes programas make têm listas de sufixos e regras implícitas mutuamente incompatíveis, e às vezes isso gera confusão ou mau funcionamento. Por isso, é uma boa ideia definir explicitamente a lista de sufixos usando apenas os sufixos de que aquele Makefile precisa, assim:
.SUFFIXES: .SUFFIXES: .c .o
A primeira linha esvazia a lista de sufixos, e a segunda introduz todos os sufixos que podem ser objeto de regras implícitas neste Makefile.
Não presuma que . (o diretório atual) esteja no caminho de execução dos comandos. Quando você precisar executar, durante o make, programas que fazem parte do seu pacote, certifique-se de usar ./ se o programa for compilado como parte do make, ou $(srcdir)/ se o arquivo for uma parte imutável do código fonte. Sem um desses prefixos, será usado o caminho de busca vigente naquele momento.
A distinção entre ./ (o diretório de compilação) e $(srcdir)/ (o diretório fonte) é importante, porque os usuários podem compilar em um diretório separado usando a opção «--srcdir» do configure. Uma regra da forma:
foo.1 : foo.man sedscript
sed -f sedscript foo.man > foo.1
falha quando o diretório de compilação não é o diretório fonte, porque foo.man e sedscript estão no diretório fonte.
Ao usar o GNU make, confiar no «VPATH» para localizar o arquivo fonte funciona no caso em que há um único arquivo de dependência, pois a variável automática «$<» do make representa o arquivo fonte onde quer que ele esteja. (Muitas versões do make definem «$<» apenas em regras implícitas.) Ou seja, um alvo de Makefile como
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
deve, em vez disso, ser escrito como
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
para permitir que o «VPATH» funcione corretamente. Quando o alvo tem múltiplas dependências, usar explicitamente «$(srcdir)» é a maneira mais simples de fazer a regra funcionar bem. Por exemplo, o alvo de foo.1 mostrado acima é mais bem escrito assim:
foo.1 : foo.man sedscript
sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
As distribuições GNU normalmente contêm alguns arquivos que não são arquivos fonte — por exemplo, arquivos Info e a saída do Autoconf, Automake, Bison ou Flex. Como esses arquivos normalmente aparecem no diretório fonte, eles devem sempre aparecer no diretório fonte, e não no diretório de compilação. Portanto, as regras de Makefile que os atualizam devem colocar os arquivos atualizados no diretório fonte.
No entanto, para um arquivo que não conste da distribuição, o Makefile não deve colocá-lo no diretório fonte, pois compilar um programa em circunstâncias normais não deve modificar o diretório fonte de forma alguma.
Procure fazer com que pelo menos os alvos de compilação e de instalação (e todos os seus subalvos) funcionem corretamente com um make paralelo.
Escreva os comandos do Makefile (e quaisquer scripts de shell, como o configure) para rodar sob sh (tanto o Bourne shell tradicional quanto o shell POSIX), e não sob csh. Não use recursos especiais do ksh ou do bash, nem recursos POSIX que não sejam amplamente suportados pelo Bourne sh tradicional.
O script configure e as regras de Makefile para compilação e instalação não devem usar diretamente nenhum utilitário além destes:
awk cat cmp cp diff echo expr false grep install-info ln ls mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
Programas de compressão como o gzip podem ser usados na regra dist.
De modo geral, atenha-se às opções e recursos amplamente suportados (normalmente especificados pelo POSIX) desses programas. Por exemplo, não use «mkdir -p», por mais conveniente que seja, porque alguns poucos sistemas não o suportam de forma alguma e, em outros, ele não é seguro para execução paralela. Para uma lista de incompatibilidades conhecidas, consulte a seção Portable Shell Programming do manual Autoconf.
É prudente evitar criar links simbólicos em makefiles, pois alguns poucos sistemas de arquivos não os suportam.
As regras de Makefile para compilação e instalação também podem usar compiladores e programas relacionados, mas devem fazê-lo por meio de variáveis do make, para que o usuário possa substituí-los por alternativas. Eis alguns dos programas a que nos referimos:
ar bison cc flex install ld ldconfig lex make makeinfo ranlib texi2dvi yacc
Use as seguintes variáveis do make para executar esses programas:
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
Ao usar ranlib ou ldconfig, certifique-se de que nada de ruim aconteça se o sistema não tiver o programa em questão. Faça com que um erro desse comando seja ignorado e exiba uma mensagem antes do comando para informar ao usuário que a falha desse comando não significa um problema. (A macro «AC_PROG_RANLIB» do Autoconf pode ajudar nisso.)
Se você usar links simbólicos, deve implementar uma alternativa (fallback) para sistemas que não têm links simbólicos.
Outros utilitários que podem ser usados por meio de variáveis do Make são:
chgrp chmod chown mknod
Em partes do Makefile (ou scripts) destinadas apenas a sistemas específicos onde você sabe que esses utilitários existem, não há problema em usar outros utilitários.
Os Makefiles devem fornecer variáveis que permitam sobrepor determinados comandos, opções e afins.
Em particular, você deve executar a maioria dos programas utilitários por meio de variáveis. Assim, se você usar o Bison, tenha uma variável chamada BISON cujo valor padrão seja definido com «BISON = bison», e refira-se a ela com $(BISON) sempre que precisar usar o Bison.
Utilitários de gerenciamento de arquivos como ln, rm e mv não precisam ser referenciados por meio de variáveis dessa forma, pois os usuários não precisam substituí-los por outros programas.
Cada variável de nome de programa deve vir acompanhada de uma variável de opções, usada para fornecer opções ao programa. Acrescente «FLAGS» ao final do nome da variável de nome de programa para obter o nome da variável de opções — por exemplo, BISONFLAGS. (Os nomes CFLAGS para o compilador C, YFLAGS para o yacc e LFLAGS para o lex são exceções a essa regra, mas os mantemos porque são padrão.) Use CPPFLAGS em qualquer comando de compilação que execute o pré-processador, e use LDFLAGS em qualquer comando de compilação que faça a ligação (linking), bem como em qualquer uso direto do ld.
Se houver opções do compilador C que precisem ser usadas para a compilação correta de determinados arquivos, não as inclua em CFLAGS. Os usuários esperam poder especificar CFLAGS livremente por conta própria. Em vez disso, providencie para passar as opções necessárias ao compilador C independentemente de CFLAGS, escrevendo-as explicitamente nos comandos de compilação ou definindo uma regra implícita, assim:
CFLAGS = -g
ALL_CFLAGS = -I. $(CFLAGS)
.c.o:
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
Você pode incluir a opção «-g» em CFLAGS, porque ela não é obrigatória para a compilação correta. Você pode considerá-la um padrão apenas recomendado. Se o pacote estiver configurado para ser compilado com o GCC por padrão, então você também pode incluir «-O» no valor padrão de CFLAGS.
Coloque CFLAGS por último no comando de compilação, depois das outras variáveis que contêm opções do compilador, para que o usuário possa usar CFLAGS para sobrepor as demais.
CFLAGS deve ser usado em toda invocação do compilador C, tanto nas que fazem compilação quanto nas que fazem ligação.
Todo Makefile deve definir a variável INSTALL, que é o comando básico para instalar um arquivo no sistema.
Todo Makefile também deve definir as variáveis INSTALL_PROGRAM e INSTALL_DATA. (O padrão de INSTALL_PROGRAM deve ser $(INSTALL); o padrão de INSTALL_DATA deve ser ${INSTALL} -m 644.) Em seguida, deve usar essas variáveis como os comandos para a instalação propriamente dita: a primeira para arquivos executáveis e a segunda para arquivos não executáveis. O uso mínimo dessas variáveis é o seguinte:
$(INSTALL_PROGRAM) foo $(bindir)/foo $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
No entanto, é preferível permitir um prefixo DESTDIR nos arquivos de destino, como explicado na próxima seção.
Também é aceitável (mas não obrigatório) instalar vários arquivos em um único comando, sendo o último argumento um diretório, como em:
$(INSTALL_PROGRAM) foo bar baz $(bindir)
DESTDIR: suporte a instalações em etapas
DESTDIR é uma variável que se antepõe a cada arquivo de destino instalado, assim:
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
A variável DESTDIR é especificada pelo usuário na linha de comando do make como um nome de arquivo absoluto. Por exemplo:
make DESTDIR=/tmp/stage install
DESTDIR deve ser suportado apenas nos alvos install* e uninstall*, pois são os únicos alvos em que ele é útil.
Se o seu passo de instalação normalmente instalasse /usr/local/bin/foo e /usr/local/lib/libfoo.a, então uma instalação invocada como no exemplo acima instalaria, em vez disso, /tmp/stage/usr/local/bin/foo e /tmp/stage/usr/local/lib/libfoo.a.
Antepor a variável DESTDIR a cada alvo dessa forma possibilita as instalações em etapas (staged installs), nas quais os arquivos instalados não são colocados diretamente em seu local esperado, mas sim copiados para um local temporário (DESTDIR). Ainda assim, os arquivos instalados mantêm sua estrutura de diretórios relativa, e quaisquer nomes de arquivo embutidos não são modificados.
Você não deve definir o valor de DESTDIR no seu Makefile de modo algum; assim, por padrão, os arquivos são instalados em seus locais esperados. Além disso, especificar DESTDIR não deve alterar o funcionamento do software de forma alguma, portanto seu valor não deve ser incluído no conteúdo de nenhum arquivo.
O suporte a DESTDIR é comumente usado na criação de pacotes. Também é útil para usuários que querem entender o que um dado pacote vai instalar e onde, e para permitir que usuários que normalmente não têm permissão para instalar em áreas protegidas compilem e instalem antes de obter essas permissões. Por fim, ele pode ser útil com ferramentas como o stow, em que o código é instalado em um lugar, mas feito parecer instalado em outro por meio de links simbólicos ou operações especiais de montagem. Por isso, embora não seja um requisito absoluto, recomendamos enfaticamente que os pacotes GNU suportem DESTDIR.
Os diretórios de instalação devem sempre ser nomeados por variáveis, para que seja fácil instalar em um local não padrão. Os nomes padrão dessas variáveis e os valores que elas devem ter nos pacotes GNU são descritos a seguir. Eles se baseiam em um layout padrão de sistema de arquivos, cujas variantes são usadas no GNU/Linux e em outros sistemas operacionais modernos.
Espera-se que os instaladores sobreponham esses valores ao chamar o make (por exemplo, make prefix=/usr install) ou o configure (por exemplo, configure --prefix=/usr). Os pacotes GNU não devem tentar adivinhar qual valor seria apropriado para essas variáveis no sistema em que estão sendo instalados: use as configurações padrão especificadas aqui, para que todos os pacotes GNU se comportem de forma idêntica, permitindo que o instalador obtenha o layout desejado.
Todos os diretórios de instalação, e seus diretórios pais, devem ser criados (se necessário) antes de se instalar neles.
Estas duas primeiras variáveis definem a raiz da instalação. Todos os demais diretórios de instalação devem ser subdiretórios de um desses dois, e nada deve ser instalado diretamente nesses dois diretórios.
prefixUm prefixo usado para construir os valores padrão das variáveis listadas abaixo. O valor padrão de prefix deve ser /usr/local. Ao compilar o sistema GNU completo, o prefixo será vazio e /usr será um link simbólico para /. (Se você estiver usando o Autoconf, escreva-o como «@prefix@».)
Executar «make install» com um valor de prefix diferente daquele usado para compilar o programa não deve recompilar o programa.
exec_prefixUm prefixo usado para construir os valores padrão de algumas das variáveis listadas abaixo. O valor padrão de exec_prefix deve ser $(prefix). (Se você estiver usando o Autoconf, escreva-o como «@exec_prefix@».)
De modo geral, $(exec_prefix) é usado para diretórios que contêm arquivos específicos da máquina (como executáveis e bibliotecas de sub-rotinas), enquanto $(prefix) é usado diretamente para os demais diretórios.
Executar «make install» com um valor de exec_prefix diferente daquele usado para compilar o programa não deve recompilar o programa.
Os programas executáveis são instalados em um dos diretórios a seguir.
bindirO diretório para instalar programas executáveis que os usuários podem executar. Normalmente isso é /usr/local/bin, mas escreva-o como $(exec_prefix)/bin. (Se você estiver usando o Autoconf, escreva-o como «@bindir@».)
sbindirO diretório para instalar programas executáveis que podem ser executados a partir do shell, mas que em geral só são úteis para administradores de sistema. Normalmente isso é /usr/local/sbin, mas escreva-o como $(exec_prefix)/sbin. (Se você estiver usando o Autoconf, escreva-o como «@sbindir@».)
libexecdirO diretório para instalar programas executáveis a serem executados por outros programas, e não por usuários. Normalmente esse diretório é /usr/local/libexec, mas escreva-o como $(exec_prefix)/libexec. (Se você estiver usando o Autoconf, escreva-o como «@libexecdir@».)
A definição de «libexecdir» é a mesma para todos os pacotes, então você deve instalar seus dados em um subdiretório dele. A maioria dos pacotes instala seus dados sob $(libexecdir)/package-name/, possivelmente em subdiretórios adicionais dele (por exemplo, $(libexecdir)/package-name/machine/version).
Os arquivos de dados usados pelo programa durante sua execução são classificados de duas maneiras.
Isso gera seis possibilidades diferentes. No entanto, queremos desencorajar o uso de arquivos dependentes de arquitetura, além de arquivos objeto e bibliotecas. É muito mais limpo tornar os demais arquivos de dados independentes de arquitetura, e em geral isso não é difícil.
Eis as variáveis que os Makefiles devem usar para especificar os diretórios onde colocar esses vários tipos de arquivos:
A raiz da árvore de diretórios para arquivos de dados somente leitura e independentes de arquitetura. Normalmente isso é /usr/local/share, mas escreva-o como $(prefix)/share. (Se você estiver usando o Autoconf, escreva-o como «@datarootdir@».) O valor padrão de «datadir» baseia-se nesta variável; o mesmo vale para «infodir», «mandir» e outros.
O diretório para instalar arquivos de dados somente leitura, independentes de arquitetura e específicos deste programa. Costuma ser o mesmo local que «datarootdir», mas usamos as duas variáveis separadas para que você possa mover esses arquivos específicos do programa sem alterar a localização dos arquivos Info, das páginas de manual etc.
Normalmente isso é /usr/local/share, mas escreva-o como $(datarootdir). (Se você estiver usando o Autoconf, escreva-o como «@datadir@».)
A definição de «datadir» é a mesma para todos os pacotes, então você deve instalar seus dados em um subdiretório dele. A maioria dos pacotes instala seus dados sob $(datadir)/package-name/.
O diretório para instalar arquivos de dados somente leitura que dizem respeito a uma única máquina — ou seja, arquivos para configurar um host. Arquivos de configuração de programas de correio e de rede, /etc/passwd etc. pertencem aqui. Todos os arquivos neste diretório devem ser arquivos de texto ASCII comuns. Normalmente isso é /usr/local/etc, mas escreva-o como $(prefix)/etc. (Se você estiver usando o Autoconf, escreva-o como «@sysconfdir@».)
Não instale executáveis neste diretório (eles provavelmente pertencem a $(libexecdir) ou $(sbindir)). Também não instale arquivos que sejam modificados no curso normal de seu uso (excetuados os programas cujo propósito é alterar a configuração do sistema). Esses provavelmente pertencem a $(localstatedir).
O diretório para instalar arquivos de dados independentes de arquitetura que os programas modificam enquanto são executados. Normalmente isso é /usr/local/com, mas escreva-o como $(prefix)/com. (Se você estiver usando o Autoconf, escreva-o como «@sharedstatedir@».)
O diretório para instalar arquivos de dados que os programas modificam enquanto são executados e que dizem respeito a uma máquina específica. Os usuários nunca devem precisar modificar arquivos neste diretório para configurar o funcionamento do pacote; coloque tais informações de configuração em arquivos separados, em $(datadir) ou $(sysconfdir). $(localstatedir) normalmente é /usr/local/var, mas escreva-o como $(prefix)/var. (Se você estiver usando o Autoconf, escreva-o como «@localstatedir@».)
O diretório para instalar arquivos de dados que os programas modificam enquanto são executados, que dizem respeito a uma máquina específica e que não precisam persistir além da execução do programa — a qual geralmente é de longa duração, por exemplo, até a próxima reinicialização. Os arquivos PID de daemons de sistema são um uso típico. Além disso, este diretório não deve ser limpo, exceto talvez na reinicialização, ao passo que o /tmp geral (TMPDIR) pode ser limpo arbitrariamente. Normalmente isso é /var/run, mas escreva-o como $(localstatedir)/run. Tê-lo como uma variável separada permite usar /run, se desejado, por exemplo. (Se você estiver usando o Autoconf 2.70 ou posterior, escreva-o como «@runstatedir@».)
As variáveis a seguir especificam o diretório para instalar certos tipos específicos de arquivos, caso o seu programa os tenha. Todo pacote GNU deve ter arquivos Info, então todo programa precisa de «infodir», mas nem todos precisam de «libdir» ou «lispdir».
O diretório para instalar arquivos de cabeçalho a serem incluídos por programas de usuário com a diretiva de pré-processador «#include» do C. Normalmente isso é /usr/local/include, mas escreva-o como $(prefix)/include. (Se você estiver usando o Autoconf, escreva-o como «@includedir@».)
A maioria dos compiladores além do GCC não procura arquivos de cabeçalho no diretório /usr/local/include. Portanto, instalar os arquivos de cabeçalho dessa forma só é útil com o GCC. Às vezes isso não é um problema, pois algumas bibliotecas realmente se destinam a funcionar apenas com o GCC. Mas algumas bibliotecas se destinam a funcionar com outros compiladores. Elas devem instalar seus arquivos de cabeçalho em dois locais: um especificado por includedir e outro especificado por oldincludedir.
O diretório para instalar arquivos de cabeçalho «#include» para uso com compiladores que não sejam o GCC. Normalmente isso é /usr/include. (Se você estiver usando o Autoconf, pode escrevê-lo como «@oldincludedir@».)
Os comandos do Makefile devem verificar se o valor de oldincludedir está vazio. Se estiver, não devem tentar usá-lo; devem cancelar a segunda instalação dos arquivos de cabeçalho.
Um pacote não deve substituir um cabeçalho existente neste diretório, a menos que o cabeçalho tenha vindo do mesmo pacote. Assim, se o seu pacote Foo fornece um arquivo de cabeçalho foo.h, então ele deve instalar o arquivo de cabeçalho no diretório oldincludedir se (1) não houver nenhum foo.h ali ou (2) o foo.h que existe ali tiver vindo do pacote Foo.
Para saber se foo.h veio do pacote Foo, coloque uma string mágica no arquivo — como parte de um comentário — e procure por essa string com o grep.
O diretório para instalar os arquivos de documentação (que não sejam Info) deste pacote. Por padrão, deve ser /usr/local/share/doc/yourpkg, mas deve ser escrito como $(datarootdir)/doc/yourpkg. (Se você estiver usando o Autoconf, escreva-o como «@docdir@».) O subdiretório yourpkg (que pode incluir um número de versão) evita colisões entre arquivos de nomes comuns, como README.
O diretório para instalar os arquivos Info deste pacote. Por padrão, deve ser /usr/local/share/info, mas deve ser escrito como $(datarootdir)/info. (Se você estiver usando o Autoconf, escreva-o como «@infodir@».) infodir é separado de docdir por compatibilidade com a prática existente.
Diretórios para instalar arquivos de documentação no formato específico. Por padrão, todos devem ser definidos como $(docdir). (Se você estiver usando o Autoconf, escreva-os como «@htmldir@», «@dvidir@» etc.) Os pacotes que fornecem várias traduções de sua documentação devem instalá-las em «$(htmldir)/»ll, «$(pdfdir)/»ll etc., onde ll é uma abreviação de localidade como «en» ou «pt_BR».
O diretório para arquivos objeto e bibliotecas de código objeto. Não instale executáveis aqui; eles provavelmente devem ir para $(libexecdir) em vez disso. O valor de libdir normalmente é /usr/local/lib, mas escreva-o como $(exec_prefix)/lib. (Se você estiver usando o Autoconf, escreva-o como «@libdir@».)
O diretório para instalar quaisquer arquivos Emacs Lisp deste pacote. Por padrão, deve ser /usr/local/share/emacs/site-lisp, mas deve ser escrito como $(datarootdir)/emacs/site-lisp.
Se você estiver usando o Autoconf, escreva o padrão como «@lispdir@». Para fazer «@lispdir@» funcionar, você precisa das seguintes linhas no seu arquivo configure.ac:
lispdir='${datarootdir}/emacs/site-lisp'
AC_SUBST(lispdir)
O diretório para instalar os catálogos de mensagens específicos de localidade deste pacote. Por padrão, deve ser /usr/local/share/locale, mas deve ser escrito como $(datarootdir)/locale. (Se você estiver usando o Autoconf, escreva-o como «@localedir@».) Este diretório normalmente tem um subdiretório por localidade.
As páginas de manual no estilo Unix são instaladas em um dos seguintes:
O diretório de nível mais alto para instalar as páginas de manual (se houver) deste pacote. Normalmente será /usr/local/share/man, mas você deve escrevê-lo como $(datarootdir)/man. (Se você estiver usando o Autoconf, escreva-o como «@mandir@».)
O diretório para instalar as páginas de manual da seção 1. Escreva-o como $(mandir)/man1.
O diretório para instalar as páginas de manual da seção 2. Escreva-o como $(mandir)/man2.
Não faça da página de manual a documentação principal de qualquer software GNU. Em vez disso, escreva um manual em Texinfo. As páginas de manual existem apenas em benefício de quem executa software GNU no Unix, o que é apenas uma aplicação secundária.
A extensão de nome de arquivo da página de manual instalada. Deve conter um ponto seguido do dígito apropriado; normalmente deve ser «.1».
A extensão de nome de arquivo das páginas de manual da seção 1 instaladas.
A extensão de nome de arquivo das páginas de manual da seção 2 instaladas.
Use estes nomes em vez de «manext» se o pacote precisar instalar páginas de manual em mais de uma seção do manual.
E, por fim, você deve definir a seguinte variável:
O diretório dos arquivos fonte a serem compilados. O valor desta variável normalmente é inserido pelo script de shell configure. (Se você estiver usando o Autoconf, use «srcdir = @srcdir@».)
Por exemplo:
# Common prefix for installation directories. # NOTE: This directory must exist when you start the install. prefix = /usr/local datarootdir = $(prefix)/share datadir = $(datarootdir) exec_prefix = $(prefix) # Where to put the executable for the command 'gcc'. bindir = $(exec_prefix)/bin # Where to put the directories used by the compiler. libexecdir = $(exec_prefix)/libexec # Where to put the Info files. infodir = $(datarootdir)/info
Se o seu programa instalar um grande número de arquivos em um dos diretórios padrão especificados pelo usuário, pode ser útil agrupá-los em um subdiretório específico daquele programa. Se você fizer isso, deve escrever a regra install para criar esses subdiretórios.
Não espere que o usuário inclua o nome do subdiretório no valor de nenhuma das variáveis listadas acima. A ideia de ter um conjunto uniforme de nomes de variáveis para diretórios de instalação é permitir que o usuário especifique exatamente os mesmos valores para vários pacotes GNU diferentes. Para que isso seja útil, todos os pacotes devem ser projetados de modo a funcionar de forma sensata quando o usuário faz isso.
Por vezes, nem todas essas variáveis podem estar implementadas na versão atual do Autoconf e/ou do Automake; mas, a partir do Autoconf 2.60, acreditamos que todas estejam. Quando alguma estiver faltando, as descrições aqui servem como especificações do que o Autoconf deve implementar. Como programador, você pode usar uma versão de desenvolvimento do Autoconf ou evitar usar essas variáveis até que seja lançada uma versão estável que as suporte.
Todos os programas GNU devem ter os seguintes alvos em seus Makefiles:
Compila o programa inteiro. Este deve ser o alvo padrão. Este alvo não precisa regenerar nenhum arquivo de documentação; os arquivos Info normalmente devem ser incluídos na distribuição, e os arquivos DVI (e de outros formatos de documentação) devem ser gerados apenas quando solicitados explicitamente.
Por padrão, as regras do Make devem compilar e ligar com «-g», para que os programas executáveis tenham símbolos de depuração. Caso contrário, você fica essencialmente sem recursos diante de uma falha (crash), e muitas vezes não é nada fácil reproduzi-la com uma compilação nova.
Compila o programa e copia os executáveis, bibliotecas etc. para os nomes de arquivo onde devem residir para uso real. Se houver um teste simples para verificar se um programa foi instalado corretamente, este alvo deve executar esse teste.
Não faça strip (remoção de símbolos) dos executáveis ao instalá-los. Isso ajuda em uma eventual depuração que possa ser necessária mais tarde; além disso, hoje em dia o espaço em disco é barato e os carregadores dinâmicos normalmente garantem que as seções de depuração não sejam carregadas durante a execução normal. Os usuários que precisarem de binários com strip podem invocar o alvo install-strip para isso.
Se possível, escreva a regra do alvo install de modo que ela não modifique nada no diretório onde o programa foi compilado, desde que «make all» tenha acabado de ser executado. Isso é conveniente para compilar o programa com um nome de usuário e instalá-lo com outro.
Os comandos devem criar todos os diretórios nos quais os arquivos serão instalados, caso ainda não existam. Isso inclui os diretórios especificados como os valores das variáveis prefix e exec_prefix, bem como todos os subdiretórios necessários. Uma maneira de fazer isso é por meio de um alvo installdirs, descrito adiante.
Use «-» antes de qualquer comando que instale uma página de manual, para que o make ignore quaisquer erros. Isso é para o caso de haver sistemas que não têm o sistema de documentação de páginas de manual do Unix instalado.
A maneira de instalar arquivos Info é copiá-los para $(infodir) com $(INSTALL_DATA) (consulte Variáveis para especificar comandos) e, em seguida, executar o programa install-info se ele estiver presente. install-info é um programa que edita o arquivo dir do Info para adicionar ou atualizar a entrada de menu do arquivo Info informado; ele faz parte do pacote Texinfo.
Eis uma regra de exemplo para instalar um arquivo Info que também tenta lidar com algumas situações adicionais, como a ausência de install-info.
do-install-info: foo.info installdirs
$(NORMAL_INSTALL)
# Prefer an info file in . to one in srcdir.
if test -f foo.info; then d=.; \
else d="$(srcdir)"; fi; \
$(INSTALL_DATA) $$d/foo.info \
"$(DESTDIR)$(infodir)/foo.info"
# Run install-info only if it exists.
# Use 'if' instead of just prepending '-' to the
# line so we notice real errors from install-info.
# Use '$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
$(POST_INSTALL)
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
"$(DESTDIR)$(infodir)/foo.info"; \
else true; fi
Ao escrever o alvo install, você deve classificar todos os comandos em três categorias: os normais, os comandos de pré-instalação e os comandos de pós-instalação. Consulte Categorias de comandos de instalação.
Estes alvos instalam documentação em formatos diferentes de Info; destinam-se a ser chamados explicitamente pela pessoa que instala o pacote, caso esse formato seja desejado. O GNU prefere arquivos Info, então estes devem ser instalados pelo alvo install.
Quando você tiver muitos arquivos de documentação para instalar, recomendamos que evite colisões e desordem fazendo com que esses alvos instalem em subdiretórios do diretório de instalação apropriado, como htmldir. Como exemplo, se o seu pacote tem vários manuais e você deseja instalar documentação HTML com muitos arquivos (como o modo «dividido» gerado por makeinfo --html), certamente vai querer usar subdiretórios; caso contrário, dois nós com o mesmo nome em manuais diferentes sobrescreverão um ao outro.
Faça com que esses alvos install-format invoquem os comandos do alvo format, por exemplo, tornando format uma dependência.
Exclui todos os arquivos instalados — as cópias que os alvos «install» e «install-*» criam.
Esta regra não deve modificar os diretórios onde a compilação é feita, apenas os diretórios onde os arquivos são instalados.
Os comandos de desinstalação são divididos em três categorias, assim como os comandos de instalação. Consulte Categorias de comandos de instalação.
Como install, mas faz strip dos arquivos executáveis ao instalá-los. Em casos simples, este alvo pode usar o alvo install de forma simples:
install-strip:
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
install
Mas se o pacote instalar scripts além de executáveis reais, o alvo install-strip não pode simplesmente se referir ao alvo install; ele tem de fazer strip dos executáveis, mas não dos scripts.
install-strip não deve fazer strip dos executáveis no diretório de compilação que estão sendo copiados para instalação. Deve fazer strip apenas das cópias que são instaladas.
Normalmente não recomendamos fazer strip de um executável, a menos que você tenha certeza de que o programa não tem bugs. No entanto, pode ser razoável instalar um executável com strip para a execução real, guardando em outro lugar o executável sem strip para o caso de haver um bug.
Exclui todos os arquivos no diretório atual que normalmente são criados ao compilar o programa. Exclui também arquivos em outros diretórios, se forem criados por este makefile. No entanto, não exclua os arquivos que registram a configuração. Preserve também os arquivos que poderiam ser gerados pela compilação, mas que normalmente não são porque a distribuição já os traz. Não é necessário excluir os diretórios pais criados com «mkdir -p», pois eles poderiam já existir de qualquer forma.
Exclua aqui os arquivos .dvi se eles não fizerem parte da distribuição.
Exclui todos os arquivos no diretório atual (ou criados por este makefile) que são criados ao configurar ou compilar o programa. Se você desempacotou a fonte e compilou o programa sem criar nenhum outro arquivo, «make distclean» deve deixar apenas os arquivos que estavam na distribuição. No entanto, não é necessário excluir os diretórios pais criados com «mkdir -p», pois eles poderiam já existir de qualquer forma.
Semelhante a «clean», mas pode abster-se de excluir alguns poucos arquivos que as pessoas normalmente não querem recompilar. Por exemplo, o alvo «mostlyclean» do GCC não exclui libgcc.a, porque recompilá-lo raramente é necessário e leva muito tempo.
Exclui quase tudo que pode ser reconstruído com este Makefile. Isso normalmente inclui tudo que é excluído por distclean, além de muito mais: arquivos fonte C produzidos pelo Bison, tabelas de tags, arquivos Info e assim por diante.
Dizemos «quase tudo» por um motivo. Executar o comando «make maintainer-clean» não deve excluir configure, mesmo que configure possa ser refeito por uma regra no Makefile. De modo mais geral, «make maintainer-clean» não deve excluir nada que precise existir para se executar configure e então começar a compilar o programa. Além disso, não é necessário excluir os diretórios pais criados com «mkdir -p», pois eles poderiam já existir de qualquer forma. Essas são as únicas exceções; maintainer-clean deve excluir todo o resto que possa ser reconstruído.
O alvo «maintainer-clean» destina-se a ser usado por um mantenedor do pacote, e não por usuários comuns. Podem ser necessárias ferramentas especiais para reconstruir alguns dos arquivos que «make maintainer-clean» exclui. Como esses arquivos normalmente estão incluídos na distribuição, não nos preocupamos em torná-los fáceis de reconstruir. Se você precisar desempacotar a distribuição completa novamente, não nos culpe por isso.
Para ajudar a conscientizar os usuários disso, os comandos do alvo especial maintainer-clean devem começar com estas duas linhas:
@echo 'This command is intended for maintainers to use; it' @echo 'deletes files that may need special tools to rebuild.'
Atualiza uma tabela de tags para este programa.
Gera quaisquer arquivos Info necessários. A melhor maneira de escrever as regras é a seguinte:
info: foo.info
foo.info: foo.texi chap1.texi chap2.texi
$(MAKEINFO) $(srcdir)/foo.texi
Você deve definir a variável MAKEINFO no Makefile. Ela deve executar o programa makeinfo, que faz parte da distribuição Texinfo.
Normalmente, uma distribuição GNU vem com arquivos Info, o que significa que os arquivos Info estão presentes no diretório fonte. Portanto, a regra do Make para um arquivo Info deve atualizá-lo no diretório fonte. Quando os usuários compilam o pacote, em geral o Make não atualizará os arquivos Info, pois eles já estarão atualizados.
Gera arquivos de documentação no formato indicado. Esses alvos devem sempre existir, mas qualquer um deles (ou todos) pode ser um no-op se o formato de saída indicado não puder ser gerado. Esses alvos não devem ser dependências do alvo all; o usuário deve invocá-los manualmente.
Eis um exemplo de regra para gerar arquivos DVI a partir do Texinfo:
dvi: foo.dvi
foo.dvi: foo.texi chap1.texi chap2.texi
$(TEXI2DVI) $(srcdir)/foo.texi
Você deve definir a variável TEXI2DVI no Makefile. Ela deve executar o programa texi2dvi, que faz parte da distribuição Texinfo. (O texi2dvi usa o TeX para fazer o trabalho real de formatação. O TeX não é distribuído com o Texinfo.) Como alternativa, escreva apenas as dependências e deixe o GNU make fornecer o comando.
Eis outro exemplo, este para gerar HTML a partir do Texinfo:
html: foo.html
foo.html: foo.texi chap1.texi chap2.texi
$(TEXI2HTML) $(srcdir)/foo.texi
Novamente, você definiria a variável TEXI2HTML no Makefile; por exemplo, ela poderia executar makeinfo --no-split --html (o makeinfo faz parte da distribuição Texinfo).
Cria um arquivo tar de distribuição para este programa. O arquivo tar deve ser montado de modo que os nomes de arquivo dentro dele comecem com um nome de subdiretório que é o nome do pacote ao qual a distribuição se refere. Esse nome pode incluir o número de versão.
Por exemplo, o arquivo tar de distribuição do GCC versão 1.40 é desempacotado em um subdiretório chamado gcc-1.40.
A maneira mais simples de fazer isso é criar um subdiretório com o nome apropriado, usar ln ou cp para instalar nele os arquivos adequados e então empacotar esse subdiretório com o tar.
Comprima o arquivo tar com o gzip. Por exemplo, o arquivo de distribuição real do GCC versão 1.40 chama-se gcc-1.40.tar.gz. Também não há problema em dar suporte a outros formatos de compressão livres.
O alvo dist deve depender explicitamente de todos os arquivos que não são fonte presentes na distribuição, para garantir que estejam atualizados na distribuição. Consulte a seção Making Releases do GNU Coding Standards.
Realiza autotestes (se houver). O usuário deve compilar o programa antes de executar os testes, mas não precisa instalá-lo; você deve escrever os autotestes de modo que funcionem quando o programa estiver compilado, mas não instalado.
Os alvos a seguir são sugeridos como nomes convencionais, para programas em que sejam úteis.
installcheckRealiza testes de instalação (se houver). O usuário deve compilar e instalar o programa antes de executar os testes. Você não deve presumir que $(bindir) esteja no caminho de busca.
installdirsÉ útil adicionar um alvo chamado «installdirs» para criar os diretórios onde os arquivos são instalados, e seus diretórios pais. Há um script chamado mkinstalldirs que é conveniente para isso; você o encontra no pacote Gnulib. Você pode usar uma regra como esta:
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
$(libdir) $(infodir) \
$(mandir)
ou, se você quiser dar suporte a DESTDIR (fortemente encorajado),
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs \
$(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
$(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
$(DESTDIR)$(mandir)
Esta regra não deve modificar os diretórios onde a compilação é feita. Ela não deve fazer nada além de criar os diretórios de instalação.
Ao escrever o alvo install, você deve classificar todos os comandos em três categorias: os normais, os comandos de pré-instalação e os comandos de pós-instalação.
Os comandos normais movem os arquivos para seus lugares próprios e definem seus modos (permissões). Eles não podem alterar nenhum arquivo além daqueles que vêm inteiramente do pacote a que pertencem.
Os comandos de pré-instalação e pós-instalação podem alterar outros arquivos; em particular, podem editar arquivos de configuração globais ou bases de dados.
Os comandos de pré-instalação são normalmente executados antes dos comandos normais, e os comandos de pós-instalação são normalmente executados depois dos comandos normais.
O uso mais comum de um comando de pós-instalação é executar o install-info. Isso não pode ser feito com um comando normal, pois ele altera um arquivo (o diretório do Info) que não vem inteira e exclusivamente do pacote sendo instalado. É um comando de pós-instalação porque precisa ser executado depois do comando normal que instala os arquivos Info do pacote.
A maioria dos programas não precisa de comandos de pré-instalação, mas oferecemos esse recurso para o caso de ser necessário.
Para classificar os comandos da regra install nessas três categorias, insira linhas de categoria entre eles. Uma linha de categoria especifica a categoria dos comandos que a seguem.
Uma linha de categoria consiste em uma tabulação e uma referência a uma variável especial do Make, mais um comentário opcional ao final. Há três variáveis que você pode usar, uma para cada categoria; o nome da variável especifica a categoria. As linhas de categoria são no-ops na execução comum, pois essas três variáveis do Make normalmente não estão definidas (e você não deve defini-las no makefile).
Eis as três possíveis linhas de categoria, cada uma com um comentário que explica o que significa:
$(PRE_INSTALL) # Seguem os comandos de pré-instalação.
$(POST_INSTALL) # Seguem os comandos de pós-instalação.
$(NORMAL_INSTALL) # Seguem os comandos normais.
Se você não usar uma linha de categoria no início da regra install, todos os comandos até a primeira linha de categoria serão classificados como normais. Se você não usar nenhuma linha de categoria, todos os comandos serão classificados como normais.
As linhas de categoria para uninstall são:
$(PRE_UNINSTALL) # Seguem os comandos de pré-desinstalação.
$(POST_UNINSTALL) # Seguem os comandos de pós-desinstalação.
$(NORMAL_UNINSTALL) # Seguem os comandos normais.
Tipicamente, um comando de pré-desinstalação seria usado para excluir entradas do diretório do Info.
Se o alvo install ou uninstall tiver quaisquer dependências que funcionem como sub-rotinas da instalação, então você deve iniciar os comandos de cada dependência com uma linha de categoria, e iniciar também os comandos do alvo principal com uma linha de categoria. Dessa forma, você pode garantir que cada comando seja colocado na categoria correta, independentemente de qual das dependências de fato seja executada.
Os comandos de pré-instalação e pós-instalação não devem executar nenhum programa além destes:
[ basename bash cat chgrp chmod chown cmp cp dd diff echo expand expr false find getopt grep gunzip gzip hostname install install-info kill ldconfig ln ls md5sum mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee test touch true uname xargs yes
A razão para distinguir os comandos dessa forma é em prol da criação de pacotes binários. Tipicamente, um pacote binário contém todos os executáveis e demais arquivos que precisam ser instalados, e tem seu próprio método de instalá-los — portanto, não precisa executar os comandos normais de instalação. Mas instalar o pacote binário precisa executar os comandos de pré-instalação e pós-instalação.
Os programas que criam pacotes binários funcionam extraindo os comandos de pré-instalação e pós-instalação. Eis uma maneira de extrair os comandos de pré-instalação (a opção -s do make é necessária para silenciar as mensagens sobre entrada em subdiretórios):
make -s -n install -o all \
PRE_INSTALL=pre-install \
POST_INSTALL=post-install \
NORMAL_INSTALL=normal-install \
| gawk -f pre-install.awk
onde o arquivo pre-install.awk poderia conter o seguinte:
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
on {print $0}
$0 ~ /^pre-install[ \t]*$/ {on = 1}