4. 创建源代码分发包
*******************

備註:

  这篇文档只有在
  https://setuptools.readthedocs.io/en/latest/setuptools.html 上的
  "setuptools" 文档独立涵盖此处包含的所有相关信息之前，才会单独保留。

如 一个简单的例子 一节所示，可以使用 **sdist** 命令来创建一个源代码分
发包。 在最简单的场景下，:

   python setup.py sdist

（假定你没有在设置脚本或配置文件中指定任何 **sdist** 选项），**sdist**
将创建基于当前平台的默认格式的归档。 在 Unix 上默认格式为 gzip 的 tar
文件，而在 Windows 上则为 ZIP 文件。

你可以使用 "--formats" 选项来指定任何你想要的格式，例如:

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

创建一个 gzip 的 tar 文件和一个 zip 文件。 可用的格式有:

+-------------+---------------------------+-----------+
| 格式        | 描述                      | 註解      |
|=============|===========================|===========|
| "zip"       | zip 文件 (".zip")         | (1),(3)   |
+-------------+---------------------------+-----------+
| "gztar"     | gzip'ed tar 文件          | (2)       |
|             | (".tar.gz")               |           |
+-------------+---------------------------+-----------+
| "bztar"     | bzip2'ed tar 文件         |           |
|             | (".tar.bz2")              |           |
+-------------+---------------------------+-----------+
| "xztar"     | xz'ed tar 文件            |           |
|             | (".tar.xz")               |           |
+-------------+---------------------------+-----------+
| "ztar"      | 压缩 tar 文件 (".tar.Z")  | (4)       |
+-------------+---------------------------+-----------+
| "tar"       | tar 文件 (".tar")         |           |
+-------------+---------------------------+-----------+

3.5 版更變: 添加了对 "xztar" 格式的支持

註解：

1. 默认Windows

2. 默认 Unix

3. 需要有外部 **zip** 工具或 "zipfile" 模块（自 Python 1.6 起是标准
   Python 库的一部分）

4. 需要有 **compress** 程序。 请注意此格式计划要弃用并将在未来的
   Python 版本中被移除。

当使用任意 "tar" 格式 ("gztar", "bztar", "xztar", "ztar" 或 "tar") 时
，在 Unix 中你可以指定将为每个归档成员设置的 "owner" 和 "group" 名称。

举例来说，如果你希望归档中所有文件均为 root 所有:

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


4.1. Specifying the files to distribute
=======================================

If you don't supply an explicit list of files (or instructions on how
to generate one), the **sdist** command puts a minimal default set
into the source distribution:

* 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 Installing Scripts.

* anything that looks like a test script: "test/test*.py" (currently,
  the Distutils don't do anything with test scripts except include
  them in source distributions, but in the future there will be a
  standard for testing Python module distributions)

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

Sometimes this is enough, but usually you will want to specify
additional files to distribute.  The typical way to do this is to
write a *manifest template*, called "MANIFEST.in" by default.  The
manifest template is just a list of instructions for how to generate
your manifest file, "MANIFEST", which is the exact list of files to
include in your source distribution.  The **sdist** command processes
this template and generates a manifest based on its instructions and
what it finds in the filesystem.

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.

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

3.1.3 版更變: "MANIFEST" files start with a comment indicating they
are generated. Files without this comment are not overwritten or
removed.

3.2.2 版更變: **sdist** will read a "MANIFEST" file if no
"MANIFEST.in" exists, like it used to do.

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 创建源码发行包: sdist 命
令.

The order of commands in the manifest template matters: initially, we
have the list of default files as described above, and each command in
the template adds to or removes from that list of files.  Once we have
fully processed the manifest template, we remove files that should not
be included in the source distribution:

* all files in the Distutils "build" tree (default "build/")

* all files in directories named "RCS", "CVS", ".svn", ".hg", ".git",
  ".bzr" or "_darcs"

Now we have our complete list of files, which is written to the
manifest for future reference, and then used to build the source
distribution archive(s).

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

Following the Distutils' own manifest template, let's trace how the
**sdist** command builds the list of files to include in the Distutils
source distribution:

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 编写安装脚本)

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