# 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 (`.tar.gz`) | (2)
`bztar` | zbzip2owany plik tar (`.tar.bz2`) | (5)
`xztar` | xz’ed tar file (`.tar.xz`) | (5)
`ztar` | skompresowany plik tar (file`.tar.Z`) | (4),(5)
`tar` | plik tar (`.tar`) | (5)

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.

5. deprecated by PEP 527; PyPI only accepts `.zip` and `.tar.gz` files.

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`.