[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / dist / listing-packages.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="listing-modules.html" />
<link rel="prev" href="setup-script.html" />
<link rel="parent" href="setup-script.html" />
<link rel="next" href="listing-modules.html" />
<meta name='aesop' content='information' />
<title>2.1 Listing whole packages</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="2. Writing the Setup"
  href="setup-script.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="2. Writing the Setup"
  href="setup-script.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="2.2 Listing individual modules"
  href="listing-modules.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="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="listing-modules.html">2.2 Listing individual modules</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION002100000000000000000"></A>
<A NAME="listing-packages"></A>
<BR>
2.1 Listing whole packages
</H1>

<P>
The <span class="du-option">packages</span> option tells the Distutils to process (build,
distribute, install, etc.) all pure Python modules found in each package
mentioned in the <span class="du-option">packages</span> list.  In order to do this, of
course, there has to be a correspondence between package names and
directories in the filesystem.  The default correspondence is the most
obvious one, i.e. package <tt class="module">distutils</tt> is found in the directory
<span class="file">distutils</span> relative to the distribution root.  Thus, when you say
<code>packages = ['foo']</code> in your setup script, you are promising that
the Distutils will find a file <span class="file">foo/__init__.py</span> (which might
be spelled differently on your system, but you get the idea) relative to
the directory where your setup script lives.  If you break this
promise, the Distutils will issue a warning but still process the broken
package anyways.

<P>
If you use a different convention to lay out your source directory,
that's no problem: you just have to supply the <span class="du-option">package_dir</span>
option to tell the Distutils about your convention.  For example, say
you keep all Python source under <span class="file">lib</span>, so that modules in the
``root package'' (i.e., not in any package at all) are in
<span class="file">lib</span>, modules in the <tt class="module">foo</tt> package are in <span class="file">lib/foo</span>,
and so forth.  Then you would put

<P>
<div class="verbatim"><pre>
package_dir = {'': 'lib'}
</pre></div>

<P>
in your setup script.  The keys to this dictionary are package names,
and an empty package name stands for the root package.  The values are
directory names relative to your distribution root.  In this case, when
you say <code>packages = ['foo']</code>, you are promising that the file
<span class="file">lib/foo/__init__.py</span> exists.

<P>
Another possible convention is to put the <tt class="module">foo</tt> package right in 
<span class="file">lib</span>, the <tt class="module">foo.bar</tt> package in <span class="file">lib/bar</span>, etc.  This
would be written in the setup script as

<P>
<div class="verbatim"><pre>
package_dir = {'foo': 'lib'}
</pre></div>

<P>
A <code><var>package</var>: <var>dir</var></code> entry in the <span class="du-option">package_dir</span>
dictionary implicitly applies to all packages below <var>package</var>, so
the <tt class="module">foo.bar</tt> case is automatically handled here.  In this
example, having <code>packages = ['foo', 'foo.bar']</code> tells the Distutils
to look for <span class="file">lib/__init__.py</span> and
<span class="file">lib/bar/__init__.py</span>.  (Keep in mind that although
<span class="du-option">package_dir</span> applies recursively, you must explicitly list all
packages in <span class="du-option">packages</span>: the Distutils will <em>not</em> recursively
scan your source tree looking for any directory with an
<span class="file">__init__.py</span> file.)

<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="2. Writing the Setup"
  href="setup-script.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="2. Writing the Setup"
  href="setup-script.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="2.2 Listing individual modules"
  href="listing-modules.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="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="listing-modules.html">2.2 Listing individual modules</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="listing-modules.html" />
	12	<link rel="prev" href="setup-script.html" />
	13	<link rel="parent" href="setup-script.html" />
	14	<link rel="next" href="listing-modules.html" />
	15	<meta name='aesop' content='information' />
	16	<title>2.1 Listing whole packages</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="2. Writing the Setup"
	24	href="setup-script.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="2. Writing the Setup"
	27	href="setup-script.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="2.2 Listing individual modules"
	30	href="listing-modules.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="setup-script.html">2. Writing the Setup</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="listing-modules.html">2.2 Listing individual modules</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION002100000000000000000"></A>
	54	<A NAME="listing-packages"></A>
	55	<BR>
	56	2.1 Listing whole packages
	57	</H1>
	58
	59	<P>
	60	The <span class="du-option">packages</span> option tells the Distutils to process (build,
	61	distribute, install, etc.) all pure Python modules found in each package
	62	mentioned in the <span class="du-option">packages</span> list. In order to do this, of
	63	course, there has to be a correspondence between package names and
	64	directories in the filesystem. The default correspondence is the most
65	obvious one, i.e. package <tt class="module">distutils</tt> is found in the directory
66	<span class="file">distutils</span> relative to the distribution root. Thus, when you say
67	<code>packages = ['foo']</code> in your setup script, you are promising that
68	the Distutils will find a file <span class="file">foo/__init__.py</span> (which might
69	be spelled differently on your system, but you get the idea) relative to
70	the directory where your setup script lives. If you break this
71	promise, the Distutils will issue a warning but still process the broken
72	package anyways.
73
74	<P>
75	If you use a different convention to lay out your source directory,
76	that's no problem: you just have to supply the <span class="du-option">package_dir</span>
77	option to tell the Distutils about your convention. For example, say
78	you keep all Python source under <span class="file">lib</span>, so that modules in the
79	``root package'' (i.e., not in any package at all) are in
80	<span class="file">lib</span>, modules in the <tt class="module">foo</tt> package are in <span class="file">lib/foo</span>,
81	and so forth. Then you would put
82
83	<P>
84	<div class="verbatim"><pre>
85	package_dir = {'': 'lib'}
86	</pre></div>
87
88	<P>
89	in your setup script. The keys to this dictionary are package names,
90	and an empty package name stands for the root package. The values are
91	directory names relative to your distribution root. In this case, when
92	you say <code>packages = ['foo']</code>, you are promising that the file
93	<span class="file">lib/foo/__init__.py</span> exists.
94
95	<P>
96	Another possible convention is to put the <tt class="module">foo</tt> package right in
97	<span class="file">lib</span>, the <tt class="module">foo.bar</tt> package in <span class="file">lib/bar</span>, etc. This
98	would be written in the setup script as
99
100	<P>
101	<div class="verbatim"><pre>
102	package_dir = {'foo': 'lib'}
103	</pre></div>
104
105	<P>
106	A <code><var>package</var>: <var>dir</var></code> entry in the <span class="du-option">package_dir</span>
107	dictionary implicitly applies to all packages below <var>package</var>, so
108	the <tt class="module">foo.bar</tt> case is automatically handled here. In this
109	example, having <code>packages = ['foo', 'foo.bar']</code> tells the Distutils
110	to look for <span class="file">lib/__init__.py</span> and
111	<span class="file">lib/bar/__init__.py</span>. (Keep in mind that although
112	<span class="du-option">package_dir</span> applies recursively, you must explicitly list all
113	packages in <span class="du-option">packages</span>: the Distutils will <em>not</em> recursively
114	scan your source tree looking for any directory with an
115	<span class="file">__init__.py</span> file.)
116
117	<P>
118
119	<DIV CLASS="navigation">
120	<div class='online-navigation'>
121	<p></p><hr />
122	<table align="center" width="100%" cellpadding="0" cellspacing="2">
123	<tr>
124	<td class='online-navigation'><a rel="prev" title="2. Writing the Setup"
125	href="setup-script.html"><img src='../icons/previous.png'
126	border='0' height='32' alt='Previous Page' width='32' /></A></td>
127	<td class='online-navigation'><a rel="parent" title="2. Writing the Setup"
128	href="setup-script.html"><img src='../icons/up.png'
129	border='0' height='32' alt='Up One Level' width='32' /></A></td>
130	<td class='online-navigation'><a rel="next" title="2.2 Listing individual modules"
131	href="listing-modules.html"><img src='../icons/next.png'
132	border='0' height='32' alt='Next Page' width='32' /></A></td>
133	<td align="center" width="100%">Distributing Python Modules</td>
134	<td class='online-navigation'><img src='../icons/blank.png'
135	border='0' height='32' alt='' width='32' /></td>
136	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
137	border='0' height='32' alt='Module Index' width='32' /></a></td>
138	<td class='online-navigation'><a rel="index" title="Index"
139	href="genindex.html"><img src='../icons/index.png'
140	border='0' height='32' alt='Index' width='32' /></A></td>
141	</tr></table>
142	<div class='online-navigation'>
143	<b class="navlabel">Previous:</b>
144	<a class="sectref" rel="prev" href="setup-script.html">2. Writing the Setup</A>
145	<b class="navlabel">Up:</b>
146	<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
147	<b class="navlabel">Next:</b>
148	<a class="sectref" rel="next" href="listing-modules.html">2.2 Listing individual modules</A>
149	</div>
150	</div>
151	<hr />
152	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
153	</DIV>
154	<!--End of Navigation Panel-->
155	<ADDRESS>
156	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
157	</ADDRESS>
158	</BODY>
159	</HTML>