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          | (2)       |
|             | (".tar.gz")               |           |
+-------------+---------------------------+-----------+
| "bztar"     | bzip2'ed tar file         |           |
|             | (".tar.bz2")              |           |
+-------------+---------------------------+-----------+
| "xztar"     | xz'ed tar file            |           |
|             | (".tar.xz")               |           |
+-------------+---------------------------+-----------+
| "ztar"      | compressed tar file       | (4)       |
|             | (".tar.Z")                |           |
+-------------+---------------------------+-----------+
| "tar"       | arquivo tar (".tar")      |           |
+-------------+---------------------------+-----------+

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.

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