# 4. Criando uma Distribuição Fonte

Nota

Este documento está sendo mantido apenas até que a documentação do `setuptools` em https://setuptools.readthedocs.io/en/latest/setuptools.html cubra independentemente todas as informações relevantes atualmente incluídas aqui.

Conforme mostrado na seção Um Exemplo Simples, você usa o comando sdist para criar uma distribuição fonte. No caso mais simples,

    python setup.py sdist

(assuming you haven’t specified any sdist options in the setup script or config file), sdist creates the archive of the default format for the current platform. The default format is a gzip’ed tar file (`.tar.gz`) on Unix, and ZIP file on Windows.

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

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

to create a gzipped tarball and a zip file. The available formats are:

Formatação | Descrição | Notas
--- | --- | ---
`zip` | arquivo zip (`.zip`) | (1),(3)
`gztar` | gzip’ed tar file (`.tar.gz`) | (2)
`bztar` | bzip2’ed tar file (`.tar.bz2`) | (5)
`xztar` | xz’ed tar file (`.tar.xz`) | (5)
`ztar` | compressed tar file (`.tar.Z`) | (4),(5)
`tar` | arquivo tar (`.tar`) | (5)

Alterado na versão 3.5: Added support for the `xztar` format.

Notas:

1. default on Windows

2. default on Unix

3. requires either external zip utility or `zipfile` module (part of the standard Python library since Python 1.6)

4. requires the compress program. Notice that this format is now pending for deprecation and will be removed in the future versions of Python.

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.

For example, if you want all files of the archive to be owned by root:

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

## 4.1. Specifying the files to distribute

Se você não fornecer uma lista explícita de arquivos (ou instruções sobre como gerá-la), o comando sdist coloca um conjunto padrão mínimo na distribuição fonte:

- todos os arquivos fonte Python implícitos nas opções `py_modules` e `packages`

- todos os arquivos fonte C mencionados nas opções `ext_modules` ou `libraries`

- scripts identified by the `scripts` option See Installing Scripts.

- qualquer coisa que se pareça com um script de teste: `test/test*.py` (atualmente, os Distutils não fazem nada com scripts de teste, exceto incluí-los em distribuições fonte, mas no futuro haverá um padrão para teste de distribuições de módulo Python)

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

- all files that matches the `package_data` metadata. See Installing Package Data.

- all files that matches the `data_files` metadata. See Installing Additional Files.

Às vezes, isso é suficiente, mas normalmente você deseja especificar arquivos adicionais para distribuir. A maneira típica de fazer isso é escrever um modelo de manifesto, chamado `MANIFEST.in` por padrão. O modelo de manifesto é apenas uma lista de instruções sobre como gerar seu arquivo de manifesto, `MANIFEST`, que é a lista exata de arquivos a serem incluídos em sua distribuição fonte. O comando sdist processa este modelo e gera um manifesto baseado em suas instruções e no que ele encontra no sistema de arquivos.

If you prefer to roll your own manifest file, the format is simple: one filename per line, regular files (or symlinks to them) only. If you do supply your own `MANIFEST`, you must specify everything: the default set of files described above does not apply in this case.

Alterado na versão 3.1: An existing generated `MANIFEST` will be regenerated without sdist comparing its modification time to the one of `MANIFEST.in` or `setup.py`.

Alterado na versão 3.1.3: `MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed.

Alterado na versão 3.2.2: sdist will read a `MANIFEST` file if no `MANIFEST.in` exists, like it used to do.

Alterado na versão 3.7: `README.rst` is now included in the list of distutils standard READMEs.

O modelo de manifesto tem um comando por linha, onde cada comando especifica um conjunto de arquivos para incluir ou excluir da distribuição fonte. Por exemplo, voltamos novamente para o próprio modelo de manifesto do Distutils:

    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 Criando uma distribuição de fontes: o comando sdist.

A ordem dos comandos no modelo de manifesto é importante: inicialmente, temos a lista de arquivos padrão conforme descrito acima, e cada comando no modelo adiciona ou remove dessa lista de arquivos. Depois de processarmos totalmente o modelo de manifesto, removemos os arquivos que não devem ser incluídos na distribuição fonte:

- all files in the Distutils “build” tree (default `build/`)

- all files in directories named `RCS`, `CVS`, `.svn`, `.hg`, `.git`, `.bzr` or `_darcs`

Agora temos nossa lista completa de arquivos, que é gravada no manifesto para referência futura e usada para construir o(s) arquivo(s) de distribuição fonte.

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

Seguindo o modelo de manifesto do próprio Distutils, vamos rastrear como o comando sdist constrói a lista de arquivos a serem incluídos na distribuição fonte Distutils:

1. inclua todos os arquivos fonte Python nos subdiretórios `distutils` e `distutils/command` (porque os pacotes correspondentes a esses dois diretórios foram mencionados na opção `packages` no script de configuração – consulte a seção Escrevendo o Script de Configuração)

2. include `README.txt`, `setup.py`, and `setup.cfg` (standard files)

3. include `test/test*.py` (standard files)

4. include `*.txt` in the distribution root (this will find `README.txt` a second time, but such redundancies are weeded out later)

5. include anything matching `*.txt` or `*.py` in the sub-tree under `examples`,

6. exclude all files in the sub-trees starting at directories matching `examples/sample?/build`—this may exclude files included by the previous two steps, so it’s important that the `prune` command in the manifest template comes after the `recursive-include` command

7. exclude the entire `build` tree, and any `RCS`, `CVS`, `.svn`, `.hg`, `.git`, `.bzr` and `_darcs` directories

Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems.

## 4.2. Manifest-related options

The normal course of operations for the sdist command is as follows:

- 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

- if neither `MANIFEST` nor `MANIFEST.in` exist, create a manifest with just the default file set

- use the list of files now in `MANIFEST` (either just generated or read in) to create the source distribution archive(s)

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.

Second, you might just want to (re)generate the manifest, but not create a source distribution:

    python setup.py sdist --manifest-only

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