4. Tworzenie dystrybucji źródłowej
**********************************

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.

Jak pokazano w rozdziale Prosty przykład, używasz polecenia **sdist**
aby utworzyć dystrybucję źródłową. W najprostszym przypadku,

   python setup.py sdist

(zakładając że nie ustaliłeś żadnych opcji polecenia **sdist`w
skrypcie instalacyjnym lub pliku konfiguracyjnym), polecenie
:command:`sdist** tworzy archiwum domyślnego formatu dla danej
maszyny/środowiska. Domyślnym formatem jest zgzipowany plik tar
(".tar.gz") na Unixie i plik ZIP na Windows.

You can specify as many formats as you like using the "--formats"
option, for example:

   python setup.py sdist --formats=gztar,zip

aby utworzyć zgzipowany tarball i plik zip. Dostępne formaty to:

+-------------+---------------------------+-----------+
| Format      | Opis                      | Notatki   |
|=============|===========================|===========|
| "zip"       | plik zip (".zip")         | (1),(3)   |
+-------------+---------------------------+-----------+
| "gztar"     | zgzipowany plik tar       | (2)       |
|             | (".tar.gz")               |           |
+-------------+---------------------------+-----------+
| "bztar"     | zbzip2owany plik tar      |           |
|             | (".tar.bz2")              |           |
+-------------+---------------------------+-----------+
| "xztar"     | xz'ed tar file            |           |
|             | (".tar.xz")               |           |
+-------------+---------------------------+-----------+
| "ztar"      | skompresowany plik tar    | (4)       |
|             | (file`.tar.Z`)            |           |
+-------------+---------------------------+-----------+
| "tar"       | plik tar (".tar")         |           |
+-------------+---------------------------+-----------+

Zmienione w wersji 3.5: Added support for the "xztar" format.

Uwagi:

1. domyślne dla Windows

2. domyślne dla Unix

3. wymaga zewnętrznego programu użytkowego **zip** lub modułu
   "zipfile" (części standardowej biblioteki języka pytonowskiego od
   wersji 1.6 języka pytonowskiego)

4. wymaga programu kompresji **compress**. Zauważ że ten format
   oczekuje teraz na przedawnienie i zostanie zdjęty w przyszłych
   wersjach języka pytonowskiego.

When using any "tar" format ("gztar", "bztar", "xztar", "ztar" or
"tar"), under Unix you can specify the "owner" and "group" names that
will be set for each member of the archive.

Dla przykładu, gdy chcesz aby wszystkie pliki archiwum były posiadane
przez roota:

   python setup.py sdist --owner=root --group=root


4.1. Określanie plików do rozprowadzenia
========================================

Jeśli nie dostarczasz jawnej listy plików (lub instrukcji jak ją
wygenerować), polecenie **sdist** wkłada minimalny zbiór domyślny w
dystrybucję źródeł:

* all Python source files implied by the "py_modules" and "packages"
  options

* all C source files mentioned in the "ext_modules" or "libraries"
  options

* scripts identified by the "scripts" option See Instalowanie
  skryptów.

* cokolwiek co wygląda jak skrypt testujący: plik "test/test*.py"
  (obecnie Distutils nie robi nic ze skryptami testowymi z wyjątkiem
  załączania ich w dystrybucji źródeł, ale w przyszłości będzie
  standard dla testowania dystrybucji modułów języka pytonowskiego)

* Any of the standard README files ("README", "README.txt", or
  "README.rst"), "setup.py" (or whatever you called your setup
  script), and "setup.cfg".

* wszystkie pliki które odpowiadają danym-o-danych "package_data".
  Zobacz Instalowanie danych pakietu.

* wszystkie pliki które odpowiadają danym-o-danych "data_files".
  Zobacz Instalowanie dodatkowych plików.

Czasem to jest wystarczające, ale zwykle potrzebujesz określić
dodatkowe pliki do rozprowadzenia. Typowym sposobem robienia tego jest
napisanie *wzoru manifestu* - z ang. - *manifest template* zwanego
"MANIFEST.in" domyślnie. Wzór manifestu jest po prostu listą
instrukcji na to jak wygenerować plik manifestu, "MANIFEST", który
jest dokładnie listą plików do włączenia w twoją dystrybucję źródłową.
Polecenie **sdist** przetwarza ten wzorzec i wytwarza manifest w
oparciu o jego instrukcje i to, co znajdzie w systemie plików.

Jeśli wolisz napisać swój własny plik manifestu, format jest prosty:
jedna nazwa pliku na linię, jedynie pliki zwyczajne (lub symboliczne
odwołania do nich). Jeżeli dostarczysz swój własny plik "MANIFEST",
musisz określić wszystko: domyślny zbiór plików opisujących powyższe
nie odnosi się do tego przypadku.

Zmienione w wersji 3.1: An existing generated "MANIFEST" will be
regenerated without **sdist** comparing its modification time to the
one of "MANIFEST.in" or "setup.py".

Zmienione w wersji 3.1.3: "MANIFEST" files start with a comment
indicating they are generated. Files without this comment are not
overwritten or removed.

Zmienione w wersji 3.2.2: **sdist** will read a "MANIFEST" file if no
"MANIFEST.in" exists, like it used to do.

Zmienione w wersji 3.7: "README.rst" is now included in the list of
distutils standard READMEs.

The manifest template has one command per line, where each command
specifies a set of files to include or exclude from the source
distribution.  For an example, again we turn to the Distutils' own
manifest template:

   include *.txt
   recursive-include examples *.txt *.py
   prune examples/sample?/build

The meanings should be fairly clear: include all files in the
distribution root matching "*.txt", all files anywhere under the
"examples" directory matching "*.txt" or "*.py", and exclude all
directories matching "examples/sample?/build".  All of this is done
*after* the standard include set, so you can exclude files from the
standard set with explicit instructions in the manifest template.
(Or, you can use the "--no-defaults" option to disable the standard
set entirely.)  There are several other commands available in the
manifest template mini-language; see section Creating a source
distribution: the sdist command.

Kolejność poleceń we wzorze manifestu ma znaczenie: początkowo, mamy
listę domyślnych plików, jak opisano powyżej, i każde polecenie we
wzorze dodaje lub zdejmuje z tej listy plików. Gdy mamy całkowicie
przetworzony wzór manifestu, usuwamy pliki, które nie powinny
znajdować się w dystrybucji źródłowej:

* wszystkie pliki w drzewie budowania Distutils (domyślne "build/")

* wszystkie pliki w katalogach nazwanych "RCS", "CVS", ".svn", ".hg",
  ".git", ".bzr" or "_darcs"

Teraz mamy naszą pełną listę plików, które są zapisane w manifeście
dla przyszłego odniesienia, i potem używane do budowania archiwum(ów)
źródłowych dystrybucji.

You can disable the default set of included files with the "--no-
defaults" option, and you can disable the standard exclude set with "
--no-prune".

Podążając za wzorem manifestu własnego Distutils, prześledźmy jak
polecenie **sdist** buduje listę plików do załączenia w źródłowej
dystrybucji Distutils:

1. include all Python source files in the "distutils" and
   "distutils/command" subdirectories (because packages corresponding
   to those two directories were mentioned in the "packages" option in
   the setup script---see section Pisanie Skryptu Instalacyjnego)

2. include "README.txt", "setup.py", and "setup.cfg" (standardowe
   pliki)

3. include "test/test*.py" (standardowe pliki)

4. załącz pliki "*.txt" w nadrzędnym katalogu dystrybucji (to
   odnajdzie plik "README.txt" po raz drugi, ale takie nadmiarowości
   są odchwaszczane później)

5. załącz cokolwiek pasującego do wzoru "*.txt" lub "*.py" w
   poddrzewie pod "examples",

6. wyłącz wszystkie pliki w poddrzewach pasujące do
   "examples/sample?/build"--- to może wyłączyć pliki załączone w
   poprzednich dwóch krokach, więc istotne jest aby polecenie "prune"
   we wzorcu manifestu następowało po poleceniu "recursive-include"

7. wyłącz całe drzewo "build", i wszystkie katalogi "RCS" "CVS",
   ".svn", ".hg", ".git", ".bzr" i "_darcs"

Tak jak w skrypcie instalacyjnym, nazwy plików i katalogów we wzorcu
manifestu powinny zawsze być separowane-ukośnikiem; Distutils zajmie
się zamianą ich na standardową postać na twojej maszynie/środowisku. W
ten sposób, wzór manifestu jest przenośny pomiędzy systemami
operacyjnymi.


4.2. Związane-z-Manifestem opcje
================================

Normalny kurs operacji polecenia **sdist** jest następujący:

* if the manifest file ("MANIFEST" by default) exists and the first
  line does not have a comment indicating it is generated from
  "MANIFEST.in", then it is used as is, unaltered

* if the manifest file doesn't exist or has been previously
  automatically generated, read "MANIFEST.in" and create the manifest

* Jeśli żaden z plików "MANIFEST" ani "MANIFEST.in" nie istnieją,
  stwórz manifest tylko z domyślnym zestawem plików

* użyj listy plików teraz znajdujących się w pliku "MANIFEST" (albo
  dopiero co wygenerowanych albo wczytanych) do utworzenia
  archiwum(/ów) dystrybucji źródłowej

There are a couple of options that modify this behaviour.  First, use
the "--no-defaults" and "--no-prune" to disable the standard "include"
and "exclude" sets.

Po drugie możesz po prostu chcieć wygenerować (powtórnie) manifest,
ale nie tworzyć dystrybucji źródłowej:

   python setup.py sdist --manifest-only

"-o" is a shortcut for "--manifest-only".
