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="inst.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="inst.html" title='Installing Python Modules' /> | |
8 | <link rel='last' href='about.html' title='About this document...' /> | |
9 | <link rel='help' href='about.html' title='About this document...' /> | |
10 | <link rel="next" href="alt-install-windows.html" /> | |
11 | <link rel="prev" href="trivial-install.html" /> | |
12 | <link rel="parent" href="inst.html" /> | |
13 | <link rel="next" href="alt-install-windows.html" /> | |
14 | <meta name='aesop' content='information' /> | |
15 | <title>2 Standard Build and Install</title> | |
16 | </head> | |
17 | <body> | |
18 | <DIV CLASS="navigation"> | |
19 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
20 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
21 | <tr> | |
22 | <td class='online-navigation'><a rel="prev" title="1 Introduction" | |
23 | href="trivial-install.html"><img src='../icons/previous.png' | |
24 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
25 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" | |
26 | href="inst.html"><img src='../icons/up.png' | |
27 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
28 | <td class='online-navigation'><a rel="next" title="3 Alternate Installation" | |
29 | href="alt-install-windows.html"><img src='../icons/next.png' | |
30 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
31 | <td align="center" width="100%">Installing Python Modules</td> | |
32 | <td class='online-navigation'><img src='../icons/blank.png' | |
33 | border='0' height='32' alt='' width='32' /></td> | |
34 | <td class='online-navigation'><img src='../icons/blank.png' | |
35 | border='0' height='32' alt='' width='32' /></td> | |
36 | <td class='online-navigation'><img src='../icons/blank.png' | |
37 | border='0' height='32' alt='' width='32' /></td> | |
38 | </tr></table> | |
39 | <div class='online-navigation'> | |
40 | <b class="navlabel">Previous:</b> | |
41 | <a class="sectref" rel="prev" href="trivial-install.html">1 Introduction</A> | |
42 | <b class="navlabel">Up:</b> | |
43 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> | |
44 | <b class="navlabel">Next:</b> | |
45 | <a class="sectref" rel="next" href="alt-install-windows.html">3 Alternate Installation</A> | |
46 | </div> | |
47 | <hr /></div> | |
48 | </DIV> | |
49 | <!--End of Navigation Panel--> | |
50 | <div class='online-navigation'> | |
51 | <!--Table of Child-Links--> | |
52 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
53 | ||
54 | <UL CLASS="ChildLinks"> | |
55 | <LI><A href="standard-install.html#SECTION000210000000000000000">2.1 Platform variations</a> | |
56 | <LI><A href="standard-install.html#SECTION000220000000000000000">2.2 Splitting the job up</a> | |
57 | <LI><A href="standard-install.html#SECTION000230000000000000000">2.3 How building works</a> | |
58 | <LI><A href="standard-install.html#SECTION000240000000000000000">2.4 How installation works</a> | |
59 | </ul> | |
60 | <!--End of Table of Child-Links--> | |
61 | </div> | |
62 | <HR> | |
63 | ||
64 | <H1><A NAME="SECTION000200000000000000000"></A> | |
65 | <A NAME="standard-install"></A> | |
66 | <BR> | |
67 | 2 Standard Build and Install | |
68 | </H1> | |
69 | ||
70 | <P> | |
71 | As described in section <A href="trivial-install.html#new-standard">1.2</A>, building and installing | |
72 | a module distribution using the Distutils is usually one simple command: | |
73 | ||
74 | <P> | |
75 | <div class="verbatim"><pre> | |
76 | python setup.py install | |
77 | </pre></div> | |
78 | ||
79 | <P> | |
80 | On <span class="Unix">Unix</span>, you'd run this command from a shell prompt; on Windows, you | |
81 | have to open a command prompt window (``DOS box'') and do it there; on | |
82 | Mac OS X, you open a <code class="du-command">Terminal</code> window to get a shell prompt. | |
83 | ||
84 | <P> | |
85 | ||
86 | <H2><A NAME="SECTION000210000000000000000"></A> | |
87 | <A NAME="platform-variations"></A> | |
88 | <BR> | |
89 | 2.1 Platform variations | |
90 | </H2> | |
91 | ||
92 | <P> | |
93 | You should always run the setup command from the distribution root | |
94 | directory, i.e. the top-level subdirectory that the module source | |
95 | distribution unpacks into. For example, if you've just downloaded a | |
96 | module source distribution <span class="file">foo-1.0.tar.gz</span> onto a | |
97 | <span class="Unix">Unix</span> system, the normal thing to do is: | |
98 | ||
99 | <P> | |
100 | <div class="verbatim"><pre> | |
101 | gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 | |
102 | cd foo-1.0 | |
103 | python setup.py install | |
104 | </pre></div> | |
105 | ||
106 | <P> | |
107 | On Windows, you'd probably download <span class="file">foo-1.0.zip</span>. If you | |
108 | downloaded the archive file to <span class="file">C:\Temp</span>, then it | |
109 | would unpack into <span class="file">C:\Temp\foo-1.0</span>; | |
110 | you can use either a archive manipulator with a graphical user interface | |
111 | (such as WinZip) or a command-line tool (such as <b class="program">unzip</b> or | |
112 | <b class="program">pkunzip</b>) to unpack the archive. Then, open a command prompt | |
113 | window (``DOS box''), and run: | |
114 | ||
115 | <P> | |
116 | <div class="verbatim"><pre> | |
117 | cd c:\Temp\foo-1.0 | |
118 | python setup.py install | |
119 | </pre></div> | |
120 | ||
121 | <P> | |
122 | ||
123 | <H2><A NAME="SECTION000220000000000000000"></A> | |
124 | <A NAME="splitting-up"></A> | |
125 | <BR> | |
126 | 2.2 Splitting the job up | |
127 | </H2> | |
128 | ||
129 | <P> | |
130 | Running <code>setup.py install</code> builds and installs all modules in one | |
131 | run. If you prefer to work incrementally--especially useful if you | |
132 | want to customize the build process, or if things are going wrong--you | |
133 | can use the setup script to do one thing at a time. This is | |
134 | particularly helpful when the build and install will be done by | |
135 | different users--for example, you might want to build a module distribution | |
136 | and hand it off to a system administrator for installation (or do it | |
137 | yourself, with super-user privileges). | |
138 | ||
139 | <P> | |
140 | For example, you can build everything in one step, and then install | |
141 | everything in a second step, by invoking the setup script twice: | |
142 | ||
143 | <P> | |
144 | <div class="verbatim"><pre> | |
145 | python setup.py build | |
146 | python setup.py install | |
147 | </pre></div> | |
148 | ||
149 | <P> | |
150 | If you do this, you will notice that running the <code class="du-command">install</code> | |
151 | command first runs the <code class="du-command">build</code> command, which--in this | |
152 | case--quickly notices that it has nothing to do, since everything in | |
153 | the <span class="file">build</span> directory is up-to-date. | |
154 | ||
155 | <P> | |
156 | You may not need this ability to break things down often if all you do | |
157 | is install modules downloaded off the 'net, but it's very handy for more | |
158 | advanced tasks. If you get into distributing your own Python modules | |
159 | and extensions, you'll run lots of individual Distutils commands on | |
160 | their own. | |
161 | ||
162 | <P> | |
163 | ||
164 | <H2><A NAME="SECTION000230000000000000000"></A> | |
165 | <A NAME="how-build-works"></A> | |
166 | <BR> | |
167 | 2.3 How building works | |
168 | </H2> | |
169 | ||
170 | <P> | |
171 | As implied above, the <code class="du-command">build</code> command is responsible for putting | |
172 | the files to install into a <em>build directory</em>. By default, this is | |
173 | <span class="file">build</span> under the distribution root; if you're excessively | |
174 | concerned with speed, or want to keep the source tree pristine, you can | |
175 | change the build directory with the <b class="programopt">--build-base</b> option. | |
176 | For example: | |
177 | ||
178 | <P> | |
179 | <div class="verbatim"><pre> | |
180 | python setup.py build --build-base=/tmp/pybuild/foo-1.0 | |
181 | </pre></div> | |
182 | ||
183 | <P> | |
184 | (Or you could do this permanently with a directive in your system or | |
185 | personal Distutils configuration file; see | |
186 | section <A href="config-syntax.html#config-files">5</A>.) Normally, this isn't necessary. | |
187 | ||
188 | <P> | |
189 | The default layout for the build tree is as follows: | |
190 | ||
191 | <P> | |
192 | <div class="verbatim"><pre> | |
193 | --- build/ --- lib/ | |
194 | or | |
195 | --- build/ --- lib.<plat>/ | |
196 | temp.<plat>/ | |
197 | </pre></div> | |
198 | ||
199 | <P> | |
200 | where <code><plat></code> expands to a brief description of the current | |
201 | OS/hardware platform and Python version. The first form, with just a | |
202 | <span class="file">lib</span> directory, is used for ``pure module distributions''--that | |
203 | is, module distributions that include only pure Python modules. If a | |
204 | module distribution contains any extensions (modules written in C/C++), | |
205 | then the second form, with two <code><plat></code> directories, is used. In | |
206 | that case, the <span class="file">temp.<span class="du-filevar">plat</span></span> directory holds temporary | |
207 | files generated by the compile/link process that don't actually get | |
208 | installed. In either case, the <span class="file">lib</span> (or | |
209 | <span class="file">lib.<span class="du-filevar">plat</span></span>) directory contains all Python modules (pure | |
210 | Python and extensions) that will be installed. | |
211 | ||
212 | <P> | |
213 | In the future, more directories will be added to handle Python scripts, | |
214 | documentation, binary executables, and whatever else is needed to handle | |
215 | the job of installing Python modules and applications. | |
216 | ||
217 | <P> | |
218 | ||
219 | <H2><A NAME="SECTION000240000000000000000"></A> | |
220 | <A NAME="how-install-works"></A> | |
221 | <BR> | |
222 | 2.4 How installation works | |
223 | </H2> | |
224 | ||
225 | <P> | |
226 | After the <code class="du-command">build</code> command runs (whether you run it explicitly, | |
227 | or the <code class="du-command">install</code> command does it for you), the work of the | |
228 | <code class="du-command">install</code> command is relatively simple: all it has to do is copy | |
229 | everything under <span class="file">build/lib</span> (or <span class="file">build/lib.<span class="du-filevar">plat</span></span>) | |
230 | to your chosen installation directory. | |
231 | ||
232 | <P> | |
233 | If you don't choose an installation directory--i.e., if you just run | |
234 | <code>setup.py install</code>--then the <code class="du-command">install</code> command installs to | |
235 | the standard location for third-party Python modules. This location | |
236 | varies by platform and by how you built/installed Python itself. On | |
237 | <span class="Unix">Unix</span> (and Mac OS X, which is also Unix-based), | |
238 | it also depends on whether the module distribution | |
239 | being installed is pure Python or contains extensions (``non-pure''): | |
240 | <div class="center"><table class="realtable"> | |
241 | <thead> | |
242 | <tr> | |
243 | <th class="left" >Platform</th> | |
244 | <th class="left" >Standard installation location</th> | |
245 | <th class="left" >Default value</th> | |
246 | <th class="center">Notes</th> | |
247 | </tr> | |
248 | </thead> | |
249 | <tbody> | |
250 | <tr><td class="left" valign="baseline"><span class="Unix">Unix</span> (pure)</td> | |
251 | <td class="left" ><span class="file"><span class="du-filevar">prefix</span>/lib/python2.4/site-packages</span></td> | |
252 | <td class="left" ><span class="file">/usr/local/lib/python2.4/site-packages</span></td> | |
253 | <td class="center">(1)</td></tr> | |
254 | <tr><td class="left" valign="baseline"><span class="Unix">Unix</span> (non-pure)</td> | |
255 | <td class="left" ><span class="file"><span class="du-filevar">exec-prefix</span>/lib/python2.4/site-packages</span></td> | |
256 | <td class="left" ><span class="file">/usr/local/lib/python2.4/site-packages</span></td> | |
257 | <td class="center">(1)</td></tr> | |
258 | <tr><td class="left" valign="baseline">Windows</td> | |
259 | <td class="left" ><span class="file"><span class="du-filevar">prefix</span></span></td> | |
260 | <td class="left" ><span class="file">C:\Python</span></td> | |
261 | <td class="center">(2)</td></tr></tbody> | |
262 | </table></div> | |
263 | ||
264 | <P> | |
265 | Notes: | |
266 | <DL> | |
267 | <DT><STRONG>(1)</STRONG></DT> | |
268 | <DD>Most Linux distributions include Python as a standard part of | |
269 | the system, so <span class="du-filevar">prefix</span> and <span class="du-filevar">exec-prefix</span> are usually | |
270 | both <span class="file">/usr</span> on Linux. If you build Python yourself on Linux (or | |
271 | any <span class="Unix">Unix</span>-like system), the default <span class="du-filevar">prefix</span> and | |
272 | <span class="du-filevar">exec-prefix</span> are <span class="file">/usr/local</span>. | |
273 | </DD> | |
274 | <DT><STRONG>(2)</STRONG></DT> | |
275 | <DD>The default installation directory on Windows was | |
276 | <span class="file">C:\Program Files\Python</span> under | |
277 | Python 1.6a1, 1.5.2, and earlier. | |
278 | </DD> | |
279 | </DL> | |
280 | ||
281 | <P> | |
282 | <span class="du-filevar">prefix</span> and <span class="du-filevar">exec-prefix</span> stand for the directories | |
283 | that Python is installed to, and where it finds its libraries at | |
284 | run-time. They are always the same under Windows, and very | |
285 | often the same under <span class="Unix">Unix</span>and Mac OS X. You can find out what your Python | |
286 | installation uses for <span class="du-filevar">prefix</span> and <span class="du-filevar">exec-prefix</span> by | |
287 | running Python in interactive mode and typing a few simple commands. | |
288 | Under <span class="Unix">Unix</span>, just type <code>python</code> at the shell prompt. Under | |
289 | Windows, choose <span class="guilabel">Start </span> > <span class="guilabel">Programs </span> > <span class="guilabel">Python | |
290 | 2.4</span> > <span class="guilabel">Python (command line)</span>. | |
291 | Once the interpreter is started, you type Python code at the | |
292 | prompt. For example, on my Linux system, I type the three Python | |
293 | statements shown below, and get the output as shown, to find out my | |
294 | <span class="du-filevar">prefix</span> and <span class="du-filevar">exec-prefix</span>: | |
295 | ||
296 | <P> | |
297 | <div class="verbatim"><pre> | |
298 | Python 2.4 (#26, Aug 7 2004, 17:19:02) | |
299 | Type "help", "copyright", "credits" or "license" for more information. | |
300 | >>> import sys | |
301 | >>> sys.prefix | |
302 | '/usr' | |
303 | >>> sys.exec_prefix | |
304 | '/usr' | |
305 | </pre></div> | |
306 | ||
307 | <P> | |
308 | If you don't want to install modules to the standard location, or if you | |
309 | don't have permission to write there, then you need to read about | |
310 | alternate installations in section <A href="alt-install-windows.html#alt-install">3</A>. If you want to | |
311 | customize your installation directories more heavily, see | |
312 | section <A href="search-path.html#custom-install">4</A> on custom installations. | |
313 | ||
314 | <P> | |
315 | ||
316 | <P> | |
317 | ||
318 | <DIV CLASS="navigation"> | |
319 | <div class='online-navigation'> | |
320 | <p></p><hr /> | |
321 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
322 | <tr> | |
323 | <td class='online-navigation'><a rel="prev" title="1 Introduction" | |
324 | href="trivial-install.html"><img src='../icons/previous.png' | |
325 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
326 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" | |
327 | href="inst.html"><img src='../icons/up.png' | |
328 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
329 | <td class='online-navigation'><a rel="next" title="3 Alternate Installation" | |
330 | href="alt-install-windows.html"><img src='../icons/next.png' | |
331 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
332 | <td align="center" width="100%">Installing Python Modules</td> | |
333 | <td class='online-navigation'><img src='../icons/blank.png' | |
334 | border='0' height='32' alt='' width='32' /></td> | |
335 | <td class='online-navigation'><img src='../icons/blank.png' | |
336 | border='0' height='32' alt='' width='32' /></td> | |
337 | <td class='online-navigation'><img src='../icons/blank.png' | |
338 | border='0' height='32' alt='' width='32' /></td> | |
339 | </tr></table> | |
340 | <div class='online-navigation'> | |
341 | <b class="navlabel">Previous:</b> | |
342 | <a class="sectref" rel="prev" href="trivial-install.html">1 Introduction</A> | |
343 | <b class="navlabel">Up:</b> | |
344 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> | |
345 | <b class="navlabel">Next:</b> | |
346 | <a class="sectref" rel="next" href="alt-install-windows.html">3 Alternate Installation</A> | |
347 | </div> | |
348 | </div> | |
349 | <hr /> | |
350 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
351 | </DIV> | |
352 | <!--End of Navigation Panel--> | |
353 | <ADDRESS> | |
354 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
355 | </ADDRESS> | |
356 | </BODY> | |
357 | </HTML> |