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.
