3. Escrevendo o arquivo de configuração de instalação

Nota

Este documento está sendo mantido apenas até que a documentação do setuptools em https://setuptools.readthedocs.io/en/latest/setuptools.html cubra independentemente todas as informações relevantes atualmente incluídas aqui.

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 editando setup.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 para setup.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 indentando 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 “localmente” – 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 localmente 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é