Google Git
Sign in
chromium / external / github.com / python / cpython / refs/tags/2.2 / . / README
blob: 3f76ea536d00bcdc5fb5c65cfe7fce03746381e2 [file] [log] [blame]
Barry Warsawcf9727f2003-05-22 15:15:05[diff] [blame]1This is Python version 2.2.3
Guido van Rossum241aa8b2002-10-14 12:35:53[diff] [blame]2============================
Guido van Rossum91447632000-04-11 17:11:09[diff] [blame]3
Barry Warsawcf9727f2003-05-22 15:15:05[diff] [blame]4Copyright (c) 2001, 2002, 2003 Python Software Foundation.
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]5All rights reserved.
6
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]7Copyright (c) 2000 BeOpen.com.
8All rights reserved.
9
Guido van Rossum23f7aed2001-04-12 20:53:31[diff] [blame]10Copyright (c) 1995-2001 Corporation for National Research Initiatives.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]11All rights reserved.
12
Guido van Rossum6ebd2992000-09-03 04:47:47[diff] [blame]13Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]14All rights reserved.
15
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]16
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]17License information
18-------------------
19
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]20See the file "LICENSE" for information on the history of this
21software, terms & conditions for usage, and a DISCLAIMER OF ALL
22WARRANTIES.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]23
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]24This Python distribution contains no GNU General Public Licensed
25(GPLed) code so it may be used in proprietary projects just like prior
26Python distributions. There are interfaces to some GNU code but these
27are entirely optional.
28
29All trademarks referenced herein are property of their respective
30holders.
Guido van Rossum79808261997-12-11 18:01:47[diff] [blame]31
32
Guido van Rossum8d7d4ed1996-07-30 21:41:07[diff] [blame]33What's new in this release?
34---------------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04[diff] [blame]35
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]36See the file "Misc/NEWS".
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]37
38If you don't read instructions
39------------------------------
40
41Congratulations on getting this far. :-)
42
43To start building right away (on UNIX): type "./configure" in the
Michael W. Hudsonc104d892002-03-17 19:39:24[diff] [blame]44current directory and when it finishes, type "make". This creates an
45executable "./python"; to install in /usr/local, first do "su root"
46and then "make install".
47
48The section `Build Instructions' below is still recommended reading,
49especially the part on customizing Modules/Setup.
Guido van Rossum3ff96dd1996-07-30 18:05:04[diff] [blame]50
51
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]52What is Python anyway?
53----------------------
54
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]55Python is an interpreted object-oriented programming language suitable
56(amongst other uses) for distributed application development,
57scripting, numeric computing and system testing. Python is often
58compared to Tcl, Perl, Java, JavaScript, Visual Basic or Scheme. To
59find out more about what Python can do for you, point your browser to
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]60http://www.python.org/.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]61
62
Guido van Rossumf501b4e1996-10-25 14:32:48[diff] [blame]63How do I learn Python?
64----------------------
65
Fred Drake0e6444c1999-05-17 19:35:01[diff] [blame]66The official tutorial is still a good place to start; see
Guido van Rossumd0a42e22000-03-31 20:16:45[diff] [blame]67http://www.python.org/doc/ for online and downloadable versions, as
68well as a list of other introductions, and reference documentation.
Guido van Rossumf501b4e1996-10-25 14:32:48[diff] [blame]69
Guido van Rossumd0a42e22000-03-31 20:16:45[diff] [blame]70There's a quickly growing set of books on Python. See
71http://www.python.org/psa/bookstore/ for a list.
Guido van Rossum8d90f9d1997-05-22 20:13:25[diff] [blame]72
Guido van Rossumf501b4e1996-10-25 14:32:48[diff] [blame]73
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]74Documentation
75-------------
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]76
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]77All documentation is provided online in a variety of formats. In
78order of importance for new users: Tutorial, Library Reference,
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]79Language Reference, Extending & Embedding, and the Python/C API. The
80Library Reference is especially of immense value since much of
81Python's power is described there, including the built-in data types
82and functions!
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]83
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]84All documentation is also available online at the Python web site
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]85(http://www.python.org/doc/, see below). It is available online for
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]86occasional reference, or can be downloaded in many formats for faster
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]87access. The documentation is available in HTML, PostScript, PDF, and
88LaTeX formats; the LaTeX version is primarily for documentation
89authors, translators, and people with special formatting requirements.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]90
Barry Warsaw06557452001-12-14 20:47:12[diff] [blame]91The best documentation for the new (in Python 2.2) type/class unification
92features is Guido's tutorial introduction, at
93
94 http://www.python.org/2.2/descrintro.html
95
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]96
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]97Web sites
98---------
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]99
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]100New Python releases and related technologies are published at
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]101http://www.python.org/. Come visit us!
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]102
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]103There's also a Python community web site at http://starship.python.net/.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]104
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]105
106Newsgroups and Mailing Lists
107----------------------------
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]108
109Read comp.lang.python, a high-volume discussion newsgroup about
110Python, or comp.lang.python.announce, a low-volume moderated newsgroup
111for Python-related announcements. These are also accessible as
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]112mailing lists: see http://www.python.org/psa/MailingLists.html for an
113overview of the many Python-related mailing lists.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]114
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]115Archives are accessible via Deja.com Usenet News: see
116http://www.deja.com/usenet. The mailing lists are also archived, see
117http://www.python.org/psa/MailingLists.html for details.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]118
119
120Bug reports
121-----------
122
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]123To report or search for bugs, please use the Python Bug
124Tracker at http://sourceforge.net/bugs/?group_id=5470.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]125
126
127Patches and contributions
128-------------------------
129
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]130To submit a patch or other contribution, please use the Python Patch
131Manager at http://sourceforge.net/patch/?group_id=5470. Guidelines
132for patch submission may be found at http://www.python.org/patches/.
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]133
134If you have a proposal to change Python, it's best to submit a Python
135Enhancement Proposal (PEP) first. All current PEPs, as well as
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]136guidelines for submitting a new PEP, are list at
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]137http://python.sourceforge.net/peps/.
138
139
140Questions
141---------
142
143For help, if you can't find it in the manuals or on the web site, it's
144best to post to the comp.lang.python or the Python mailing list (see
145above). If you specifically don't want to involve the newsgroup or
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]146mailing list, send questions to help@python.org (a group of volunteers
147who answer questions as they can). The newsgroup is the most
148efficient way to ask public questions.
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]149
Guido van Rossum901454e2000-06-29 22:28:44[diff] [blame]150
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]151Build instructions
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]152==================
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]153
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]154Before you can build Python, you must first configure it.
155Fortunately, the configuration and build process has been automated
156for Unix and Linux installations, so all you usually have to do is
157type a few commands and sit back. There are some platforms where
158things are not quite as smooth; see the platform specific notes below.
159If you want to build for multiple platforms sharing the same source
160tree, see the section on VPATH below.
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]161
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]162Start by running the script "./configure", which determines your
163system configuration and creates the Makefile. (It takes a minute or
164two -- please be patient!) You may want to pass options to the
165configure script -- see the section below on configuration options and
166variables. When it's done, you are ready to run make.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]167
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]168To build Python, you normally type "make" in the toplevel directory.
169If you have changed the configuration, the Makefile may have to be
170rebuilt. In this case you may have to run make again to correctly
171build your desired target. The interpreter executable is built in the
172top level directory.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]173
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]174Once you have built a Python interpreter, see the subsections below on
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]175testing and installation. If you run into trouble, see the next
176section.
177
178Previous versions of Python used a manual configuration process that
179involved editing the file Modules/Setup. While this file still exists
180and manual configuration is still supported, it is rarely needed any
181more: almost all modules are automatically built as appropriate under
182guidance of the setup.py script, which is run by Make after the
183interpreter has been built.
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]184
Guido van Rossum0a516c91994-09-12 10:58:40[diff] [blame]185
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]186Troubleshooting
187---------------
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]188
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]189See also the platform specific notes in the next section.
190
Guido van Rossum49523691997-08-15 18:30:14[diff] [blame]191If you run into other trouble, see section 3 of the FAQ
Guido van Rossum901454e2000-06-29 22:28:44[diff] [blame]192(http://www.python.org/cgi-bin/faqw.py or
Guido van Rossum49523691997-08-15 18:30:14[diff] [blame]193http://www.python.org/doc/FAQ.html) for hints on what can go wrong,
194and how to fix it.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]195
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]196If you rerun the configure script with different options, remove all
197object files by running "make clean" before rebuilding. Believe it or
198not, "make clean" sometimes helps to clean up other inexplicable
199problems as well. Try it before sending in a bug report!
200
Guido van Rossumd0fe8451996-08-26 03:02:37[diff] [blame]201If the configure script fails or doesn't seem to find things that
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]202should be there, inspect the config.log file. When you fix a
203configure problem, be sure to remove config.cache!
204
205If you get a warning for every file about the -Olimit option being no
206longer supported, you can ignore it. There's no foolproof way to know
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]207whether this option is needed; all we can do is test whether it is
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]208accepted without error. On some systems, e.g. older SGI compilers, it
209is essential for performance (specifically when compiling ceval.c,
210which has more basic blocks than the default limit of 1000). If the
211warning bothers you, edit the Makefile to remove "-Olimit 1500" from
212the OPT variable.
Guido van Rossumd0fe8451996-08-26 03:02:37[diff] [blame]213
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]214If you get failures in test_long, or sys.maxint gets set to -1, you
215are probably experiencing compiler bugs, usually related to
Martin v. Löwiscd0cbbe2002-11-15 07:27:03[diff] [blame]216optimization. This is a common problem with some versions of gcc, and
217some vendor-supplied compilers, which can sometimes be worked around
218by turning off optimization. Consider switching to stable versions
219(gcc 2.95.2, or contact your vendor.)
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]220
221From Python 2.0 onward, all Python C code is ANSI C. Compiling using
222old K&R-C-only compilers is no longer possible. ANSI C compilers are
223available for all modern systems, either in the form of updated
Martin v. Löwiscd0cbbe2002-11-15 07:27:03[diff] [blame]224compilers from the vendor, or one of the free compilers (gcc).
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]225
226Platform specific notes
227-----------------------
228
Guido van Rossum0447a321995-10-08 01:22:33[diff] [blame]229(Some of these may no longer apply. If you find you can build Python
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]230on these platforms without the special directions mentioned here,
231submit a documentation bug report to SourceForge (see Bug Reports
232above) so we can remove them!)
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]233
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]23464-bit platforms: The modules audioop, imageop and rgbimg don't work.
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]235 The setup.py script disables them on 64-bit installations.
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]236 Don't try to enable them in the Modules/Setup file. They
237 contain code that is quite wordsize sensitive. (If you have a
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]238 fix, let us know!)
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]239
Guido van Rossum4462e931997-01-22 21:00:32[diff] [blame]240Solaris: When using Sun's C compiler with threads, at least on Solaris
241 2.5.1, you need to add the "-mt" compiler option (the simplest
242 way is probably to specify the compiler with this option as
243 the "CC" environment variable when running the configure
244 script).
245
Guido van Rossum9eda6522002-09-23 14:02:44[diff] [blame]246 When using GCC on Solaris, beware of binutils 2.13 or GCC
247 versions built using it. This mistakenly enables the
248 -zcombreloc option which creates broken shared libraries on
249 Solaris. binutils 2.12 works, and the binutils maintainers
250 are aware of the problem, so binutils 2.13.1 will probably fix
251 this problem.
252
Martin v. Löwiscd0cbbe2002-11-15 07:27:03[diff] [blame]253 When the dynamic loader complains about errors finding shared
254 libraries, such as
255
256 ld.so.1: ./python: fatal: libstdc++.so.5: open failed:
257 No such file or directory
258
259 you need to first make sure that the library is available on
260 your system. Then, you need to instruct the dynamic loader how
261 to find it. You can chose any of the following strategies:
262
263 1. When compiling Python, set LD_RUN_PATH to the directories
264 containing missing libraries.
265 2. When running Python, set LD_LIBRARY_PATH to these directories.
266 3. Use crle(8) to extend the search path of the loader.
267 4. Modify the installed GCC specs file, adding -R options into the
268 *link: section.
269
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]270Linux: A problem with threads and fork() was tracked down to a bug in
271 the pthreads code in glibc version 2.0.5; glibc version 2.0.7
272 solves the problem. This causes the popen2 test to fail;
273 problem and solution reported by Pablo Bleyer.
Guido van Rossum4462e931997-01-22 21:00:32[diff] [blame]274
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]275 Under Linux systems using GNU libc 2 (aka libc6), the crypt
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]276 module now needs the -lcrypt option. The setup.py script
277 takes care of this automatically.
Fred Drake61280911997-12-08 14:10:40[diff] [blame]278
Michael W. Hudsonc104d892002-03-17 19:39:24[diff] [blame]279Red Hat Linux: There's an executable /usr/bin/python which is Python
280 1.5.2 on most Red Hat installations; several key Red Hat tools
281 require this version. Python 2.1.x may be installed as
282 /usr/bin/python2. The Makefile installs Python as
283 /usr/local/bin/python, which may or may not take precedence
284 over /usr/bin/python, depending on how you have set up $PATH.
285
Guido van Rossum59230501999-06-21 20:51:46[diff] [blame]286FreeBSD 3.x and probably platforms with NCurses that use libmytinfo or
287 similar: When using cursesmodule, the linking is not done in
288 the correct order with the defaults. Remove "-ltermcap" from
289 the readline entry in Setup, and use as curses entry: "curses
290 cursesmodule.c -lmytinfo -lncurses -ltermcap" - "mytinfo" (so
291 called on FreeBSD) should be the name of the auxiliary library
292 required on your platform. Normally, it would be linked
293 automatically, but not necessarily in the correct order.
294
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]295BSDI: BSDI versions before 4.1 have known problems with threads,
296 which can cause strange errors in a number of modules (for
297 instance, the 'test_signal' test script will hang forever.)
298 Turning off threads (with --with-threads=no) or upgrading to
299 BSDI 4.1 solves this problem.
300
301DEC Unix: Run configure with --with-dec-threads, or with
302 --with-threads=no if no threads are desired (threads are on by
303 default). When using GCC, it is possible to get an internal
304 compiler error if optimization is used. This was reported for
305 GCC 2.7.2.3 on selectmodule.c. Manually compile the affected
306 file without optimization to solve the problem.
Guido van Rossum8eca2c21996-02-14 18:37:46[diff] [blame]307
Guido van Rossume1cdb161999-04-10 16:04:07[diff] [blame]308DEC Ultrix: compile with GCC to avoid bugs in the native compiler,
309 and pass SHELL=/bin/sh5 to Make when installing.
310
Guido van Rossumd0fe8451996-08-26 03:02:37[diff] [blame]311AIX: A complete overhaul of the shared library support is now in
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]312 place. See Misc/AIX-NOTES for some notes on how it's done.
Guido van Rossum9ac9a261998-02-16 22:19:21[diff] [blame]313 (The optimizer bug reported at this place in previous releases
Thomas Wouters8ee06142001-02-15 11:45:29[diff] [blame]314 has been worked around by a minimal code change.) If you get
Fred Drake8520b362002-05-11 03:37:15[diff] [blame]315 errors about pthread_* functions, during compile or during
Thomas Wouters8ee06142001-02-15 11:45:29[diff] [blame]316 testing, try setting CC to a thread-safe (reentrant) compiler,
317 like "cc_r". For full C++ module support, set CC="xlC_r" (or
318 CC="xlC" without thread support).
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]319
Guido van Rossum59a88f41999-04-12 18:16:09[diff] [blame]320HP-UX: Please read the file Misc/HPUX-NOTES for shared libraries.
321 When using threading, you may have to add -D_REENTRANT to the
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]322 OPT variable in the top-level Makefile; reported by Pat Knight,
Guido van Rossum59a88f41999-04-12 18:16:09[diff] [blame]323 this seems to make a difference (at least for HP-UX 10.20)
Fred Drake622dca02002-11-04 20:50:39[diff] [blame]324 even though pyconfig.h defines it.
Guido van Rossum2094e041998-05-14 15:47:35[diff] [blame]325
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]326Minix: When using ack, use "CC=cc AR=aal RANLIB=: ./configure"!
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]327
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]328SCO: The following apply to SCO 3 only; Python builds out of the box
329 on SCO 5 (or so we've heard).
Guido van Rossuma16e2751998-04-13 20:14:05[diff] [blame]330
331 1) Everything works much better if you add -U__STDC__ to the
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]332 defs. This is because all the SCO header files are broken.
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]333 Anything that isn't mentioned in the C standard is
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]334 conditionally excluded when __STDC__ is defined.
335
336 2) Due to the U.S. export restrictions, SCO broke the crypt
337 stuff out into a separate library, libcrypt_i.a so the LIBS
338 needed be set to:
339
340 LIBS=' -lsocket -lcrypt_i'
341
Martin v. Löwis387c5472001-09-06 08:16:17[diff] [blame]342UnixWare: There are known bugs in the math library of the system, as well as
343 problems in the handling of threads (calling fork in one
344 thread may interrupt system calls in others). Therefore, test_math and
345 tests involving threads will fail until those problems are fixed.
346
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]347SunOS 4.x: When using the SunPro C compiler, you may want to use the
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]348 '-Xa' option instead of '-Xc', to enable some needed non-ANSI
349 Sunisms.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]350
Jack Jansena39ef862001-08-19 21:17:03[diff] [blame]351NeXT: Not supported anymore. Start with the MacOSX/Darwin code if you
352 want to revive it.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]353
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]354QNX: Chris Herborth (chrish@qnx.com) writes:
355 configure works best if you use GNU bash; a port is available on
356 ftp.qnx.com in /usr/free. I used the following process to build,
Guido van Rossumd4493421998-12-22 16:37:01[diff] [blame]357 test and install Python 1.5.x under QNX:
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]358
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]359 1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \
360 ./configure --verbose --without-gcc --with-libm=""
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]361
Fred Drake80078492000-10-26 17:13:19[diff] [blame]362 2) edit Modules/Setup to activate everything that makes sense for
363 your system... tested here at QNX with the following modules:
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]364
Guido van Rossum6fa49e21998-08-11 17:31:39[diff] [blame]365 array, audioop, binascii, cPickle, cStringIO, cmath,
366 crypt, curses, errno, fcntl, gdbm, grp, imageop,
367 _locale, math, md5, new, operator, parser, pcre,
368 posix, pwd, readline, regex, reop, rgbimg, rotor,
369 select, signal, socket, soundex, strop, struct,
Guido van Rossumd4493421998-12-22 16:37:01[diff] [blame]370 syslog, termios, time, timing, zlib, audioop, imageop, rgbimg
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]371
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]372 3) make SHELL=/usr/local/bin/bash
373
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]374 or, if you feel the need for speed:
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]375
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]376 make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]377
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]378 4) make SHELL=/usr/local/bin/bash test
379
Guido van Rossum6fa49e21998-08-11 17:31:39[diff] [blame]380 Using GNU readline 2.2 seems to behave strangely, but I
381 think that's a problem with my readline 2.2 port. :-\
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]382
383 5) make SHELL=/usr/local/bin/bash install
Guido van Rossumb7f454d1997-12-02 19:44:31[diff] [blame]384
Guido van Rossum6fa49e21998-08-11 17:31:39[diff] [blame]385 If you get SIGSEGVs while running Python (I haven't yet, but
386 I've only run small programs and the test cases), you're
387 probably running out of stack; the default 32k could be a
388 little tight. To increase the stack size, edit the Makefile
Neil Schemenauer73f8ab22001-01-26 22:18:55[diff] [blame]389 to read: LDFLAGS = -N 48k
Guido van Rossum40d63581997-08-14 19:45:30[diff] [blame]390
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]391BeOS: Chris Herborth (chrish@qnx.com) writes:
392 See BeOS/README for notes about compiling/installing Python on
Guido van Rossum6fa49e21998-08-11 17:31:39[diff] [blame]393 BeOS R3 or later. Note that only the PowerPC platform is
Guido van Rossumd4493421998-12-22 16:37:01[diff] [blame]394 supported for R3; both PowerPC and x86 are supported for R4.
Guido van Rossumec95c7b1998-08-04 17:59:56[diff] [blame]395
Michael W. Hudson227c7692002-07-31 11:19:49[diff] [blame]396Cray T3E: Mark Hadfield (m.hadfield@niwa.co.nz) writes:
397 Python can be built satisfactorily on a Cray T3E but based on
398 my experience with the NIWA T3E (2002-05-22, version 2.2.1)
399 there are a few bugs and gotchas. For more information see a
400 thread on comp.lang.python in May 2002 entitled "Building
401 Python on Cray T3E".
402
403 1) Use Cray's cc and not gcc. The latter was reported not to
404 work by Konrad Hinsen. It may work now, but it may not.
405
406 2) To set sys.platform to something sensible, pass the
407 following environment variable to the configure script:
408
409 MACHDEP=unicosmk
410
411 2) Run configure with option "--enable-unicode=ucs4".
412
413 3) The Cray T3E does not support dynamic linking, so extension
414 modules have to be built by adding (or uncommenting) lines
415 in Modules/Setup. The minimum set of modules is
416
417 posix, new, _sre, unicodedata
418
419 On NIWA's vanilla T3E system the following have also been
420 included successfully:
421
422 _codecs, _locale, _socket, _symtable, _testcapi, _weakref
423 array, binascii, cmath, cPickle, crypt, cStringIO, dbm
424 errno, fcntl, grp, math, md5, operator, parser, pcre, pwd
425 regex, rotor, select, struct, strop, syslog, termios
426 time, timing, xreadlines
427
428 4) Once the python executable and library have been built, make
429 will execute setup.py, which will attempt to build remaining
430 extensions and link them dynamically. Each of these attempts
431 will fail but should not halt the make process. This is
432 normal.
433
434 5) Running "make test" uses a lot of resources and causes
435 problems on our system. You might want to try running tests
436 singly or in small groups.
Guido van Rossum1bf0bf41997-08-20 23:50:51[diff] [blame]437
Guido van Rossum0078aaf1997-08-21 03:05:11[diff] [blame]438SGI: SGI's standard "make" utility (/bin/make or /usr/bin/make)
439 does not check whether a command actually changed the file it
440 is supposed to build. This means that whenever you say "make"
441 it will redo the link step. The remedy is to use SGI's much
Guido van Rossum7be8ca02001-04-14 13:09:53[diff] [blame]442 smarter "smake" utility (/usr/sbin/smake), or GNU make. If
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]443 you set the first line of the Makefile to #!/usr/sbin/smake
444 smake will be invoked by make (likewise for GNU make).
Guido van Rossum0078aaf1997-08-21 03:05:11[diff] [blame]445
Guido van Rossum7be8ca02001-04-14 13:09:53[diff] [blame]446 WARNING: There are bugs in the optimizer of some versions of
447 SGI's compilers that can cause bus errors or other strange
448 behavior, especially on numerical operations. To avoid this,
449 try building with "make OPT=".
Fred Drake0b5fb2b2000-09-29 17:45:05[diff] [blame]450
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]451OS/2: If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
452 compiler installed, just change into the pc\os2vacpp directory
453 and type NMAKE. Threading and sockets are supported by default
454 in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
455
Fred Drake36ed5602000-10-06 01:58:48[diff] [blame]456Monterey (64-bit AIX): The current Monterey C compiler (Visual Age)
457 uses the OBJECT_MODE={32|64} environment variable to set the
458 compilation mode to either 32-bit or 64-bit (32-bit mode is
459 the default). Presumably you want 64-bit compilation mode for
460 this 64-bit OS. As a result you must first set OBJECT_MODE=64
461 in your environment before configuring (./configure) or
462 building (make) Python on Monterey.
463
464Reliant UNIX: The thread support does not compile on Reliant UNIX, and
465 there is a (minor) problem in the configure script for that
466 platform as well. This should be resolved in time for a
467 future release.
Trent Mick635f6fb2000-08-23 21:33:05[diff] [blame]468
Barry Warsawb606e3d2002-10-14 18:03:04[diff] [blame]469MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
Barry Warsaw9edaba62002-10-14 18:13:24[diff] [blame]470 test_re and test_sre due to the small default stack size. If
471 you set the stack size to 2048 before doing a "make test" the
472 failure can be avoided. If you're using the tcsh (the default
Jack Jansen8b4226b2003-05-20 21:49:31[diff] [blame]473 on OSX), or csh shells use "limit stacksize 2048"; for the
474 bash or zsh shells, use "ulimit -s 2048".
Barry Warsaw06557452001-12-14 20:47:12[diff] [blame]475
Jack Jansen6a77cf12001-12-06 21:49:02[diff] [blame]476 On naked Darwin you may want to add the configure option
Jack Jansen4c398fd2001-10-08 13:21:15[diff] [blame]477 "--disable-toolbox-glue" to disable the glue code for the Carbon
Jack Jansen6a77cf12001-12-06 21:49:02[diff] [blame]478 interface modules. The modules themselves are currently only built
479 if you add the --enable-framework option, see below.
Barry Warsaw06557452001-12-14 20:47:12[diff] [blame]480
481 On a clean OSX /usr/local does not exist. Do a
482 "sudo mkdir -m 775 /usr/local"
Jack Jansen6a77cf12001-12-06 21:49:02[diff] [blame]483 before you do a make install. Alternatively, do "sudo make install"
Jack Jansenf8197d42001-11-12 14:11:13[diff] [blame]484 which installs everything as superuser.
Barry Warsaw06557452001-12-14 20:47:12[diff] [blame]485
486 You may want to try the configure option "--enable-framework"
487 which installs Python as a framework. The location can be set
488 as argument to the --enable-framework option (default
489 /Library/Frameworks). You may also want to check out ./Mac/OSX
490 for building a Python.app. You may also want to manually
491 install a symlink in /usr/local/bin/python to the executable
492 deep down in the framework.
Fred Drakedabed752001-02-01 19:41:13[diff] [blame]493
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]494Cygwin: With recent (relative to the time of writing, 2001-12-19)
495 Cygwin installations, there are problems with the interaction
496 of dynamic linking and fork(). This manifests itself in build
497 failures during the execution of setup.py.
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]498
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]499 There are two workarounds that both enable Python (albeit
500 without threading support) to build and pass all tests on
501 NT/2000 (and most likely XP as well, though reports of testing
502 on XP would be appreciated).
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]503
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]504 The workarounds:
505
506 (a) the band-aid fix is to link the _socket module statically
507 rather than dynamically (which is the default).
508
509 To do this, run "./configure --with-threads=no" including any
510 other options you need (--prefix, etc.). Then in Modules/Setup
511 uncomment the lines:
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]512
Michael W. Hudsonbe5ce182001-12-12 11:46:52[diff] [blame]513 #SSL=/usr/local/ssl
514 #_socket socketmodule.c \
515 # -DUSE_SSL -I$(SSL)/include -I$(SSL)/include/openssl \
516 # -L$(SSL)/lib -lssl -lcrypto
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]517
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]518 and remove "local/" from the SSL variable. Finally, just run
519 "make"!
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]520
Michael W. Hudsonb6554642001-12-19 22:09:09[diff] [blame]521 (b) The "proper" fix is to rebase the Cygwin DLLs to prevent
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]522 base address conflicts. Details on how to do this can be
523 found in the following mail:
524
525 http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html
526
527 It is hoped that a version of this solution will be
Michael W. Hudsonb6554642001-12-19 22:09:09[diff] [blame]528 incorporated into the Cygwin distribution fairly soon.
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]529
530 Two additional problems:
531
532 (1) Threading support should still be disabled due to a known
533 bug in Cygwin pthreads that causes test_threadedtempfile to
534 hang.
535
Neal Norwitz4ebde092001-12-19 20:44:13[diff] [blame]536 (2) The _curses module does not build. This is a known
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]537 Cygwin ncurses problem that should be resolved the next time
538 that this package is released.
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]539
Michael W. Hudsonbe5ce182001-12-12 11:46:52[diff] [blame]540 On older versions of Cygwin, test_poll may hang and test_strftime
541 may fail.
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]542
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]543 The situation on 9X/Me is not accurately known at present.
544 Some time ago, there were reports that the following
545 regression tests failed:
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]546
547 test_pwd
548 test_select (hang)
549 test_socket
550
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]551 Due to the test_select hang on 9X/Me, one should run the
552 regression test using the following:
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]553
Michael W. Hudsonbe5ce182001-12-12 11:46:52[diff] [blame]554 make TESTOPTS='-l -x test_select' test
Tim Peters42fc7cc2001-04-04 18:35:19[diff] [blame]555
Michael W. Hudson1c4523f2001-12-19 19:49:58[diff] [blame]556 News regarding these platforms with more recent Cygwin
557 versions would be appreciated!
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]558
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]559Configuring threads
560-------------------
561
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]562As of Python 2.0, threads are enabled by default. If you wish to
563compile without threads, or if your thread support is broken, pass the
564--with-threads=no switch to configure. Unfortunately, on some
565platforms, additional compiler and/or linker options are required for
566threads to work properly. Below is a table of those options,
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]567collected by Bill Janssen. We would love to automate this process
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]568more, but the information below is not enough to write a patch for the
569configure.in file, so manual intervention is required. If you patch
570the configure.in file and are confident that the patch works, please
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]571send in the patch. (Don't bother patching the configure script itself
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]572-- it is regenerated each the configure.in file changes.)
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]573
574Compiler switches for threads
575.............................
576
Martin v. Löwis1c24f9c2001-03-06 12:07:27[diff] [blame]577The definition of _REENTRANT should be configured automatically, if
578that does not work on your system, or if _REENTRANT is defined
579incorrectly, please report that as a bug.
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]580
Martin v. Löwis1c24f9c2001-03-06 12:07:27[diff] [blame]581 OS/Compiler/threads Switches for use with threads
582 (POSIX is draft 10, DCE is draft 4) compile & link
583
584 SunOS 5.{1-5}/{gcc,SunPro cc}/solaris -mt
585 SunOS 5.5/{gcc,SunPro cc}/POSIX (nothing)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]586 DEC OSF/1 3.x/cc/DCE -threads
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]587 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]588 Digital UNIX 4.x/cc/DCE -threads
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]589 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]590 Digital UNIX 4.x/cc/POSIX -pthread
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]591 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]592 AIX 4.1.4/cc_r/d7 (nothing)
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]593 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]594 AIX 4.1.4/cc_r4/DCE (nothing)
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]595 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]596 IRIX 6.2/cc/POSIX (nothing)
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]597 (robertl@cwi.nl)
598
599
600Linker (ld) libraries and flags for threads
601...........................................
602
603 OS/threads Libraries/switches for use with threads
604
605 SunOS 5.{1-5}/solaris -lthread
606 SunOS 5.5/POSIX -lpthread
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]607 DEC OSF/1 3.x/DCE -lpthreads -lmach -lc_r -lc
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]608 (butenhof@zko.dec.com)
609 Digital UNIX 4.x/DCE -lpthreads -lpthread -lmach -lexc -lc
610 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]611 Digital UNIX 4.x/POSIX -lpthread -lmach -lexc -lc
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]612 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]613 AIX 4.1.4/{draft7,DCE} (nothing)
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]614 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]615 IRIX 6.2/POSIX -lpthread
Guido van Rossumdc8a3cb1998-05-12 15:29:18[diff] [blame]616 (jph@emilia.engr.sgi.com)
617
618
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]619Configuring additional built-in modules
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]620---------------------------------------
Guido van Rossum19e0c261995-01-17 16:36:34[diff] [blame]621
Andrew M. Kuchlingebe30452001-02-27 03:24:24[diff] [blame]622Starting with Python 2.1, the setup.py script at the top of the source
623distribution attempts to detect which modules can be built and
624automatically compiles them. Autodetection doesn't always work, so
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]625you can still customize the configuration by editing the Modules/Setup
626file; but this should be considered a last resort. The rest of this
627section only applies if you decide to edit the Modules/Setup file.
628You also need this to enable static linking of certain modules (which
629is needed to enable profiling on some systems).
630
Andrew M. Kuchlingebe30452001-02-27 03:24:24[diff] [blame]631This file is initially copied from Setup.dist by the configure script;
632if it does not exist yet, create it by copying Modules/Setup.dist
633yourself (configure will never overwrite it). Never edit Setup.dist
634-- always edit Setup or Setup.local (see below). Read the comments in
635the file for information on what kind of edits are allowed. When you
636have edited Setup in the Modules directory, the interpreter will
Guido van Rossumef67ded2001-10-05 17:04:42[diff] [blame]637automatically be rebuilt the next time you run make (in the toplevel
638directory).
Guido van Rossum627b2d71993-12-24 10:39:16[diff] [blame]639
Andrew M. Kuchlingebe30452001-02-27 03:24:24[diff] [blame]640Many useful modules can be built on any Unix system, but some optional
641modules can't be reliably autodetected. Often the quickest way to
642determine whether a particular module works or not is to see if it
643will build: enable it in Setup, then if you get compilation or link
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]644errors, disable it -- you're either missing support or need to adjust
645the compilation and linking parameters for that module.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]646
647On SGI IRIX, there are modules that interface to many SGI specific
Andrew M. Kuchlingebe30452001-02-27 03:24:24[diff] [blame]648system libraries, e.g. the GL library and the audio hardware. These
649modules will not be built by the setup.py script.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]650
Guido van Rossum4462e931997-01-22 21:00:32[diff] [blame]651In addition to the file Setup, you can also edit the file Setup.local.
652(the makesetup script processes both). You may find it more
653convenient to edit Setup.local and leave Setup alone. Then, when
654installing a new Python version, you can copy your old Setup.local
655file.
656
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]657
658Setting the optimization/debugging options
659------------------------------------------
660
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]661If you want or need to change the optimization/debugging options for
662the C compiler, assign to the OPT variable on the toplevel make
663command; e.g. "make OPT=-g" will build a debugging version of Python
664on most platforms. The default is OPT=-O; a value for OPT in the
665environment when the configure script is run overrides this default
666(likewise for CC; and the initial value for LIBS is used as the base
667set of libraries to link with).
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]668
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]669When compiling with GCC, the default value of OPT will also include
670the -Wall and -Wstrict-prototypes options.
671
672Additional debugging code to help debug memory management problems can
673be enabled by using the --with-pydebug option to the configure script.
674
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]675
Guido van Rossuma68ca352001-10-04 17:00:07[diff] [blame]676Profiling
677---------
678
679If you want C profiling turned on, the easiest way is to run configure
680with the CC environment variable to the necessary compiler
681invocation. For example, on Linux, this works for profiling using
682gprof(1):
683
684 CC="gcc -pg" ./configure
685
686Note that on Linux, gprof apparently does not work for shared
687libraries. The Makefile/Setup mechanism can be used to compile and
688link most extension module statically.
689
690
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]691Testing
692-------
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]693
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]694To test the interpreter, type "make test" in the top-level directory.
Guido van Rossum6ae5d3d1997-05-14 21:39:05[diff] [blame]695This runs the test set twice (once with no compiled files, once with
696the compiled files left by the previous test run). The test set
697produces some output. You can generally ignore the messages about
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]698skipped tests due to optional features which can't be imported.
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]699If a message is printed about a failed test or a traceback or core
700dump is produced, something is wrong. On some Linux systems (those
Guido van Rossum24df6841997-12-30 04:32:30[diff] [blame]701that are not yet using glibc 6), test_strftime fails due to a
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]702non-standard implementation of strftime() in the C library. Please
703ignore this, or upgrade to glibc version 6.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]704
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]705IMPORTANT: If the tests fail and you decide to mail a bug report,
706*don't* include the output of "make test". It is useless. Run the
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]707failing test manually, as follows:
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]708
Michael W. Hudson777f1432002-03-25 13:15:52[diff] [blame]709 ./python ./Lib/test/test_whatever.py
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]710
Michael W. Hudson777f1432002-03-25 13:15:52[diff] [blame]711(substituting the top of the source tree for '.' if you built in a
Guido van Rossum6ae5d3d1997-05-14 21:39:05[diff] [blame]712different directory). This runs the test in verbose mode.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]713
714
715Installing
716----------
717
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]718To install the Python binary, library modules, shared library modules
719(see below), include files, configuration files, and the manual page,
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]720just type
721
722 make install
723
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]724This will install all platform-independent files in subdirectories of
725the directory given with the --prefix option to configure or to the
726`prefix' Make variable (default /usr/local). All binary and other
727platform-specific files will be installed in subdirectories if the
728directory given by --exec-prefix or the `exec_prefix' Make variable
729(defaults to the --prefix directory) is given.
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]730
731All subdirectories created will have Python's version number in their
732name, e.g. the library modules are installed in
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]733"/usr/local/lib/python<version>/" by default, where <version> is the
734<major>.<minor> release number (e.g. "2.1"). The Python binary is
735installed as "python<version>" and a hard link named "python" is
736created. The only file not installed with a version number in its
737name is the manual page, installed as "/usr/local/man/man1/python.1"
738by default.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]739
Neil Schemenauer0e91dc72001-02-16 04:18:08[diff] [blame]740If you have a previous installation of Python that you don't
Guido van Rossum64773801997-11-26 17:07:02[diff] [blame]741want to replace yet, use
742
743 make altinstall
744
745This installs the same set of files as "make install" except it
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]746doesn't create the hard link to "python<version>" named "python" and
747it doesn't install the manual page at all.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]748
Neil Schemenauer0e91dc72001-02-16 04:18:08[diff] [blame]749Alpha/beta revision levels are stripped from the executable and
750library filenames during installation. For example, Python2.1a2 will
751install as python2.1, overwriting the previous python2.1. To avoid
752this, you could set the Makefile VERSION variable manually
753(e.g. VERSION=2.1a2) before running "make install" or "make altinstall".
754
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]755The only thing you may have to install manually is the Python mode for
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]756Emacs found in Misc/python-mode.el. (But then again, more recent
757versions of Emacs may already have it.) Follow the instructions that
758came with Emacs for installation of site-specific files.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]759
Jack Jansena39ef862001-08-19 21:17:03[diff] [blame]760On Mac OS X, if you have configured Python with --enable-framework, you
761should use "make frameworkinstall" to do the installation. Note that this
762installs the Python executable in a place that is not normally on your
763PATH, you may want to set up a symlink in /usr/local/bin.
764
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]765
766Configuration options and variables
767-----------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]768
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]769Some special cases are handled by passing options to the configure
770script.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]771
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]772WARNING: if you rerun the configure script with different options, you
773must run "make clean" before rebuilding. Exceptions to this rule:
774after changing --prefix or --exec-prefix, all you need to do is remove
Guido van Rossumb06df271997-08-05 21:50:20[diff] [blame]775Modules/getpath.o.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]776
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]777--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
778 it finds it. If you don't want this, or if this compiler is
779 installed but broken on your platform, pass the option
780 --without-gcc. You can also pass "CC=cc" (or whatever the
781 name of the proper C compiler is) in the environment, but the
782 advantage of using --without-gcc is that this option is
783 remembered by the config.status script for its --recheck
784 option.
Guido van Rossum76be6ed1995-01-02 18:33:54[diff] [blame]785
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]786--prefix, --exec-prefix: If you want to install the binaries and the
787 Python library somewhere else than in /usr/local/{bin,lib},
788 you can pass the option --prefix=DIRECTORY; the interpreter
789 binary will be installed as DIRECTORY/bin/python and the
790 library files as DIRECTORY/lib/python/*. If you pass
791 --exec-prefix=DIRECTORY (as well) this overrides the
792 installation prefix for architecture-dependent files (like the
793 interpreter binary). Note that --prefix=DIRECTORY also
794 affects the default module search path (sys.path), when
795 Modules/config.c is compiled. Passing make the option
796 prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
797 prefix set at configuration time; this may be more convenient
798 than re-running the configure script if you change your mind
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]799 about the install prefix.
Guido van Rossum76be6ed1995-01-02 18:33:54[diff] [blame]800
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]801--with-readline: This option is no longer supported. GNU
802 readline is automatically enabled by setup.py when present.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]803
Guido van Rossum7ac11532000-08-29 21:36:40[diff] [blame]804--with-threads: On most Unix systems, you can now use multiple
805 threads, and support for this is enabled by default. To
806 disable this, pass --with-threads=no. If the library required
807 for threads lives in a peculiar place, you can use
808 --with-thread=DIRECTORY. IMPORTANT: run "make clean" after
809 changing (either enabling or disabling) this option, or you
810 will get link errors! Note: for DEC Unix use
Guido van Rossum0e13da91998-02-22 04:36:34[diff] [blame]811 --with-dec-threads instead.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]812
813--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
814 supported by the "dl" library by Jack Jansen, which is
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]815 ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]816 This is enabled (after you've ftp'ed and compiled the dl
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]817 library) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]818 is the absolute pathname of the dl library. (Don't bother on
819 IRIX 5, it already has dynamic linking using SunOS style
820 shared libraries.) Support for this feature is deprecated.
821
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]822--with-dl-dld: Dynamic loading of modules is rumored to be supported
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]823 on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
824 Symmetry (Dynix), and Atari ST. This is done using a
825 combination of the GNU dynamic loading package
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]826 (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]827 emulation of the SGI dl library mentioned above (the emulation
828 can be found at
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]829 ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z). To
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]830 enable this, ftp and compile both libraries, then call
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]831 configure, passing it the option
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]832 --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
833 the absolute pathname of the dl emulation library and
834 DLD_DIRECTORY is the absolute pathname of the GNU dld library.
835 (Don't bother on SunOS 4 or 5, they already have dynamic
836 linking using shared libraries.) Support for this feature is
837 deprecated.
838
839--with-libm, --with-libc: It is possible to specify alternative
840 versions for the Math library (default -lm) and the C library
841 (default the empty string) using the options
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]842 --with-libm=STRING and --with-libc=STRING, respectively. For
843 example, if your system requires that you pass -lc_s to the C
844 compiler to use the shared C library, you can pass
845 --with-libc=-lc_s. These libraries are passed after all other
846 libraries, the C library last.
Guido van Rossum16e809e2001-04-16 02:07:08[diff] [blame]847
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]848--with-libs='libs': Add 'libs' to the LIBS that the python interpreter
849 is linked against.
Guido van Rossumd02ba451996-07-31 17:36:01[diff] [blame]850
Martin v. Löwis2df66942000-12-13 14:14:32[diff] [blame]851--with-cxx=<compiler>: Some C++ compilers require that main() is
852 compiled with the C++ if there is any C++ code in the application.
853 Specifically, g++ on a.out systems may require that to support
854 construction of global objects. With this option, the main() function
855 of Python will be compiled with <compiler>; use that only if you
856 plan to use C++ extension modules, and if your compiler requires
857 compilation of main() as a C++ program.
858
859
Fred Drake6caae142000-10-25 17:51:02[diff] [blame]860--with-pydebug: Enable additional debugging code to help track down
861 memory management problems. This allows printing a list of all
862 live objects when the interpreter terminates.
863
Guido van Rossum76be6ed1995-01-02 18:33:54[diff] [blame]864
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]865Building for multiple architectures (using the VPATH feature)
866-------------------------------------------------------------
867
868If your file system is shared between multiple architectures, it
869usually is not necessary to make copies of the sources for each
870architecture you want to support. If the make program supports the
871VPATH feature, you can create an empty build directory for each
872architecture, and in each directory run the configure script (on the
873appropriate machine with the appropriate options). This creates the
874necessary subdirectories and the Makefiles therein. The Makefiles
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]875contain a line VPATH=... which points to a directory containing the
Guido van Rossumd0fe8451996-08-26 03:02:37[diff] [blame]876actual sources. (On SGI systems, use "smake -J1" instead of "make" if
877you use VPATH -- don't try gnumake.)
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]878
879For example, the following is all you need to build a minimal Python
880in /usr/tmp/python (assuming ~guido/src/python is the toplevel
881directory and you want to build in /usr/tmp/python):
882
883 $ mkdir /usr/tmp/python
884 $ cd /usr/tmp/python
885 $ ~guido/src/python/configure
886 [...]
887 $ make
888 [...]
889 $
890
Neil Schemenauer73f8ab22001-01-26 22:18:55[diff] [blame]891Note that configure copies the original Setup file to the build
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]892directory if it finds no Setup file there. This means that you can
893edit the Setup file for each architecture independently. For this
894reason, subsequent changes to the original Setup file are not tracked
895automatically, as they might overwrite local changes. To force a copy
896of a changed original Setup file, delete the target Setup file. (The
897makesetup script supports multiple input files, so if you want to be
898fancy you can change the rules to create an empty Setup.local if it
899doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
900however this assumes that you only need to add modules.)
901
902
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]903Building on non-UNIX systems
904----------------------------
905
Tim Peters03444242000-09-19 00:38:35[diff] [blame]906For Windows (2000/NT/ME/98/95), assuming you have MS VC++ 6.0, the
907project files are in PCbuild, the workspace is pcbuild.dsw. See
908PCbuild\readme.txt for detailed instructions.
Guido van Rossum8d7d4ed1996-07-30 21:41:07[diff] [blame]909
Guido van Rossum31ae2071999-04-12 14:47:30[diff] [blame]910For other non-Unix Windows compilers, in particular Windows 3.1 and
911for OS/2, enter the directory "PC" and read the file "readme.txt".
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]912
913For the Mac, a separate source distribution will be made available,
914for use with the CodeWarrior compiler. If you are interested in Mac
915development, join the PythonMac Special Interest Group
916(http://www.python.org/sigs/pythonmac-sig/, or send email to
917pythonmac-sig-request@python.org).
918
919Of course, there are also binary distributions available for these
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]920platforms -- see http://www.python.org/.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]921
922To port Python to a new non-UNIX system, you will have to fake the
923effect of running the configure script manually (for Mac and PC, this
924has already been done for you). A good start is to copy the file
Fred Drake622dca02002-11-04 20:50:39[diff] [blame]925pyconfig.h.in to pyconfig.h and edit the latter to reflect the actual
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]926configuration of your system. Most symbols must simply be defined as
9271 only if the corresponding feature is present and can be left alone
Tim Peters4f1b2082000-07-23 21:18:09[diff] [blame]928otherwise; however the *_t type symbols must be defined as some variant
929of int if they need to be defined at all.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]930
Barry Warsaw06557452001-12-14 20:47:12[diff] [blame]931For all platforms, it's important that the build arrange to define the
932preprocessor symbol NDEBUG on the compiler command line in a release
933build of Python (else assert() calls remain in the code, hurting
934release-build performance). The Unix, Windows and Mac builds already
935do this.
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]936
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]937
938Miscellaneous issues
939====================
940
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]941Emacs mode
942----------
943
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]944There's an excellent Emacs editing mode for Python code; see the file
945Misc/python-mode.el. Originally written by the famous Tim Peters, it
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]946is now maintained by the equally famous Barry Warsaw (it's no
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]947coincidence that they now both work on the same team). The latest
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]948version, along with various other contributed Python-related Emacs
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]949goodies, is online at http://www.python.org/emacs/python-mode. And
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]950if you are planning to edit the Python C code, please pick up the
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]951latest version of CC Mode http://www.python.org/emacs/cc-mode; it
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]952contains a "python" style used throughout most of the Python C source
953files. (Newer versions of Emacs or XEmacs may already come with the
954latest version of python-mode.)
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]955
956
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]957Tkinter
958-------
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]959
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]960The setup.py script automatically configures this when it detects a
961usable Tcl/Tk installation. This requires Tcl/Tk version 8.0 or
Fred Drake8179a9d2000-09-28 23:28:30[diff] [blame]962higher.
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]963
Guido van Rossum973e4dc2000-07-01 00:34:39[diff] [blame]964For more Tkinter information, see the Tkinter Resource page:
965http://www.python.org/topics/tkinter/
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]966
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]967There are demos in the Demo/tkinter directory, in the subdirectories
968guido, matt and www (the matt and guido subdirectories have been
969overhauled to use more recent Tkinter coding conventions).
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]970
971Note that there's a Python module called "Tkinter" (capital T) which
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]972lives in Lib/lib-tk/Tkinter.py, and a C module called "_tkinter"
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]973(lower case t and leading underscore) which lives in
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]974Modules/_tkinter.c. Demos and normal Tk applications import only the
Michael W. Hudson45c44fb2002-02-22 13:50:51[diff] [blame]975Python Tkinter module -- only the latter imports the C _tkinter
976module. In order to find the C _tkinter module, it must be compiled
977and linked into the Python interpreter -- the setup.py script does
978this. In order to find the Python Tkinter module, sys.path must be
979set correctly -- normal installation takes care of this.
Guido van Rossum84c8c7f1995-08-28 02:44:24[diff] [blame]980
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]981
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]982Distribution structure
983----------------------
984
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]985Most subdirectories have their own README files. Most files have
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]986comments.
987
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]988.cvsignore Additional filename matching patterns for CVS to ignore
989BeOS/ Files specific to the BeOS port
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]990Demo/ Demonstration scripts, modules and programs
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]991Doc/ Documentation sources (LaTeX)
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]992Grammar/ Input for the parser generator
993Include/ Public header files
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]994LICENSE Licensing information
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]995Lib/ Python library modules
Neil Schemenauer3f52da52001-01-24 17:49:59[diff] [blame]996Makefile.pre.in Source from which config.status creates the Makefile.pre
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]997Misc/ Miscellaneous useful files
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]998Modules/ Implementation of most built-in modules
999Objects/ Implementation of most built-in object types
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1000PC/ Files specific to PC ports (DOS, Windows, OS/2)
1001PCbuild/ Build directory for Microsoft Visual C++
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1002Parser/ The parser and tokenizer and their input handling
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]1003Python/ The byte-compiler and interpreter
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1004README The file you're reading now
1005Tools/ Some useful programs written in Python
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1006acconfig.h Additional input for the GNU autoheader program
Fred Drake622dca02002-11-04 20:50:39[diff] [blame]1007pyconfig.h.in Source from which pyconfig.h is created (GNU autoheader output)
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1008configure Configuration shell script (GNU autoconf output)
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1009configure.in Configuration specification (input for GNU autoconf)
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1010install-sh Shell script used to install files
Guido van Rossum91cb9d21995-04-10 11:47:38[diff] [blame]1011
1012The following files will (may) be created in the toplevel directory by
1013the configuration and build processes:
1014
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1015Makefile Build rules
Neil Schemenauer3f52da52001-01-24 17:49:59[diff] [blame]1016Makefile.pre Build rules before running Modules/makesetup
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1017buildno Keeps track of the build number
1018config.cache Cache of configuration variables
Fred Drake622dca02002-11-04 20:50:39[diff] [blame]1019pyconfig.h Configuration header
Guido van Rossumc0be2f51997-10-08 05:05:28[diff] [blame]1020config.log Log from last configure run
Guido van Rossum4f40c2d2000-09-05 16:46:22[diff] [blame]1021config.status Status from last run of the configure script
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1022getbuildinfo.o Object file from Modules/getbuildinfo.c
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]1023libpython<version>.a The library archive
Guido van Rossum6d9cc801996-08-01 17:31:22[diff] [blame]1024python The executable interpreter
1025tags, TAGS Tags files for vi and Emacs
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]1026
1027
Guido van Rossumc07d5fa2000-09-01 22:50:02[diff] [blame]1028That's all, folks!
1029------------------
Guido van Rossum433c8ad1994-08-01 12:07:07[diff] [blame]1030
1031
Guido van Rossum67345eb2001-01-18 14:51:12[diff] [blame]1032--Guido van Rossum (home page: http://www.python.org/~guido/)