sam-t2/devtools/v9/html/python/dist/built-dist.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="package-index.html" />
<link rel="prev" href="source-dist.html" />
<link rel="parent" href="dist.html" />
<link rel="next" href="creating-dumb.html" />
<meta name='aesop' content='information' />
<title>5. Creating Built Distributions</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.2 Manifest-related options"
  href="manifest-options.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="5.1 Creating dumb built"
  href="creating-dumb.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="manifest-options.html">4.2 Manifest-related options</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="creating-dumb.html">5.1 Creating dumb built</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION005000000000000000000"></A>
<A NAME="built-dist"></A>
<BR>
5. Creating Built Distributions
</H1>

<P>
A ``built distribution'' is what you're probably used to thinking of
either as a ``binary package'' or an ``installer'' (depending on your
background).  It's not necessarily binary, though, because it might
contain only Python source code and/or byte-code; and we don't call it a
package, because that word is already spoken for in Python.  (And
``installer'' is a term specific to the world of mainstream desktop
systems.)

<P>
A built distribution is how you make life as easy as possible for
installers of your module distribution: for users of RPM-based Linux
systems, it's a binary RPM; for Windows users, it's an executable
installer; for Debian-based Linux users, it's a Debian package; and so
forth.  Obviously, no one person will be able to create built
distributions for every platform under the sun, so the Distutils are
designed to enable module developers to concentrate on their
specialty--writing code and creating source distributions--while an
intermediary species called <em>packagers</em> springs up to turn source
distributions into built distributions for as many platforms as there
are packagers.

<P>
Of course, the module developer could be his own packager; or the
packager could be a volunteer ``out there'' somewhere who has access to
a platform which the original developer does not; or it could be
software periodically grabbing new source distributions and turning them
into built distributions for as many platforms as the software has
access to.  Regardless of who they are, a packager uses the
setup script and the <code class="du-command">bdist</code> command family to generate built
distributions.

<P>
As a simple example, if I run the following command in the Distutils
source tree:

<P>
<div class="verbatim"><pre>
python setup.py bdist
</pre></div>

<P>
then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the <span class="file">build</span>
directory), and creates the default type of built distribution for my
platform.  The default format for built distributions is a ``dumb'' tar
file on <span class="Unix">Unix</span>, and a simple executable installer on Windows.  (That tar
file is considered ``dumb'' because it has to be unpacked in a specific
location to work.)

<P>
Thus, the above command on a <span class="Unix">Unix</span> system creates
<span class="file">Distutils-1.0.<span class="du-filevar">plat</span>.tar.gz</span>; unpacking this tarball
from the right place installs the Distutils just as though you had
downloaded the source distribution and run <code>python setup.py
  install</code>.  (The ``right place'' is either the root of the filesystem or
Python's <span class="du-filevar">prefix</span> directory, depending on the options given to
the <code class="du-command">bdist_dumb</code> command; the default is to make dumb
distributions relative to <span class="du-filevar">prefix</span>.)

<P>
Obviously, for pure Python distributions, this isn't any simpler than
just running <code>python setup.py install</code>--but for non-pure
distributions, which include extensions that would need to be
compiled, it can mean the difference between someone being able to use
your extensions or not.  And creating ``smart'' built distributions,
such as an RPM package or an executable installer for Windows, is far
more convenient for users even if your distribution doesn't include
any extensions.

<P>
The <code class="du-command">bdist</code> command has a <b class="programopt">--formats</b> option,
similar to the <code class="du-command">sdist</code> command, which you can use to select the
types of built distribution to generate: for example,

<P>
<div class="verbatim"><pre>
python setup.py bdist --format=zip
</pre></div>

<P>
would, when run on a <span class="Unix">Unix</span> system, create
<span class="file">Distutils-1.0.<span class="du-filevar">plat</span>.zip</span>--again, this archive would be
unpacked from the root directory to install the Distutils.

<P>
The available formats for built distributions are:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Format</th>
      <th class="left"  >Description</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><code>gztar</code></td>
        <td class="left"  >gzipped tar file (<span class="file">.tar.gz</span>)</td>
        <td class="center">(1),(3)</td></tr>
    <tr><td class="left"   valign="baseline"><code>ztar</code></td>
        <td class="left"  >compressed tar file (<span class="file">.tar.Z</span>)</td>
        <td class="center">(3)</td></tr>
    <tr><td class="left"   valign="baseline"><code>tar</code></td>
        <td class="left"  >tar file (<span class="file">.tar</span>)</td>
        <td class="center">(3)</td></tr>
    <tr><td class="left"   valign="baseline"><code>zip</code></td>
        <td class="left"  >zip file (<span class="file">.zip</span>)</td>
        <td class="center">(4)</td></tr>
    <tr><td class="left"   valign="baseline"><code>rpm</code></td>
        <td class="left"  >RPM</td>
        <td class="center">(5)</td></tr>
    <tr><td class="left"   valign="baseline"><code>pkgtool</code></td>
        <td class="left"  >Solaris <b class="program">pkgtool</b></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>sdux</code></td>
        <td class="left"  >HP-UX <b class="program">swinstall</b></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>rpm</code></td>
        <td class="left"  >RPM</td>
        <td class="center">(5)</td></tr>
    <tr><td class="left"   valign="baseline"><code>wininst</code></td>
        <td class="left"  >self-extracting ZIP file for Windows</td>
        <td class="center">(2),(4)</td></tr></tbody>
</table></div>

<P>
Notes:
<DL>
<DT><STRONG>(1)</STRONG></DT>
<DD>default on <span class="Unix">Unix</span>
</DD>
<DT><STRONG>(2)</STRONG></DT>
<DD>default on Windows <b class="du-xxx">to-do!</b>
</DD>
<DT><STRONG>(3)</STRONG></DT>
<DD>requires external utilities: <b class="program">tar</b> and possibly one
  of <b class="program">gzip</b>, <b class="program">bzip2</b>, or <b class="program">compress</b>
</DD>
<DT><STRONG>(4)</STRONG></DT>
<DD>requires either external <b class="program">zip</b> utility or
  <tt class="module">zipfile</tt> module (part of the standard Python library since
  Python&nbsp;1.6)
</DD>
<DT><STRONG>(5)</STRONG></DT>
<DD>requires external <b class="program">rpm</b> utility, version 3.0.4 or
  better (use <code>rpm -&#45;version</code> to find out which version you have)
</DD>
</DL>

<P>
You don't have to use the <code class="du-command">bdist</code> command with the
<b class="programopt">--formats</b> option; you can also use the command that
directly implements the format you're interested in.  Some of these
<code class="du-command">bdist</code> ``sub-commands'' actually generate several similar
formats; for instance, the <code class="du-command">bdist_dumb</code> command generates all
the ``dumb'' archive formats (<code>tar</code>, <code>ztar</code>, <code>gztar</code>, and
<code>zip</code>), and <code class="du-command">bdist_rpm</code> generates both binary and source
RPMs.  The <code class="du-command">bdist</code> sub-commands, and the formats generated by
each, are:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Command</th>
      <th class="left"  >Formats</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><code>bdist_dumb</code></td>
        <td class="left"  >tar, ztar, gztar, zip</td></tr>
    <tr><td class="left"   valign="baseline"><code>bdist_rpm</code></td>
        <td class="left"  >rpm, srpm</td></tr>
    <tr><td class="left"   valign="baseline"><code>bdist_wininst</code></td>
        <td class="left"  >wininst</td></tr></tbody>
</table></div>

<P>
The following sections give details on the individual <code class="du-command">bdist_*</code>
commands.

<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="creating-dumb.html">5.1 Creating dumb built distributions</a>
<LI><A href="creating-rpms.html">5.2 Creating RPM packages</a>
<LI><A href="postinstallation-script.html">5.3 Creating Windows Installers</a>
<UL>
<LI><A href="postinstallation-script.html#SECTION005310000000000000000">5.3.1 The Postinstallation script</a>
</ul></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="4.2 Manifest-related options"
  href="manifest-options.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="5.1 Creating dumb built"
  href="creating-dumb.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="manifest-options.html">4.2 Manifest-related options</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="creating-dumb.html">5.1 Creating dumb built</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>