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.
The setup configuration file is a useful middle-ground between the setup script
—which, ideally, would be opaque to installers [1]—and the command-line to
the setup script, which is outside of your control and entirely up to the
installer. In fact, setup.cfg
(and any other Distutils configuration
files present on the target system) are processed after the contents of the
setup script, but before the command-line. This has several useful
consequences:
- 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
The basic syntax of the configuration file is simple:
[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.
You can find out the list of options supported by a particular command with the
universal --help
option, e.g.
> 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.
For example, say you want your extensions to be built “in-place”—that is, you
have an extension pkg.ext
, and you want the compiled extension file
(ext.so
on Unix, say) to be put in the same source directory as your
pure Python modules pkg.mod1
and pkg.mod2
. You can always use the
--inplace
option on the command-line to ensure this:
python setup.py build_ext --inplace
But this requires that you always specify the build_ext command
explicitly, and remember to provide --inplace
. An easier way is to
“set and forget” this option, by encoding it in setup.cfg
, the
configuration file for this distribution:
[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.)
Another example: certain commands take a lot of options that don’t change from
run to run; for example, bdist_rpm needs to know everything required
to generate a “spec” file for creating an RPM distribution. Some of this
information comes from the setup script, and some is automatically generated by
the Distutils (such as the list of files installed). But some of it has to be
supplied as options to bdist_rpm, which would be very tedious to do
on the command-line for every run. Hence, here is a snippet from the Distutils’
own setup.cfg
:
[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
- Syntax of config files 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. |