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="python-terms.html" /> | |
12 | <link rel="prev" href="concepts.html" /> | |
13 | <link rel="parent" href="intro.html" /> | |
14 | <link rel="next" href="python-terms.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>1.2 A Simple Example</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.1 Concepts & Terminology" | |
24 | href="concepts.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="1. An Introduction to" | |
27 | href="intro.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="1.3 General Python terminology" | |
30 | href="python-terms.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="concepts.html">1.1 Concepts & Terminology</A> | |
44 | <b class="navlabel">Up:</b> | |
45 | <a class="sectref" rel="parent" href="intro.html">1. An Introduction to</A> | |
46 | <b class="navlabel">Next:</b> | |
47 | <a class="sectref" rel="next" href="python-terms.html">1.3 General Python terminology</A> | |
48 | </div> | |
49 | <hr /></div> | |
50 | </DIV> | |
51 | <!--End of Navigation Panel--> | |
52 | ||
53 | <H1><A NAME="SECTION001200000000000000000"></A> | |
54 | <A NAME="simple-example"></A> | |
55 | <BR> | |
56 | 1.2 A Simple Example | |
57 | </H1> | |
58 | ||
59 | <P> | |
60 | The setup script is usually quite simple, although since it's written | |
61 | in Python, there are no arbitrary limits to what you can do with it, | |
62 | though you should be careful about putting arbitrarily expensive | |
63 | operations in your setup script. Unlike, say, Autoconf-style configure | |
64 | scripts, the setup script may be run multiple times in the course of | |
65 | building and installing your module distribution. | |
66 | ||
67 | <P> | |
68 | If all you want to do is distribute a module called <tt class="module">foo</tt>, | |
69 | contained in a file <span class="file">foo.py</span>, then your setup script can be as | |
70 | simple as this: | |
71 | ||
72 | <P> | |
73 | <div class="verbatim"><pre> | |
74 | from distutils.core import setup | |
75 | setup(name='foo', | |
76 | version='1.0', | |
77 | py_modules=['foo'], | |
78 | ) | |
79 | </pre></div> | |
80 | ||
81 | <P> | |
82 | Some observations: | |
83 | ||
84 | <UL> | |
85 | <LI>most information that you supply to the Distutils is supplied as | |
86 | keyword arguments to the <tt class="function">setup()</tt> function | |
87 | </LI> | |
88 | <LI>those keyword arguments fall into two categories: package | |
89 | metadata (name, version number) and information about what's in the | |
90 | package (a list of pure Python modules, in this case) | |
91 | </LI> | |
92 | <LI>modules are specified by module name, not filename (the same will | |
93 | hold true for packages and extensions) | |
94 | </LI> | |
95 | <LI>it's recommended that you supply a little more metadata, in | |
96 | particular your name, email address and a URL for the project | |
97 | (see section <A href="setup-script.html#setup-script">2</A> for an example) | |
98 | </LI> | |
99 | </UL> | |
100 | ||
101 | <P> | |
102 | To create a source distribution for this module, you would create a | |
103 | setup script, <span class="file">setup.py</span>, containing the above code, and run: | |
104 | ||
105 | <P> | |
106 | <div class="verbatim"><pre> | |
107 | python setup.py sdist | |
108 | </pre></div> | |
109 | ||
110 | <P> | |
111 | which will create an archive file (e.g., tarball on <span class="Unix">Unix</span>, ZIP file on | |
112 | Windows) containing your setup script <span class="file">setup.py</span>, and your module | |
113 | <span class="file">foo.py</span>. The archive file will be named <span class="file">foo-1.0.tar.gz</span> (or | |
114 | <span class="file">.zip</span>), and will unpack into a directory <span class="file">foo-1.0</span>. | |
115 | ||
116 | <P> | |
117 | If an end-user wishes to install your <tt class="module">foo</tt> module, all she has | |
118 | to do is download <span class="file">foo-1.0.tar.gz</span> (or <span class="file">.zip</span>), unpack it, | |
119 | and--from the <span class="file">foo-1.0</span> directory--run | |
120 | ||
121 | <P> | |
122 | <div class="verbatim"><pre> | |
123 | python setup.py install | |
124 | </pre></div> | |
125 | ||
126 | <P> | |
127 | which will ultimately copy <span class="file">foo.py</span> to the appropriate directory | |
128 | for third-party modules in their Python installation. | |
129 | ||
130 | <P> | |
131 | This simple example demonstrates some fundamental concepts of the | |
132 | Distutils. First, both developers and installers have the same basic | |
133 | user interface, i.e. the setup script. The difference is which | |
134 | Distutils <em>commands</em> they use: the <code class="du-command">sdist</code> command is | |
135 | almost exclusively for module developers, while <code class="du-command">install</code> is | |
136 | more often for installers (although most developers will want to install | |
137 | their own code occasionally). | |
138 | ||
139 | <P> | |
140 | If you want to make things really easy for your users, you can create | |
141 | one or more built distributions for them. For instance, if you are | |
142 | running on a Windows machine, and want to make things easy for other | |
143 | Windows users, you can create an executable installer (the most | |
144 | appropriate type of built distribution for this platform) with the | |
145 | <code class="du-command">bdist_wininst</code> command. For example: | |
146 | ||
147 | <P> | |
148 | <div class="verbatim"><pre> | |
149 | python setup.py bdist_wininst | |
150 | </pre></div> | |
151 | ||
152 | <P> | |
153 | will create an executable installer, <span class="file">foo-1.0.win32.exe</span>, in the | |
154 | current directory. | |
155 | ||
156 | <P> | |
157 | Other useful built distribution formats are RPM, implemented by the | |
158 | <code class="du-command">bdist_rpm</code> command, Solaris <b class="program">pkgtool</b> | |
159 | (<code class="du-command">bdist_pkgtool</code>), and HP-UX <b class="program">swinstall</b> | |
160 | (<code class="du-command">bdist_sdux</code>). For example, the following command will | |
161 | create an RPM file called <span class="file">foo-1.0.noarch.rpm</span>: | |
162 | ||
163 | <P> | |
164 | <div class="verbatim"><pre> | |
165 | python setup.py bdist_rpm | |
166 | </pre></div> | |
167 | ||
168 | <P> | |
169 | (The <code class="du-command">bdist_rpm</code> command uses the <code class="du-command">rpm</code> executable, | |
170 | therefore this has to be run on an RPM-based system such as Red Hat | |
171 | Linux, SuSE Linux, or Mandrake Linux.) | |
172 | ||
173 | <P> | |
174 | You can find out what distribution formats are available at any time by | |
175 | running | |
176 | ||
177 | <P> | |
178 | <div class="verbatim"><pre> | |
179 | python setup.py bdist --help-formats | |
180 | </pre></div> | |
181 | ||
182 | <P> | |
183 | ||
184 | <DIV CLASS="navigation"> | |
185 | <div class='online-navigation'> | |
186 | <p></p><hr /> | |
187 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
188 | <tr> | |
189 | <td class='online-navigation'><a rel="prev" title="1.1 Concepts & Terminology" | |
190 | href="concepts.html"><img src='../icons/previous.png' | |
191 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
192 | <td class='online-navigation'><a rel="parent" title="1. An Introduction to" | |
193 | href="intro.html"><img src='../icons/up.png' | |
194 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
195 | <td class='online-navigation'><a rel="next" title="1.3 General Python terminology" | |
196 | href="python-terms.html"><img src='../icons/next.png' | |
197 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
198 | <td align="center" width="100%">Distributing Python Modules</td> | |
199 | <td class='online-navigation'><img src='../icons/blank.png' | |
200 | border='0' height='32' alt='' width='32' /></td> | |
201 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
202 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
203 | <td class='online-navigation'><a rel="index" title="Index" | |
204 | href="genindex.html"><img src='../icons/index.png' | |
205 | border='0' height='32' alt='Index' width='32' /></A></td> | |
206 | </tr></table> | |
207 | <div class='online-navigation'> | |
208 | <b class="navlabel">Previous:</b> | |
209 | <a class="sectref" rel="prev" href="concepts.html">1.1 Concepts & Terminology</A> | |
210 | <b class="navlabel">Up:</b> | |
211 | <a class="sectref" rel="parent" href="intro.html">1. An Introduction to</A> | |
212 | <b class="navlabel">Next:</b> | |
213 | <a class="sectref" rel="next" href="python-terms.html">1.3 General Python terminology</A> | |
214 | </div> | |
215 | </div> | |
216 | <hr /> | |
217 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
218 | </DIV> | |
219 | <!--End of Navigation Panel--> | |
220 | <ADDRESS> | |
221 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
222 | </ADDRESS> | |
223 | </BODY> | |
224 | </HTML> |