1. Wprowadzenie do Distutils
****************************

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.

Ten dokument opisuje użycie Distutils do dystrybucji twoich modułów
języka pytonowskiego koncentrując się na roli twórcy/dystrybutora:
jeśli szukasz informacji o instalowaniu modułów języka pytonowskiego
powinieneś odwołać się do rozdziału Installing Python Modules (Legacy
version).


1.1. Pojęcia i Terminy
======================

Użycie Distutils jest całkiem proste, zarówno dla twórców modułów jak
i dla użytkowników/administratorów instalujących moduły ze strony osób
trzecich. Jako twórca, twoim zadaniem (poza pisaniem porządnego,
dobrze udokumentowanego i dobrze przetestowanego kodu, rzecz jasna!)
są:

* napisanie skryptu instalacyjnego (pliku "setup.py" - zgodnie ze
  zwyczajem)

* (opcjonalnie) napisanie pliku konfiguracji instalacji

* utworzenie dystrybucji źródłowej

* (nadobowiązkowe) stworzyć jedną lub więcej zbudowaną (binarną)
  dystrybucję

Każde z tych zadań jest opisane w tym dokumencie.

Nie wszyscy twórcy mają dostęp do wielu maszyn/środowisk, więc nie
zawsze rozsądne jest oczekiwanie od nich tworzenia wielu zbudowanych
dystrybucji. Jest oczekiwane że pewien zbiór pośredników, zwanych
*pakowaczami*, powstanie aby zaradzić tym potrzebom. Pakowacze biorą
dystrybucje źródłowe wypuszczonych przez twórców modułów, budują je na
jednej lub większej liczbie maszyn/środowisk, i wypuszczają wynikłe
zbudowane dystrybucje. Zatem, użytkownicy większości popularnych
platform będą w stanie instalować większość popularnych dystrybucji
modułów języka pytonowskiego w najbardziej naturalny sposób dla ich
maszyn/środowisk, bez konieczności uruchomienia nawet jednego skryptu
instalacyjnego ani kompilowania ani jednej linijki kodu.


1.2. Prosty przykład
====================

Skrypt instalacyjny jest zwykle raczej prosty, chociaż od kiedy jest
pisany w języku pytonowskim, nie ma odgórnych granic co można z nim
zrobić, chociaż powinieneś być ostrożny w umieszczaniu dowolnie
kosztownych operacji w swoim skrypcie instalacyjnym. W przeciwieństwie
do dajmy na to skryptów konfiguracyjnych w stylu Autoconf-a, skrypt
instalacyjny może być uruchamiany kilka razy w trakcie budowania i
instalowania twojej dystrybucji modułu.

Jeśli wszystkim czego chcesz dokonać jest dystrybuowanie modułu
nazwanego "foo" zawartego w pliku "foo.py" wtedy twój plik skryptu
instalacyjnego może być tak prosty jak:

   from distutils.core import setup
   setup(name='foo',
         version='1.0',
         py_modules=['foo'],
         )

Pewne obserwacje

* większość informacji które dostarczasz do Distutils jest podawana
  jako parametry słów kluczowych do zadania "setup()".

* te parametry słów kluczowych należą do dwóch kategorii: informacje o
  danych pakietu (- z ang. - metadata)  (nazwa, numer wersji) i
  informacja o tym co jest w pakiecie (lista czysto pytonowskich
  modułów, w tym przypadku)

* moduły są określone przez nazwę modułu nie nazwę pliku (to samo
  odnosi się do pakietów i rozszerzeń)

* polecane jest abyś dostarczył nieco więcej informacji o danych, w
  szczególności swoje imię, adres email i URL projektu (sięgnij do
  rozdziału Pisanie Skryptu Instalacyjnego po przykład)

To create a source distribution for this module, you would create a
setup script, "setup.py", containing the above code, and run this
command from a terminal:

   python setup.py sdist

For Windows, open a command prompt window (Start ‣ Accessories) and
change the command to:

   setup.py sdist

**sdist** will create an archive file (e.g., tarball on Unix, ZIP file
on Windows) containing your setup script "setup.py", and your module
"foo.py". The archive file will be named "foo-1.0.tar.gz" (or ".zip"),
and will unpack into a directory "foo-1.0".

If an end-user wishes to install your "foo" module, all they have to
do is download "foo-1.0.tar.gz" (or ".zip"), unpack it, and---from the
"foo-1.0" directory---run

   python setup.py install

które ostatecznie kopiują plik "foo.py" do odpowiedniego katalogu dla
modułów pochodzących od osób trzecich w ich instalacji języka
pytonowskiego.

Ten prosty przykład demonstruje pewne podstawowe pojęcia Distutils. Po
pierwsze zarówno twórcy modułów jak i instalujący je mają ten sam
podstawowy sprzęg użytkownika tj. skrypt instalacyjny. Różnica polega
na tym, którego *polecenia* ( - z ang. - *command* ) Distutils
używają: polecenie **sdist** jest prawie wyłącznie dla twórców
modułów, podczas gdy **install** jest częściej dla instalujących
(chociaż większość twórców też będzie chciała zainstalować swój własny
kod czasami).

Jeśli chcesz uczynić rzeczy naprawdę łatwymi dla swoich użytkowników,
możesz stworzyć jedną lub więcej zbudowaną dystrybucję dla nich. Na
przykład, jeśli działasz na komputerze z Windows, i chcesz uczynić
rzeczy łatwymi dla innych użytkowników Windowsa, możesz utworzyć
wykonywalny instalator (najbardziej odpowiedni typ zbudowanej
dystrybucji dla tej maszyny/środowiska) z poleceniem
**bdist_wininst**. Na przykład:

   python setup.py bdist_wininst

utworzy wykonywalny instalator, "foo-1.0.win32.exe", w bierzącym
katalogu.

Inne użyteczne formaty dystrybucji to RPMy, wypełnione przez polecenie
**bdist_rpm**, program **pkgtootl** Solarisa (**bdist_pkgtool**), i
program swinstall` dla HP-UX (**bdist_sdux**). Na przykład,
następujące polecenie utworzy plik RPM nazwany "foo-1.0.noarch.rpm":

   python setup.py bdist_rpm

(Polecenie **bdist_rpm** używa polecenia wykonywalnego **rpm**, zatem
musi to być uruchamiane na opartym o RPMy systemie takim jak Linux Red
Hat, Linux SuSE, lub Linux Mandrake.)

Możesz dowiedzieć się o tym które formaty dystrybucji są dostępne w
każdej chwili uruchamiając:

   python setup.py bdist --help-formats


1.3. Ogólne terminy języka pytonowskiego
========================================

Jeśli czytasz ten dokument, pewnie masz dobre pojęcie czym są moduły,
rozszerzenia, itd. itp. Tym nie mniej, aby się upewnić że wszyscy
operują ze wspólnego punktu początkowego, oferujemy następujący
słowniczek wspólnych terminów języka pytonowskiego:

module
   podstawowa miara powtórnej użyteczności kodu w języku pytonowskim:
   blok kodu zaimportowany przez inny kod. Trzy typy modułów
   interesują nas tutaj: moduły czysto pytonowskie, moduły
   rozszerzające, i pakiety.

pure Python module
   a module written in Python and contained in a single ".py" file
   (and possibly associated ".pyc" files).  Sometimes referred to as a
   "pure module."

extension module
   moduł napisany w niskopoziomowym języku wypełnienia języka
   pytonowskiego: C/C++ dla języka pytonowskiego, Java dla języka
   Jytonowskiego. Typowo zawarty w pojedynczym dynamicznie ładowalnym
   uprzednio skompilowanym pliku, np. plik współdzielonych obiektów (-
   z ang. shared object - w skrócie so - ".so") dla rozszerzeń języka
   pytonowskiego dla Unix, i DLL (mając dane rozszerzenie ".pyd") dla
   rozszerzeń języka pytonowskiego na Windowsie, lub plik uogólnienia
   Javy dla języka rozszerzeń języka jytonowskiego. (Zauważ, że
   obecnie, Distutils obsługuje tylko rozszerzenia C/C++ dla języka
   pytonowskiego.)

package
   moduł który zawiera inne moduły; typowo przechowywany w katalogu w
   systemie plików i rozróżniany od innych katalogów przez obecność
   pliku "__init__.py".

root package
   Korzeń hierarchii pakietów. (To nie jest właściwie pakiet, gdyż nie
   ma pliku "__init__.py". Ale musimy jakoś go nazwać.) Znaczna
   większość standardowej biblioteki jest w pakiecie korzenia, tak jak
   wiele małych, samodzielnych modułów osób-trzecich, które nie pasują
   do większej kolekcji modułów. W przeciwieństwie do typowych
   pakietów, moduły w pakiecie korzenia można znaleźć w wielu
   katalogach: w rzeczywistości, każdy katalog wypisany w "sys.path"
   dokłada moduły do pakietu korzenia.


1.4. Terminologia szczególna dla Distutils
==========================================

Następujące terminy odnoszą się bardziej szczególnie do domeny
dystrybucji modułów pytonowskich przy użyciu Distutils:

module distribution
   a collection of Python modules distributed together as a single
   downloadable resource and meant to be installed *en masse*.
   Examples of some well-known module distributions are NumPy, SciPy,
   Pillow, or mxBase.  (This would be called a *package*, except that
   term is already taken in the Python context: a single module
   distribution may contain zero, one, or many Python packages.)

pure module distribution
   dystrybucja modułów która zawiera tylko czysto pytonowskie moduły i
   pakiety. Czasami określana mianem "czystej dystrybucji."

non-pure module distribution
   dystrybucja modułu która zawiera przynajmniej jeden moduł
   rozszerzeń. Czasami określana jako "nie-czysta dystrybucja."

distribution root
   Nadrzędnego poziomu katalog twojego drzewa źródeł (inaczej
   dystrybucji źródeł); katalog w którym plik "setup.py" jest
   umieszczony. Ogólnie plik "setup.py" będzie uruchomiony z tego
   katalogu.
