GNU Info

(python2.1-dist.info)Specifying the files to distribute

---

Next: Manifest-related options Prev: Creating a Source Distribution Up: Creating a Source Distribution

---

Enter node , (file) or (file)node

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 (*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'), `setup.py' (or whatever you called
     your setup script), and `setup.cfg'

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.

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~Note: Creating a source
distribution the sdist command.

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' or `CVS'

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~Note: Writing the Setup Script)

  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' or `CVS' 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.