sam-t2/devtools/v8plus/html/python/dist/manifest.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="dist.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="dist.html" title='Distributing Python Modules' />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="manifest-options.html" />
<link rel="prev" href="source-dist.html" />
<link rel="parent" href="source-dist.html" />
<link rel="next" href="manifest-options.html" />
<meta name='aesop' content='information' />
<title>4.1 Specifying the files to distribute</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4. Creating a Source"
  href="source-dist.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4. Creating a Source"
  href="source-dist.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.2 Manifest-related options"
  href="manifest-options.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="source-dist.html">4. Creating a Source</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="source-dist.html">4. Creating a Source</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="manifest-options.html">4.2 Manifest-related options</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION004100000000000000000"></A>
<A NAME="manifest"></A>
<BR>
4.1 Specifying the files to distribute
</H1>

<P>
If you don't supply an explicit list of files (or instructions on how to
generate one), the <code class="du-command">sdist</code> command puts a minimal default set
into the source distribution:

<UL>
<LI>all Python source files implied by the <span class="du-option">py_modules</span> and
  <span class="du-option">packages</span> options
</LI>
<LI>all C source files mentioned in the <span class="du-option">ext_modules</span> or
  <span class="du-option">libraries</span> options (<b class="du-xxx">getting C library sources currently
    broken--no <tt class="method">get_source_files()</tt> method in <span class="file">build_clib.py</span>!</b>)
</LI>
<LI>scripts identified by the <span class="du-option">scripts</span> option
</LI>
<LI>anything that looks like a test script: <span class="file">test/test*.py</span>
  (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)
</LI>
<LI><span class="file">README.txt</span> (or <span class="file">README</span>), <span class="file">setup.py</span> (or whatever
  you called your setup script), and <span class="file">setup.cfg</span>
</LI>
</UL>

<P>
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 <em>manifest template</em>, called <span class="file">MANIFEST.in</span> by default.  The
manifest template is just a list of instructions for how to generate
your manifest file, <span class="file">MANIFEST</span>, which is the exact list of files to
include in your source distribution.  The <code class="du-command">sdist</code> command
processes this template and generates a manifest based on its
instructions and what it finds in the filesystem.

<P>
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 <span class="file">MANIFEST</span>, you must specify everything: the
default set of files described above does not apply in this case.

<P>
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:

<P>
<div class="verbatim"><pre>
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
</pre></div>

<P>
The meanings should be fairly clear: include all files in the
distribution root matching <span class="file">*.txt</span>, all files anywhere under the
<span class="file">examples</span> directory matching <span class="file">*.txt</span> or <span class="file">*.py</span>, and
exclude all directories matching <span class="file">examples/sample?/build</span>.  All of
this is done <em>after</em> 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 <b class="programopt">--no-defaults</b> option to
disable the standard set entirely.)  There are several other commands
available in the manifest template mini-language; see
section&nbsp;<A href="sdist-cmd.html#sdist-cmd">9.2</A>.

<P>
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:

<UL>
<LI>all files in the Distutils ``build'' tree (default <span class="file">build/</span>)
</LI>
<LI>all files in directories named <span class="file">RCS</span>, <span class="file">CVS</span> or <span class="file">.svn</span>
</LI>
</UL>
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).

<P>
You can disable the default set of included files with the
<b class="programopt">--no-defaults</b> option, and you can disable the standard
exclude set with <b class="programopt">--no-prune</b>.

<P>
Following the Distutils' own manifest template, let's trace how the
<code class="du-command">sdist</code> command builds the list of files to include in the
Distutils source distribution:

<OL>
<LI>include all Python source files in the <span class="file">distutils</span> and
  <span class="file">distutils/command</span> subdirectories (because packages
  corresponding to those two directories were mentioned in the
  <span class="du-option">packages</span> option in the setup script--see
  section&nbsp;<A href="setup-script.html#setup-script">2</A>)
</LI>
<LI>include <span class="file">README.txt</span>, <span class="file">setup.py</span>, and <span class="file">setup.cfg</span>
  (standard files)
</LI>
<LI>include <span class="file">test/test*.py</span> (standard files)
</LI>
<LI>include <span class="file">*.txt</span> in the distribution root (this will find
  <span class="file">README.txt</span> a second time, but such redundancies are weeded out
  later)
</LI>
<LI>include anything matching <span class="file">*.txt</span> or <span class="file">*.py</span> in the
  sub-tree under <span class="file">examples</span>,
</LI>
<LI>exclude all files in the sub-trees starting at directories
  matching <span class="file">examples/sample?/build</span>--this may exclude files
  included by the previous two steps, so it's important that the
  <code>prune</code> command in the manifest template comes after the
  <code>recursive-include</code> command
</LI>
<LI>exclude the entire <span class="file">build</span> tree, and any <span class="file">RCS</span>,
  <span class="file">CVS</span> and <span class="file">.svn</span> directories
</LI>
</OL>
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.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4. Creating a Source"
  href="source-dist.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4. Creating a Source"
  href="source-dist.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.2 Manifest-related options"
  href="manifest-options.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="source-dist.html">4. Creating a Source</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="source-dist.html">4. Creating a Source</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="manifest-options.html">4.2 Manifest-related options</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>