5.1 The manifest and manifest template

Without any additional information, the sdist command puts a minimal set of files 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 (** getting C library sources currently broken - no get_source_files() method in build_clib.py! **)
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)
README.txt (or README) and setup.py

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 sdist command processes this template and generates a manifest file, MANIFEST. (If you prefer, you can skip the manifest template and generate the manifest yourself: it just lists one file per line.)

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. There are several other commands available in the manifest template mini-language; see section 9.4.

The order of commands in the manifest template very much 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. When we have fully processed the manifest template, we have our complete list of files. This list is written to the manifest for future reference, and then used to build the source distribution archive(s).

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

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)
include test/test*.py (always included)
include README.txt and setup.py (always included)
include *.txt in the distribution root (this will find README.txt a second time, but such redundancies are weeded out later)
in the sub-tree under examples, include anything matching *.txt
in the sub-tree under examples, include anything matching *.py
remove 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 two recursive-include commands

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.

See About this document... for information on suggesting changes.