Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# 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é

1

  Este ideal provavelmente não será alcançado até que a configuração automática seja totalmente suportada pelo Distutils.