3. Escrevendo o arquivo de configuração de instalação¶
Frequentemente, não é possível escrever tudo o que é necessário para construir uma distribuição a priori: você pode precisar obter algumas informações do usuário, ou do sistema do usuário, para prosseguir. Contanto que essa informação seja bastante simples – uma lista de diretórios para pesquisar arquivos de cabeçalho C ou bibliotecas, por exemplo – então fornecer um arquivo de configuração, setup.cfg
, para os usuários editarem é um maneira pouco custosa e fácil de solicitá-la. Os arquivos de configuração também permitem fornecer valores padrão para qualquer opção de comando, que o instalador pode então substituir na linha de comando ou editando o arquivo de configuração.
O arquivo de configuração de instalação é um meio-termo útil entre o script de instalação – que, idealmente, deveria ser utilizado sem que os instaladores se preocupem com seu conteúdo 1 – e a linha de comando para o script de instalação, que está fora do seu controle e inteiramente a cargo do instalador. Na verdade, setup.cfg
(e quaisquer outros arquivos de configuração Distutils presentes no sistema de destino) são processados após o conteúdo do script de instalação, mas antes da linha de comando. Isso tem várias consequências úteis:
os instaladores podem substituir parte do que você colocou em
setup.py
editandosetup.cfg
você pode fornecer valores iniciais fora do padrão para opções que não são facilmente definidas em
setup.py
os instaladores podem substituir qualquer coisa em
setup.cfg
usando as opções de linha de comando parasetup.py
A sintaxe básica do arquivo de configuração é simples:
[command]
option=value
...
sendo command um dos comandos Distutils (por exemplo build_py, install) e option uma das opções as quais o comando tem suporte. Qualquer número de opções pode ser fornecido para cada comando e qualquer número de seções de comando pode ser incluído no arquivo. As linhas em branco são ignoradas, assim como os comentários, que vão de um caractere '#'
até o final da linha. Valores de opção longas podem ser divididos em várias linhas simplesmente identando as linhas de continuação.
Você pode descobrir a lista de opções suportadas por um comando específico com a opção universal --help
, por exemplo.
$ python setup.py --help build_ext
[...]
Options for 'build_ext' command:
--build-lib (-b) directory for compiled extension modules
--build-temp (-t) directory for temporary files (build by-products)
--inplace (-i) ignore build-lib and put compiled extensions into the
source directory alongside your pure Python modules
--include-dirs (-I) list of directories to search for header files
--define (-D) C preprocessor macros to define
--undef (-U) C preprocessor macros to undefine
--swig-opts list of SWIG command line options
[...]
Note que uma opção escrita --foo-bar
na linha de comando é escrita foo_bar
nos arquivos de configuração.
Por exemplo, digamos que você queira que suas extensões sejam construídas “no local” – isto é, você tem uma extensão pkg.ext
, e deseja o arquivo de extensão compilado (ext.so
no Unix, digamos) para serem colocados no mesmo diretório fonte de seus módulos Python puros pkg.mod1
e pkg.mod2
. Você sempre pode usar a opção --inplace
na linha de comando para garantir isso:
python setup.py build_ext --inplace
Mas isso requer que você sempre especifique o comando build_ext explicitamente, e que lembre-se de fornecer --inplace
. Uma maneira mais fácil é “definir e esquecer” esta opção, codificando-a em setup.cfg
, o arquivo de configuração para esta distribuição:
[build_ext]
inplace=1
Isso afetará todas as construções desta distribuição de módulo, quer você especifique explicitamente ou não build_ext. Se você incluir um setup.cfg
em sua distribuição fonte, isso também afetará as construções do usuário final – o que provavelmente é uma má ideia para esta opção, já que sempre construir extensões no local interromperia a instalação da distribuição de módulo. Em certos casos peculiares, porém, os módulos são construídos diretamente em seu diretório de instalação, portanto, esta é uma capacidade útil. (Distribuir extensões que esperam ser construídas em seu diretório de instalação é quase sempre uma má ideia, no entanto.)
Outro exemplo: certos comandos aceitam muitas opções que não mudam de execução para execução; por exemplo, bdist_rpm precisa saber tudo o que é necessário para gerar um arquivo “spec” para criar uma distribuição RPM. Algumas dessas informações vêm do script de configuração e outras são geradas automaticamente pelo Distutils (como a lista de arquivos instalados). Mas algumas delas devem ser fornecidas como opções para bdist_rpm, o que seria muito tedioso de fazer na linha de comando para cada execução. Portanto, aqui está um trecho de código do setup.cfg
do próprio Distutils:
[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
README.txt
USAGE.txt
doc/
examples/
Note que a opção doc_files
é simplesmente uma string separada por espaços em branco dividida em várias linhas para facilitar a leitura.
Ver também
- Sintaxe dos arquivos de configuração em “Instalando Módulos Python”
Mais informações sobre os arquivos de configuração estão disponíveis no manual para administradores de sistema.
Notas de rodapé
- 1
Este ideal provavelmente não será alcançado até que a configuração automática seja totalmente suportada pelo Distutils.