3. Pisanie pliku konfiguracyjnego instalacji¶
Informacja
Ten dokument jest przechowywany wyłącznie do czasu, gdy dokumentacja setuptools
pod adresem https://setuptools.readthedocs.io/en/latest/setuptools.html niezależnie obejmie wszystkie istotne informacje, które są tutaj zawarte.
Często nie jest możliwe zapisanie wszystkiego potrzebnego do zbudowania dystrybucji a priori: możesz potrzebować zdobyć pewne informacje od użytkownika, lub z systemu użytkownika, w celu przejścia dalej. O ile ta informacje jest raczej prosta—lista katalogów do przeszukania na okoliczność plików nagłówkowych C lub bibliotek, dla przykładu—potem dostarczając plik konfiguracji, setup.cfg
, dla użytkowników aby poddać go edycji jest tanim i łatwym sposobem aby ją uzyskać. Pliki konfiguracji także pozwalają ci dostarczyć domyślne wartości dla dowolnych opcji polecenia, które instalator może wtedy obejść zarówno w linii poleceń lub przez edycję pliku konfiguracyjnego.
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:
Instalatory mogą obejść część tego co umieścisz w pliku
setup.py
przez edycjęsetup.cfg
możesz dostarczyć niestandardowe wartości domyślne dla opcji, które niełatwo się ustawia w pliku
setup.py
Instalatory mogą obejść wszystko w pliku
setup.cfg
używając opcji wiersza-poleceń wywołującego skryptsetup.py
The basic syntax of the configuration file is simple:
[command]
option=value
...
gdzie command jest jedną z komend Distutils (np. build_py, install) i option jest jedną z opcji, którą komenda wspiera. Dowolna liczba opci może być dostarczona do każdej komendy, i dowolna liczba sekcji komend może być wewnątrz pliku. Puste linie są ignorowane, tak jak komentarze, które zaczynają się od znaku '#'
i ciągną aż do końca linii. Długie wartości opcji mogą być dzielone pomiędzy kilka linii prosto przez wcięcie linii kontynuacji.
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 that an option spelled --foo-bar
on the command-line is spelled
foo_bar
in configuration files.
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
To wpłynie na to, że wszystkie budowy dystrybucji tego modułu, niezależnie od tego czy jawnie wyszczególnisz komendę build_ext. Jeśli zawrzesz plik setup.cfg
w twojej dystrybucji źródłowej, wpłynie ona także na budowy dystrybucji użytkownika końcowego—co jest prawdopodobnie złym pomysłem dla tej opcji, skoro budowanie rozszerzeń w -miejscu powodowałoby zawsze uszkodzenie instalacji dystrybucji modułu. W niektórych szczególnych przypadkach, jednakże, moduły są budowane w katalogu ich instalacji, więc jest to twórczo użyteczna umiejętność. (Rozprowadzanie rozszerzeń od których oczekuje się, że będą budowane w katalogu ich instalacji jest prawie zawsze jednak złym pomysłem.)
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 that the doc_files
option is simply a whitespace-separated string
split across multiple lines for readability.
Zobacz także
- Syntax of config files in „Installing Python Modules”
Więcej informacji o plikach konfiguracyjnych jest dostępnych w podręczniku dla administratorów systemu.
Przypisy
- 1
Ten ideał prawdopodobnie nie zostanie osiągnięty dopóki auto-konfiguracja nie będzie w pełni wspierana przez Distutils.