[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / dist / setup-script.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="setup-config.html" />
<link rel="prev" href="intro.html" />
<link rel="parent" href="dist.html" />
<link rel="next" href="listing-packages.html" />
<meta name='aesop' content='information' />
<title>2. Writing the Setup Script</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="1.4 Distutils-specific terminology"
  href="distutils-term.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="Distributing Python Modules"
  href="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="2.1 Listing whole packages"
  href="listing-packages.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="distutils-term.html">1.4 Distutils-specific terminology</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="listing-packages.html">2.1 Listing whole packages</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION002000000000000000000"></A>
<A NAME="setup-script"></A>
<BR>
2. Writing the Setup Script
</H1>

<P>
The setup script is the centre of all activity in building,
distributing, and installing modules using the Distutils.  The main
purpose of the setup script is to describe your module distribution to
the Distutils, so that the various commands that operate on your modules
do the right thing.  As we saw in section&nbsp;<A href="simple-example.html#simple-example">1.2</A> above,
the setup script consists mainly of a call to <tt class="function">setup()</tt>, and
most information supplied to the Distutils by the module developer is
supplied as keyword arguments to <tt class="function">setup()</tt>.

<P>
Here's a slightly more involved example, which we'll follow for the next
couple of sections: the Distutils' own setup script.  (Keep in mind that
although the Distutils are included with Python 1.6 and later, they also
have an independent existence so that Python 1.5.2 users can use them to
install other module distributions.  The Distutils' own setup script,
shown here, is used to install the package into Python 1.5.2.)

<P>
<div class="verbatim"><pre>
#!/usr/bin/env python

from distutils.core import setup

setup(name='Distutils',
      version='1.0',
      description='Python Distribution Utilities',
      author='Greg Ward',
      author_email='gward@python.net',
      url='http://www.python.org/sigs/distutils-sig/',
      packages=['distutils', 'distutils.command'],
     )
</pre></div>

<P>
There are only two differences between this and the trivial one-file
distribution presented in section&nbsp;<A href="simple-example.html#simple-example">1.2</A>: more
metadata, and the specification of pure Python modules by package,
rather than by module.  This is important since the Distutils consist of
a couple of dozen modules split into (so far) two packages; an explicit
list of every module would be tedious to generate and difficult to
maintain.  For more information on the additional meta-data, see
section&nbsp;<A href="meta-data.html#meta-data">2.7</A>.

<P>
Note that any pathnames (files or directories) supplied in the setup
script should be written using the <span class="Unix">Unix</span> convention, i.e.
slash-separated.  The Distutils will take care of converting this
platform-neutral representation into whatever is appropriate on your
current platform before actually using the pathname.  This makes your
setup script portable across operating systems, which of course is one
of the major goals of the Distutils.  In this spirit, all pathnames in
this document are slash-separated.  (Mac OS 9 programmers should keep in
mind that the <em>absence</em> of a leading slash indicates a relative
path, the opposite of the Mac OS convention with colons.)

<P>
This, of course, only applies to pathnames given to Distutils
functions.  If you, for example, use standard Python functions such as
<tt class="function">glob.glob()</tt> or <tt class="function">os.listdir()</tt> to specify files, you
should be careful to write portable code instead of hardcoding path
separators:

<P>
<div class="verbatim"><pre>
    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
    os.listdir(os.path.join('mydir', 'subdir'))
</pre></div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="listing-packages.html">2.1 Listing whole packages</a>
<LI><A href="listing-modules.html">2.2 Listing individual modules</a>
<LI><A href="describing-extensions.html">2.3 Describing extension modules</a>
<UL>
<LI><A href="describing-extensions.html#SECTION002310000000000000000">2.3.1 Extension names and packages</a>
<LI><A href="describing-extensions.html#SECTION002320000000000000000">2.3.2 Extension source files</a>
<LI><A href="describing-extensions.html#SECTION002330000000000000000">2.3.3 Preprocessor options</a>
<LI><A href="describing-extensions.html#SECTION002340000000000000000">2.3.4 Library options</a>
<LI><A href="describing-extensions.html#SECTION002350000000000000000">2.3.5 Other options</a>
</ul>
<LI><A href="node10.html">2.4 Installing Scripts</a>
<LI><A href="node11.html">2.5 Installing Package Data</a>
<LI><A href="node12.html">2.6 Installing Additional Files</a>
<LI><A href="meta-data.html">2.7 Additional meta-data</a>
<LI><A href="node14.html">2.8 Debugging the setup script</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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="1.4 Distutils-specific terminology"
  href="distutils-term.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="Distributing Python Modules"
  href="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="2.1 Listing whole packages"
  href="listing-packages.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="distutils-term.html">1.4 Distutils-specific terminology</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="listing-packages.html">2.1 Listing whole packages</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
86530b38 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="setup-config.html" />
	12	<link rel="prev" href="intro.html" />
	13	<link rel="parent" href="dist.html" />
	14	<link rel="next" href="listing-packages.html" />
	15	<meta name='aesop' content='information' />
	16	<title>2. Writing the Setup Script</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="1.4 Distutils-specific terminology"
	24	href="distutils-term.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="Distributing Python Modules"
	27	href="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="2.1 Listing whole packages"
	30	href="listing-packages.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="distutils-term.html">1.4 Distutils-specific terminology</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="listing-packages.html">2.1 Listing whole packages</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION002000000000000000000"></A>
	54	<A NAME="setup-script"></A>
	55	<BR>
	56	2. Writing the Setup Script
	57	</H1>
	58
	59	<P>
	60	The setup script is the centre of all activity in building,
	61	distributing, and installing modules using the Distutils. The main
	62	purpose of the setup script is to describe your module distribution to
	63	the Distutils, so that the various commands that operate on your modules
	64	do the right thing. As we saw in section <A href="simple-example.html#simple-example">1.2</A> above,
65	the setup script consists mainly of a call to <tt class="function">setup()</tt>, and
66	most information supplied to the Distutils by the module developer is
67	supplied as keyword arguments to <tt class="function">setup()</tt>.
68
69	<P>
70	Here's a slightly more involved example, which we'll follow for the next
71	couple of sections: the Distutils' own setup script. (Keep in mind that
72	although the Distutils are included with Python 1.6 and later, they also
73	have an independent existence so that Python 1.5.2 users can use them to
74	install other module distributions. The Distutils' own setup script,
75	shown here, is used to install the package into Python 1.5.2.)
76
77	<P>
78	<div class="verbatim"><pre>
79	#!/usr/bin/env python
80
81	from distutils.core import setup
82
83	setup(name='Distutils',
84	version='1.0',
85	description='Python Distribution Utilities',
86	author='Greg Ward',
87	author_email='gward@python.net',
88	url='http://www.python.org/sigs/distutils-sig/',
89	packages=['distutils', 'distutils.command'],
90	)
91	</pre></div>
92
93	<P>
94	There are only two differences between this and the trivial one-file
95	distribution presented in section <A href="simple-example.html#simple-example">1.2</A>: more
96	metadata, and the specification of pure Python modules by package,
97	rather than by module. This is important since the Distutils consist of
98	a couple of dozen modules split into (so far) two packages; an explicit
99	list of every module would be tedious to generate and difficult to
100	maintain. For more information on the additional meta-data, see
101	section <A href="meta-data.html#meta-data">2.7</A>.
102
103	<P>
104	Note that any pathnames (files or directories) supplied in the setup
105	script should be written using the <span class="Unix">Unix</span> convention, i.e.
106	slash-separated. The Distutils will take care of converting this
107	platform-neutral representation into whatever is appropriate on your
108	current platform before actually using the pathname. This makes your
109	setup script portable across operating systems, which of course is one
110	of the major goals of the Distutils. In this spirit, all pathnames in
111	this document are slash-separated. (Mac OS 9 programmers should keep in
112	mind that the <em>absence</em> of a leading slash indicates a relative
113	path, the opposite of the Mac OS convention with colons.)
114
115	<P>
116	This, of course, only applies to pathnames given to Distutils
117	functions. If you, for example, use standard Python functions such as
118	<tt class="function">glob.glob()</tt> or <tt class="function">os.listdir()</tt> to specify files, you
119	should be careful to write portable code instead of hardcoding path
120	separators:
121
122	<P>
123	<div class="verbatim"><pre>
124	glob.glob(os.path.join('mydir', 'subdir', '*.html'))
125	os.listdir(os.path.join('mydir', 'subdir'))
126	</pre></div>
127
128	<P>
129
130	<p><br /></p><hr class='online-navigation' />
131	<div class='online-navigation'>
132	<!--Table of Child-Links-->
133	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
134
135	<UL CLASS="ChildLinks">
136	<LI><A href="listing-packages.html">2.1 Listing whole packages</a>
137	<LI><A href="listing-modules.html">2.2 Listing individual modules</a>
138	<LI><A href="describing-extensions.html">2.3 Describing extension modules</a>
139	<UL>
140	<LI><A href="describing-extensions.html#SECTION002310000000000000000">2.3.1 Extension names and packages</a>
141	<LI><A href="describing-extensions.html#SECTION002320000000000000000">2.3.2 Extension source files</a>
142	<LI><A href="describing-extensions.html#SECTION002330000000000000000">2.3.3 Preprocessor options</a>
143	<LI><A href="describing-extensions.html#SECTION002340000000000000000">2.3.4 Library options</a>
144	<LI><A href="describing-extensions.html#SECTION002350000000000000000">2.3.5 Other options</a>
145	</ul>
146	<LI><A href="node10.html">2.4 Installing Scripts</a>
147	<LI><A href="node11.html">2.5 Installing Package Data</a>
148	<LI><A href="node12.html">2.6 Installing Additional Files</a>
149	<LI><A href="meta-data.html">2.7 Additional meta-data</a>
150	<LI><A href="node14.html">2.8 Debugging the setup script</a>
151	</ul>
152	<!--End of Table of Child-Links-->
153	</div>
154
155	<DIV CLASS="navigation">
156	<div class='online-navigation'>
157	<p></p><hr />
158	<table align="center" width="100%" cellpadding="0" cellspacing="2">
159	<tr>
160	<td class='online-navigation'><a rel="prev" title="1.4 Distutils-specific terminology"
161	href="distutils-term.html"><img src='../icons/previous.png'
162	border='0' height='32' alt='Previous Page' width='32' /></A></td>
163	<td class='online-navigation'><a rel="parent" title="Distributing Python Modules"
164	href="dist.html"><img src='../icons/up.png'
165	border='0' height='32' alt='Up One Level' width='32' /></A></td>
166	<td class='online-navigation'><a rel="next" title="2.1 Listing whole packages"
167	href="listing-packages.html"><img src='../icons/next.png'
168	border='0' height='32' alt='Next Page' width='32' /></A></td>
169	<td align="center" width="100%">Distributing Python Modules</td>
170	<td class='online-navigation'><img src='../icons/blank.png'
171	border='0' height='32' alt='' width='32' /></td>
172	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
173	border='0' height='32' alt='Module Index' width='32' /></a></td>
174	<td class='online-navigation'><a rel="index" title="Index"
175	href="genindex.html"><img src='../icons/index.png'
176	border='0' height='32' alt='Index' width='32' /></A></td>
177	</tr></table>
178	<div class='online-navigation'>
179	<b class="navlabel">Previous:</b>
180	<a class="sectref" rel="prev" href="distutils-term.html">1.4 Distutils-specific terminology</A>
181	<b class="navlabel">Up:</b>
182	<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
183	<b class="navlabel">Next:</b>
184	<a class="sectref" rel="next" href="listing-packages.html">2.1 Listing whole packages</A>
185	</div>
186	</div>
187	<hr />
188	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
189	</DIV>
190	<!--End of Navigation Panel-->
191	<ADDRESS>
192	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
193	</ADDRESS>
194	</BODY>
195	</HTML>