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 skrypt setup.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.