Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / dist / built-dist.html
CommitLineData
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="package-index.html" />
12<link rel="prev" href="source-dist.html" />
13<link rel="parent" href="dist.html" />
14<link rel="next" href="creating-dumb.html" />
15<meta name='aesop' content='information' />
16<title>5. Creating Built Distributions</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.2 Manifest-related options"
24 href="manifest-options.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="5.1 Creating dumb built"
30 href="creating-dumb.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="manifest-options.html">4.2 Manifest-related options</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="creating-dumb.html">5.1 Creating dumb built</A>
48</div>
49<hr /></div>
50</DIV>
51<!--End of Navigation Panel-->
52
53<H1><A NAME="SECTION005000000000000000000"></A>
54<A NAME="built-dist"></A>
55<BR>
565. Creating Built Distributions
57</H1>
58
59<P>
60A ``built distribution'' is what you're probably used to thinking of
61either as a ``binary package'' or an ``installer'' (depending on your
62background). It's not necessarily binary, though, because it might
63contain only Python source code and/or byte-code; and we don't call it a
64package, because that word is already spoken for in Python. (And
65``installer'' is a term specific to the world of mainstream desktop
66systems.)
67
68<P>
69A built distribution is how you make life as easy as possible for
70installers of your module distribution: for users of RPM-based Linux
71systems, it's a binary RPM; for Windows users, it's an executable
72installer; for Debian-based Linux users, it's a Debian package; and so
73forth. Obviously, no one person will be able to create built
74distributions for every platform under the sun, so the Distutils are
75designed to enable module developers to concentrate on their
76specialty--writing code and creating source distributions--while an
77intermediary species called <em>packagers</em> springs up to turn source
78distributions into built distributions for as many platforms as there
79are packagers.
80
81<P>
82Of course, the module developer could be his own packager; or the
83packager could be a volunteer ``out there'' somewhere who has access to
84a platform which the original developer does not; or it could be
85software periodically grabbing new source distributions and turning them
86into built distributions for as many platforms as the software has
87access to. Regardless of who they are, a packager uses the
88setup script and the <code class="du-command">bdist</code> command family to generate built
89distributions.
90
91<P>
92As a simple example, if I run the following command in the Distutils
93source tree:
94
95<P>
96<div class="verbatim"><pre>
97python setup.py bdist
98</pre></div>
99
100<P>
101then the Distutils builds my module distribution (the Distutils itself
102in this case), does a ``fake'' installation (also in the <span class="file">build</span>
103directory), and creates the default type of built distribution for my
104platform. The default format for built distributions is a ``dumb'' tar
105file on <span class="Unix">Unix</span>, and a simple executable installer on Windows. (That tar
106file is considered ``dumb'' because it has to be unpacked in a specific
107location to work.)
108
109<P>
110Thus, the above command on a <span class="Unix">Unix</span> system creates
111<span class="file">Distutils-1.0.<span class="du-filevar">plat</span>.tar.gz</span>; unpacking this tarball
112from the right place installs the Distutils just as though you had
113downloaded the source distribution and run <code>python setup.py
114 install</code>. (The ``right place'' is either the root of the filesystem or
115Python's <span class="du-filevar">prefix</span> directory, depending on the options given to
116the <code class="du-command">bdist_dumb</code> command; the default is to make dumb
117distributions relative to <span class="du-filevar">prefix</span>.)
118
119<P>
120Obviously, for pure Python distributions, this isn't any simpler than
121just running <code>python setup.py install</code>--but for non-pure
122distributions, which include extensions that would need to be
123compiled, it can mean the difference between someone being able to use
124your extensions or not. And creating ``smart'' built distributions,
125such as an RPM package or an executable installer for Windows, is far
126more convenient for users even if your distribution doesn't include
127any extensions.
128
129<P>
130The <code class="du-command">bdist</code> command has a <b class="programopt">--formats</b> option,
131similar to the <code class="du-command">sdist</code> command, which you can use to select the
132types of built distribution to generate: for example,
133
134<P>
135<div class="verbatim"><pre>
136python setup.py bdist --format=zip
137</pre></div>
138
139<P>
140would, when run on a <span class="Unix">Unix</span> system, create
141<span class="file">Distutils-1.0.<span class="du-filevar">plat</span>.zip</span>--again, this archive would be
142unpacked from the root directory to install the Distutils.
143
144<P>
145The available formats for built distributions are:
146
147<P>
148<div class="center"><table class="realtable">
149 <thead>
150 <tr>
151 <th class="left" >Format</th>
152 <th class="left" >Description</th>
153 <th class="center">Notes</th>
154 </tr>
155 </thead>
156 <tbody>
157 <tr><td class="left" valign="baseline"><code>gztar</code></td>
158 <td class="left" >gzipped tar file (<span class="file">.tar.gz</span>)</td>
159 <td class="center">(1),(3)</td></tr>
160 <tr><td class="left" valign="baseline"><code>ztar</code></td>
161 <td class="left" >compressed tar file (<span class="file">.tar.Z</span>)</td>
162 <td class="center">(3)</td></tr>
163 <tr><td class="left" valign="baseline"><code>tar</code></td>
164 <td class="left" >tar file (<span class="file">.tar</span>)</td>
165 <td class="center">(3)</td></tr>
166 <tr><td class="left" valign="baseline"><code>zip</code></td>
167 <td class="left" >zip file (<span class="file">.zip</span>)</td>
168 <td class="center">(4)</td></tr>
169 <tr><td class="left" valign="baseline"><code>rpm</code></td>
170 <td class="left" >RPM</td>
171 <td class="center">(5)</td></tr>
172 <tr><td class="left" valign="baseline"><code>pkgtool</code></td>
173 <td class="left" >Solaris <b class="program">pkgtool</b></td>
174 <td class="center"></td></tr>
175 <tr><td class="left" valign="baseline"><code>sdux</code></td>
176 <td class="left" >HP-UX <b class="program">swinstall</b></td>
177 <td class="center"></td></tr>
178 <tr><td class="left" valign="baseline"><code>rpm</code></td>
179 <td class="left" >RPM</td>
180 <td class="center">(5)</td></tr>
181 <tr><td class="left" valign="baseline"><code>wininst</code></td>
182 <td class="left" >self-extracting ZIP file for Windows</td>
183 <td class="center">(2),(4)</td></tr></tbody>
184</table></div>
185
186<P>
187Notes:
188<DL>
189<DT><STRONG>(1)</STRONG></DT>
190<DD>default on <span class="Unix">Unix</span>
191</DD>
192<DT><STRONG>(2)</STRONG></DT>
193<DD>default on Windows <b class="du-xxx">to-do!</b>
194</DD>
195<DT><STRONG>(3)</STRONG></DT>
196<DD>requires external utilities: <b class="program">tar</b> and possibly one
197 of <b class="program">gzip</b>, <b class="program">bzip2</b>, or <b class="program">compress</b>
198</DD>
199<DT><STRONG>(4)</STRONG></DT>
200<DD>requires either external <b class="program">zip</b> utility or
201 <tt class="module">zipfile</tt> module (part of the standard Python library since
202 Python&nbsp;1.6)
203</DD>
204<DT><STRONG>(5)</STRONG></DT>
205<DD>requires external <b class="program">rpm</b> utility, version 3.0.4 or
206 better (use <code>rpm -&#45;version</code> to find out which version you have)
207</DD>
208</DL>
209
210<P>
211You don't have to use the <code class="du-command">bdist</code> command with the
212<b class="programopt">--formats</b> option; you can also use the command that
213directly implements the format you're interested in. Some of these
214<code class="du-command">bdist</code> ``sub-commands'' actually generate several similar
215formats; for instance, the <code class="du-command">bdist_dumb</code> command generates all
216the ``dumb'' archive formats (<code>tar</code>, <code>ztar</code>, <code>gztar</code>, and
217<code>zip</code>), and <code class="du-command">bdist_rpm</code> generates both binary and source
218RPMs. The <code class="du-command">bdist</code> sub-commands, and the formats generated by
219each, are:
220
221<P>
222<div class="center"><table class="realtable">
223 <thead>
224 <tr>
225 <th class="left" >Command</th>
226 <th class="left" >Formats</th>
227 </tr>
228 </thead>
229 <tbody>
230 <tr><td class="left" valign="baseline"><code>bdist_dumb</code></td>
231 <td class="left" >tar, ztar, gztar, zip</td></tr>
232 <tr><td class="left" valign="baseline"><code>bdist_rpm</code></td>
233 <td class="left" >rpm, srpm</td></tr>
234 <tr><td class="left" valign="baseline"><code>bdist_wininst</code></td>
235 <td class="left" >wininst</td></tr></tbody>
236</table></div>
237
238<P>
239The following sections give details on the individual <code class="du-command">bdist_*</code>
240commands.
241
242<P>
243
244<p><br /></p><hr class='online-navigation' />
245<div class='online-navigation'>
246<!--Table of Child-Links-->
247<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
248
249<UL CLASS="ChildLinks">
250<LI><A href="creating-dumb.html">5.1 Creating dumb built distributions</a>
251<LI><A href="creating-rpms.html">5.2 Creating RPM packages</a>
252<LI><A href="postinstallation-script.html">5.3 Creating Windows Installers</a>
253<UL>
254<LI><A href="postinstallation-script.html#SECTION005310000000000000000">5.3.1 The Postinstallation script</a>
255</ul></ul>
256<!--End of Table of Child-Links-->
257</div>
258
259<DIV CLASS="navigation">
260<div class='online-navigation'>
261<p></p><hr />
262<table align="center" width="100%" cellpadding="0" cellspacing="2">
263<tr>
264<td class='online-navigation'><a rel="prev" title="4.2 Manifest-related options"
265 href="manifest-options.html"><img src='../icons/previous.png'
266 border='0' height='32' alt='Previous Page' width='32' /></A></td>
267<td class='online-navigation'><a rel="parent" title="Distributing Python Modules"
268 href="dist.html"><img src='../icons/up.png'
269 border='0' height='32' alt='Up One Level' width='32' /></A></td>
270<td class='online-navigation'><a rel="next" title="5.1 Creating dumb built"
271 href="creating-dumb.html"><img src='../icons/next.png'
272 border='0' height='32' alt='Next Page' width='32' /></A></td>
273<td align="center" width="100%">Distributing Python Modules</td>
274<td class='online-navigation'><img src='../icons/blank.png'
275 border='0' height='32' alt='' width='32' /></td>
276<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
277 border='0' height='32' alt='Module Index' width='32' /></a></td>
278<td class='online-navigation'><a rel="index" title="Index"
279 href="genindex.html"><img src='../icons/index.png'
280 border='0' height='32' alt='Index' width='32' /></A></td>
281</tr></table>
282<div class='online-navigation'>
283<b class="navlabel">Previous:</b>
284<a class="sectref" rel="prev" href="manifest-options.html">4.2 Manifest-related options</A>
285<b class="navlabel">Up:</b>
286<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
287<b class="navlabel">Next:</b>
288<a class="sectref" rel="next" href="creating-dumb.html">5.1 Creating dumb built</A>
289</div>
290</div>
291<hr />
292<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
293</DIV>
294<!--End of Navigation Panel-->
295<ADDRESS>
296See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
297</ADDRESS>
298</BODY>
299</HTML>