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.
