[OpenSPARC-T2-SAM] / 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="dist.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="dist.html" title='Distributing Python Modules' />
	8	<link rel='index' href='genindex.html' title='Index' />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="manifest-options.html" />
	12	<link rel="prev" href="source-dist.html" />
	13	<link rel="parent" href="source-dist.html" />
	14	<link rel="next" href="manifest-options.html" />
	15	<meta name='aesop' content='information' />
	16	<title>4.1 Specifying the files to distribute</title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="4. Creating a Source"
	24	href="source-dist.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="4. Creating a Source"
	27	href="source-dist.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="4.2 Manifest-related options"
	30	href="manifest-options.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Distributing Python Modules</td>
	33	<td class='online-navigation'><img src='../icons/blank.png'
	34	border='0' height='32' alt='' width='32' /></td>
	35	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	36	border='0' height='32' alt='Module Index' width='32' /></a></td>
	37	<td class='online-navigation'><a rel="index" title="Index"
	38	href="genindex.html"><img src='../icons/index.png'
	39	border='0' height='32' alt='Index' width='32' /></A></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="source-dist.html">4. Creating a Source</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="source-dist.html">4. Creating a Source</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="manifest-options.html">4.2 Manifest-related options</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION004100000000000000000"></A>
	54	<A NAME="manifest"></A>
	55	<BR>
	56	4.1 Specifying the files to distribute
	57	</H1>
	58
	59	<P>
	60	If you don't supply an explicit list of files (or instructions on how to
	61	generate one), the <code class="du-command">sdist</code> command puts a minimal default set
	62	into the source distribution:
	63
	64	<UL>
65	<LI>all Python source files implied by the <span class="du-option">py_modules</span> and
66	<span class="du-option">packages</span> options
67	</LI>
68	<LI>all C source files mentioned in the <span class="du-option">ext_modules</span> or
69	<span class="du-option">libraries</span> options (<b class="du-xxx">getting C library sources currently
70	broken--no <tt class="method">get_source_files()</tt> method in <span class="file">build_clib.py</span>!</b>)
71	</LI>
72	<LI>scripts identified by the <span class="du-option">scripts</span> option
73	</LI>
74	<LI>anything that looks like a test script: <span class="file">test/test*.py</span>
75	(currently, the Distutils don't do anything with test scripts except
76	include them in source distributions, but in the future there will be
77	a standard for testing Python module distributions)
78	</LI>
79	<LI><span class="file">README.txt</span> (or <span class="file">README</span>), <span class="file">setup.py</span> (or whatever
80	you called your setup script), and <span class="file">setup.cfg</span>
81	</LI>
82	</UL>
83
84	<P>
85	Sometimes this is enough, but usually you will want to specify
86	additional files to distribute. The typical way to do this is to write
87	a <em>manifest template</em>, called <span class="file">MANIFEST.in</span> by default. The
88	manifest template is just a list of instructions for how to generate
89	your manifest file, <span class="file">MANIFEST</span>, which is the exact list of files to
90	include in your source distribution. The <code class="du-command">sdist</code> command
91	processes this template and generates a manifest based on its
92	instructions and what it finds in the filesystem.
93
94	<P>
95	If you prefer to roll your own manifest file, the format is simple: one
96	filename per line, regular files (or symlinks to them) only. If you do
97	supply your own <span class="file">MANIFEST</span>, you must specify everything: the
98	default set of files described above does not apply in this case.
99
100	<P>
101	The manifest template has one command per line, where each command
102	specifies a set of files to include or exclude from the source
103	distribution. For an example, again we turn to the Distutils' own
104	manifest template:
105
106	<P>
107	<div class="verbatim"><pre>
108	include *.txt
109	recursive-include examples .txt .py
110	prune examples/sample?/build
111	</pre></div>
112
113	<P>
114	The meanings should be fairly clear: include all files in the
115	distribution root matching <span class="file">*.txt</span>, all files anywhere under the
116	<span class="file">examples</span> directory matching <span class="file">.txt</span> or <span class="file">.py</span>, and
117	exclude all directories matching <span class="file">examples/sample?/build</span>. All of
118	this is done <em>after</em> the standard include set, so you can exclude
119	files from the standard set with explicit instructions in the manifest
120	template. (Or, you can use the <b class="programopt">--no-defaults</b> option to
121	disable the standard set entirely.) There are several other commands
122	available in the manifest template mini-language; see
123	section <A href="sdist-cmd.html#sdist-cmd">9.2</A>.
124
125	<P>
126	The order of commands in the manifest template matters: initially, we
127	have the list of default files as described above, and each command in
128	the template adds to or removes from that list of files. Once we have
129	fully processed the manifest template, we remove files that should not
130	be included in the source distribution:
131
132	<UL>
133	<LI>all files in the Distutils ``build'' tree (default <span class="file">build/</span>)
134	</LI>
135	<LI>all files in directories named <span class="file">RCS</span>, <span class="file">CVS</span> or <span class="file">.svn</span>
136	</LI>
137	</UL>
138	Now we have our complete list of files, which is written to the manifest
139	for future reference, and then used to build the source distribution
140	archive(s).
141
142	<P>
143	You can disable the default set of included files with the
144	<b class="programopt">--no-defaults</b> option, and you can disable the standard
145	exclude set with <b class="programopt">--no-prune</b>.
146
147	<P>
148	Following the Distutils' own manifest template, let's trace how the
149	<code class="du-command">sdist</code> command builds the list of files to include in the
150	Distutils source distribution:
151
152	<OL>
153	<LI>include all Python source files in the <span class="file">distutils</span> and
154	<span class="file">distutils/command</span> subdirectories (because packages
155	corresponding to those two directories were mentioned in the
156	<span class="du-option">packages</span> option in the setup script--see
157	section <A href="setup-script.html#setup-script">2</A>)
158	</LI>
159	<LI>include <span class="file">README.txt</span>, <span class="file">setup.py</span>, and <span class="file">setup.cfg</span>
160	(standard files)
161	</LI>
162	<LI>include <span class="file">test/test*.py</span> (standard files)
163	</LI>
164	<LI>include <span class="file">*.txt</span> in the distribution root (this will find
165	<span class="file">README.txt</span> a second time, but such redundancies are weeded out
166	later)
167	</LI>
168	<LI>include anything matching <span class="file">.txt</span> or <span class="file">.py</span> in the
169	sub-tree under <span class="file">examples</span>,
170	</LI>
171	<LI>exclude all files in the sub-trees starting at directories
172	matching <span class="file">examples/sample?/build</span>--this may exclude files
173	included by the previous two steps, so it's important that the
174	<code>prune</code> command in the manifest template comes after the
175	<code>recursive-include</code> command
176	</LI>
177	<LI>exclude the entire <span class="file">build</span> tree, and any <span class="file">RCS</span>,
178	<span class="file">CVS</span> and <span class="file">.svn</span> directories
179	</LI>
180	</OL>
181	Just like in the setup script, file and directory names in the manifest
182	template should always be slash-separated; the Distutils will take care
183	of converting them to the standard representation on your platform.
184	That way, the manifest template is portable across operating systems.
185
186	<P>
187
188	<DIV CLASS="navigation">
189	<div class='online-navigation'>
190	<p></p><hr />
191	<table align="center" width="100%" cellpadding="0" cellspacing="2">
192	<tr>
193	<td class='online-navigation'><a rel="prev" title="4. Creating a Source"
194	href="source-dist.html"><img src='../icons/previous.png'
195	border='0' height='32' alt='Previous Page' width='32' /></A></td>
196	<td class='online-navigation'><a rel="parent" title="4. Creating a Source"
197	href="source-dist.html"><img src='../icons/up.png'
198	border='0' height='32' alt='Up One Level' width='32' /></A></td>
199	<td class='online-navigation'><a rel="next" title="4.2 Manifest-related options"
200	href="manifest-options.html"><img src='../icons/next.png'
201	border='0' height='32' alt='Next Page' width='32' /></A></td>
202	<td align="center" width="100%">Distributing Python Modules</td>
203	<td class='online-navigation'><img src='../icons/blank.png'
204	border='0' height='32' alt='' width='32' /></td>
205	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
206	border='0' height='32' alt='Module Index' width='32' /></a></td>
207	<td class='online-navigation'><a rel="index" title="Index"
208	href="genindex.html"><img src='../icons/index.png'
209	border='0' height='32' alt='Index' width='32' /></A></td>
210	</tr></table>
211	<div class='online-navigation'>
212	<b class="navlabel">Previous:</b>
213	<a class="sectref" rel="prev" href="source-dist.html">4. Creating a Source</A>
214	<b class="navlabel">Up:</b>
215	<a class="sectref" rel="parent" href="source-dist.html">4. Creating a Source</A>
216	<b class="navlabel">Next:</b>
217	<a class="sectref" rel="next" href="manifest-options.html">4.2 Manifest-related options</A>
218	</div>
219	</div>
220	<hr />
221	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
222	</DIV>
223	<!--End of Navigation Panel-->
224	<ADDRESS>
225	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
226	</ADDRESS>
227	</BODY>
228	</HTML>