blob: 5a5b8e145771cccc5bb57fa25c7c415e639b4984 [file] [log] [blame]
Benjamin Petersonc2516072010-05-08 17:08:17 +00001This is Python version 2.7 beta 2
Benjamin Petersonfbac6c12010-04-10 16:22:05 +00002=================================
Guido van Rossum91447632000-04-11 17:11:09 +00003
Ezio Melotti9db77462010-01-01 04:16:42 +00004Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Anthony Baxter83955ef2007-01-06 04:45:54 +00005Python Software Foundation.
Guido van Rossum67345eb2001-01-18 14:51:12 +00006All rights reserved.
7
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00008Copyright (c) 2000 BeOpen.com.
9All rights reserved.
10
Guido van Rossum23f7aed2001-04-12 20:53:31 +000011Copyright (c) 1995-2001 Corporation for National Research Initiatives.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000012All rights reserved.
13
Guido van Rossum6ebd2992000-09-03 04:47:47 +000014Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000015All rights reserved.
16
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000017
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000018License information
19-------------------
20
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000021See the file "LICENSE" for information on the history of this
22software, terms & conditions for usage, and a DISCLAIMER OF ALL
23WARRANTIES.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000024
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000025This Python distribution contains no GNU General Public Licensed
26(GPLed) code so it may be used in proprietary projects just like prior
27Python distributions. There are interfaces to some GNU code but these
28are entirely optional.
29
30All trademarks referenced herein are property of their respective
31holders.
Guido van Rossum79808261997-12-11 18:01:47 +000032
33
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +000034What's new in this release?
35---------------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000036
Guido van Rossum67345eb2001-01-18 14:51:12 +000037See the file "Misc/NEWS".
Guido van Rossum64773801997-11-26 17:07:02 +000038
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +000039
Guido van Rossum64773801997-11-26 17:07:02 +000040If you don't read instructions
41------------------------------
42
43Congratulations on getting this far. :-)
44
45To start building right away (on UNIX): type "./configure" in the
Guido van Rossum2dcec0c2002-02-04 01:59:23 +000046current directory and when it finishes, type "make". This creates an
47executable "./python"; to install in /usr/local, first do "su root"
48and then "make install".
49
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +000050The section `Build instructions' below is still recommended reading.
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000051
52
Guido van Rossum91cb9d21995-04-10 11:47:38 +000053What is Python anyway?
54----------------------
55
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +000056Python is an interpreted, interactive object-oriented programming
57language suitable (amongst other uses) for distributed application
58development, scripting, numeric computing and system testing. Python
59is often compared to Tcl, Perl, Java, JavaScript, Visual Basic or
60Scheme. To find out more about what Python can do for you, point your
61browser to http://www.python.org/.
Guido van Rossum91cb9d21995-04-10 11:47:38 +000062
63
Guido van Rossumf501b4e1996-10-25 14:32:48 +000064How do I learn Python?
65----------------------
66
Fred Drake0e6444c1999-05-17 19:35:01 +000067The official tutorial is still a good place to start; see
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +000068http://docs.python.org/ for online and downloadable versions, as well
69as a list of other introductions, and reference documentation.
Guido van Rossumf501b4e1996-10-25 14:32:48 +000070
Guido van Rossumd0a42e22000-03-31 20:16:45 +000071There's a quickly growing set of books on Python. See
Michael W. Hudsonfad46402005-06-16 15:51:20 +000072http://wiki.python.org/moin/PythonBooks for a list.
Guido van Rossum8d90f9d1997-05-22 20:13:25 +000073
Guido van Rossumf501b4e1996-10-25 14:32:48 +000074
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000075Documentation
76-------------
Guido van Rossum91cb9d21995-04-10 11:47:38 +000077
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000078All documentation is provided online in a variety of formats. In
79order of importance for new users: Tutorial, Library Reference,
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000080Language Reference, Extending & Embedding, and the Python/C API. The
81Library Reference is especially of immense value since much of
82Python's power is described there, including the built-in data types
83and functions!
Guido van Rossum91cb9d21995-04-10 11:47:38 +000084
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000085All documentation is also available online at the Python web site
Benjamin Peterson9d0b6042008-03-30 19:35:10 +000086(http://docs.python.org/, see below). It is available online for occasional
87reference, or can be downloaded in many formats for faster access. The
Georg Brandl1c88e0f2008-03-30 19:41:39 +000088documentation is downloadable in HTML, PostScript, PDF, LaTeX, and
Benjamin Peterson9d0b6042008-03-30 19:35:10 +000089reStructuredText (2.6+) formats; the LaTeX and reStructuredText versions are
90primarily for documentation authors, translators, and people with special
91formatting requirements.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000092
93
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000094Web sites
95---------
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000096
Guido van Rossum4f40c2d2000-09-05 16:46:22 +000097New Python releases and related technologies are published at
Guido van Rossum67345eb2001-01-18 14:51:12 +000098http://www.python.org/. Come visit us!
Guido van Rossumc07d5fa2000-09-01 22:50:02 +000099
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000100
101Newsgroups and Mailing Lists
102----------------------------
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000103
104Read comp.lang.python, a high-volume discussion newsgroup about
105Python, or comp.lang.python.announce, a low-volume moderated newsgroup
106for Python-related announcements. These are also accessible as
Georg Brandl4492a982009-08-24 17:12:30 +0000107mailing lists: see http://www.python.org/community/lists/ for an
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000108overview of these and many other Python-related mailing lists.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000109
Anthony Baxter70e07962006-04-03 14:16:27 +0000110Archives are accessible via the Google Groups Usenet archive; see
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +0000111http://groups.google.com/. The mailing lists are also archived, see
Georg Brandl4492a982009-08-24 17:12:30 +0000112http://www.python.org/community/lists/ for details.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000113
114
115Bug reports
116-----------
117
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000118To report or search for bugs, please use the Python Bug
Georg Brandl4492a982009-08-24 17:12:30 +0000119Tracker at http://bugs.python.org/.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000120
121
122Patches and contributions
123-------------------------
124
Fred Drake6caae142000-10-25 17:51:02 +0000125To submit a patch or other contribution, please use the Python Patch
Georg Brandl4492a982009-08-24 17:12:30 +0000126Manager at http://bugs.python.org/. Guidelines
Andrew M. Kuchling951300e2008-01-04 14:47:17 +0000127for patch submission may be found at http://www.python.org/dev/patches/.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000128
Benjamin Petersonb2355002008-04-02 21:20:35 +0000129If you have a proposal to change Python, you may want to send an email to the
130comp.lang.python or python-ideas mailing lists for inital feedback. A Python
131Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
132current PEPs, as well as guidelines for submitting a new PEP, are listed at
133http://www.python.org/dev/peps/.
Guido van Rossumc07d5fa2000-09-01 22:50:02 +0000134
135
136Questions
137---------
138
139For help, if you can't find it in the manuals or on the web site, it's
140best to post to the comp.lang.python or the Python mailing list (see
141above). If you specifically don't want to involve the newsgroup or
Guido van Rossum67345eb2001-01-18 14:51:12 +0000142mailing list, send questions to help@python.org (a group of volunteers
143who answer questions as they can). The newsgroup is the most
144efficient way to ask public questions.
Guido van Rossum627b2d71993-12-24 10:39:16 +0000145
Guido van Rossum901454e2000-06-29 22:28:44 +0000146
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000147Build instructions
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000148==================
Guido van Rossum627b2d71993-12-24 10:39:16 +0000149
Guido van Rossum59b0b602002-02-08 22:22:35 +0000150Before you can build Python, you must first configure it.
151Fortunately, the configuration and build process has been automated
152for Unix and Linux installations, so all you usually have to do is
153type a few commands and sit back. There are some platforms where
154things are not quite as smooth; see the platform specific notes below.
155If you want to build for multiple platforms sharing the same source
156tree, see the section on VPATH below.
Guido van Rossum627b2d71993-12-24 10:39:16 +0000157
Guido van Rossum59b0b602002-02-08 22:22:35 +0000158Start by running the script "./configure", which determines your
159system configuration and creates the Makefile. (It takes a minute or
160two -- please be patient!) You may want to pass options to the
161configure script -- see the section below on configuration options and
162variables. When it's done, you are ready to run make.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000163
Guido van Rossum59b0b602002-02-08 22:22:35 +0000164To build Python, you normally type "make" in the toplevel directory.
165If you have changed the configuration, the Makefile may have to be
Benjamin Peterson7bee77c2009-02-26 19:05:59 +0000166rebuilt. In this case, you may have to run make again to correctly
Guido van Rossum59b0b602002-02-08 22:22:35 +0000167build your desired target. The interpreter executable is built in the
168top level directory.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000169
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000170Once you have built a Python interpreter, see the subsections below on
Guido van Rossum59b0b602002-02-08 22:22:35 +0000171testing and installation. If you run into trouble, see the next
172section.
173
174Previous versions of Python used a manual configuration process that
175involved editing the file Modules/Setup. While this file still exists
176and manual configuration is still supported, it is rarely needed any
177more: almost all modules are automatically built as appropriate under
178guidance of the setup.py script, which is run by Make after the
179interpreter has been built.
Guido van Rossum627b2d71993-12-24 10:39:16 +0000180
Guido van Rossum0a516c91994-09-12 10:58:40 +0000181
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000182Troubleshooting
183---------------
Guido van Rossum627b2d71993-12-24 10:39:16 +0000184
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000185See also the platform specific notes in the next section.
186
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000187If you run into other trouble, see the FAQ
Georg Brandl4492a982009-08-24 17:12:30 +0000188(http://www.python.org/doc/faq/) for hints on what can go wrong, and
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000189how to fix it.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000190
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000191If you rerun the configure script with different options, remove all
192object files by running "make clean" before rebuilding. Believe it or
193not, "make clean" sometimes helps to clean up other inexplicable
194problems as well. Try it before sending in a bug report!
195
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000196If the configure script fails or doesn't seem to find things that
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000197should be there, inspect the config.log file.
Guido van Rossumc0be2f51997-10-08 05:05:28 +0000198
199If you get a warning for every file about the -Olimit option being no
200longer supported, you can ignore it. There's no foolproof way to know
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000201whether this option is needed; all we can do is test whether it is
Guido van Rossumc0be2f51997-10-08 05:05:28 +0000202accepted without error. On some systems, e.g. older SGI compilers, it
203is essential for performance (specifically when compiling ceval.c,
204which has more basic blocks than the default limit of 1000). If the
205warning bothers you, edit the Makefile to remove "-Olimit 1500" from
206the OPT variable.
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000207
Guido van Rossum7ac11532000-08-29 21:36:40 +0000208If you get failures in test_long, or sys.maxint gets set to -1, you
209are probably experiencing compiler bugs, usually related to
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000210optimization. This is a common problem with some versions of gcc, and
211some vendor-supplied compilers, which can sometimes be worked around
212by turning off optimization. Consider switching to stable versions
Anthony Baxtere9d719b2004-11-30 01:49:18 +0000213(gcc 2.95.2, gcc 3.x, or contact your vendor.)
Guido van Rossum7ac11532000-08-29 21:36:40 +0000214
215From Python 2.0 onward, all Python C code is ANSI C. Compiling using
216old K&R-C-only compilers is no longer possible. ANSI C compilers are
217available for all modern systems, either in the form of updated
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000218compilers from the vendor, or one of the free compilers (gcc).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000219
Georg Brandl250755b2006-11-15 17:42:03 +0000220If "make install" fails mysteriously during the "compiling the library"
221step, make sure that you don't have any of the PYTHONPATH or PYTHONHOME
222environment variables set, as they may interfere with the newly built
223executable which is compiling the library.
224
Martin v. Löwis779ffc02002-12-02 22:17:01 +0000225Unsupported systems
226-------------------
227
Martin v. Löwis8cab8b02006-07-24 05:05:22 +0000228A number of features are not supported in Python 2.5 anymore. Some
229support code is still present, but will be removed in Python 2.6.
Martin v. Löwis779ffc02002-12-02 22:17:01 +0000230If you still need to use current Python versions on these systems,
231please send a message to python-dev@python.org indicating that you
Martin v. Löwis8cab8b02006-07-24 05:05:22 +0000232volunteer to support this system. For a more detailed discussion
233regarding no-longer-supported and resupporting platforms, as well
234as a list of platforms that became or will be unsupported, see PEP 11.
Martin v. Löwis779ffc02002-12-02 22:17:01 +0000235
236More specifically, the following systems are not supported any
237longer:
238- SunOS 4
239- DYNIX
240- dgux
241- Minix
Martin v. Löwis8cab8b02006-07-24 05:05:22 +0000242- NeXT
Martin v. Löwis779ffc02002-12-02 22:17:01 +0000243- Irix 4 and --with-sgi-dl
244- Linux 1
245- Systems defining __d6_pthread_create (configure.in)
246- Systems defining PY_PTHREAD_D4, PY_PTHREAD_D6,
247 or PY_PTHREAD_D7 in thread_pthread.h
248- Systems using --with-dl-dld
Martin v. Löwis7e4cfcb2002-12-19 16:21:49 +0000249- Systems using --without-universal-newlines
Martin v. Löwis8cab8b02006-07-24 05:05:22 +0000250- MacOS 9
Martin v. Löwis8cab8b02006-07-24 05:05:22 +0000251- Systems using --with-wctype-functions
252- Win9x, WinME
253
Martin v. Löwis779ffc02002-12-02 22:17:01 +0000254
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000255Platform specific notes
256-----------------------
257
Guido van Rossum0447a321995-10-08 01:22:33 +0000258(Some of these may no longer apply. If you find you can build Python
Guido van Rossum67345eb2001-01-18 14:51:12 +0000259on these platforms without the special directions mentioned here,
260submit a documentation bug report to SourceForge (see Bug Reports
261above) so we can remove them!)
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000262
Skip Montanaro6dc4a8e2003-05-02 15:27:59 +0000263Unix platforms: If your vendor still ships (and you still use) Berkeley DB
Anthony Baxter70e07962006-04-03 14:16:27 +0000264 1.85 you will need to edit Modules/Setup to build the bsddb185
265 module and add a line to sitecustomize.py which makes it the
266 default. In Modules/Setup a line like
Skip Montanaro6dc4a8e2003-05-02 15:27:59 +0000267
Anthony Baxter70e07962006-04-03 14:16:27 +0000268 bsddb185 bsddbmodule.c
Skip Montanaro6dc4a8e2003-05-02 15:27:59 +0000269
Anthony Baxter70e07962006-04-03 14:16:27 +0000270 should work. (You may need to add -I, -L or -l flags to direct the
271 compiler and linker to your include files and libraries.)
Skip Montanaro6dc4a8e2003-05-02 15:27:59 +0000272
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000273XXX I think this next bit is out of date:
Skip Montanaro6dc4a8e2003-05-02 15:27:59 +0000274
Brett Cannondc48b742007-05-20 07:09:50 +000027564-bit platforms: The modules audioop, and imageop don't work.
Anthony Baxter70e07962006-04-03 14:16:27 +0000276 The setup.py script disables them on 64-bit installations.
277 Don't try to enable them in the Modules/Setup file. They
278 contain code that is quite wordsize sensitive. (If you have a
279 fix, let us know!)
Guido van Rossumc0be2f51997-10-08 05:05:28 +0000280
Guido van Rossum4462e931997-01-22 21:00:32 +0000281Solaris: When using Sun's C compiler with threads, at least on Solaris
Anthony Baxter70e07962006-04-03 14:16:27 +0000282 2.5.1, you need to add the "-mt" compiler option (the simplest
283 way is probably to specify the compiler with this option as
284 the "CC" environment variable when running the configure
285 script).
Guido van Rossum4462e931997-01-22 21:00:32 +0000286
Guido van Rossum42992312002-09-23 14:02:18 +0000287 When using GCC on Solaris, beware of binutils 2.13 or GCC
288 versions built using it. This mistakenly enables the
289 -zcombreloc option which creates broken shared libraries on
290 Solaris. binutils 2.12 works, and the binutils maintainers
Skip Montanaro4de9cba2003-01-03 16:26:23 +0000291 are aware of the problem. Binutils 2.13.1 only partially
292 fixed things. It appears that 2.13.2 solves the problem
293 completely. This problem is known to occur with Solaris 2.7
294 and 2.8, but may also affect earlier and later versions of the
295 OS.
Guido van Rossum42992312002-09-23 14:02:18 +0000296
Anthony Baxter70e07962006-04-03 14:16:27 +0000297 When the dynamic loader complains about errors finding shared
298 libraries, such as
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000299
Anthony Baxter70e07962006-04-03 14:16:27 +0000300 ld.so.1: ./python: fatal: libstdc++.so.5: open failed:
301 No such file or directory
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000302
Anthony Baxter70e07962006-04-03 14:16:27 +0000303 you need to first make sure that the library is available on
304 your system. Then, you need to instruct the dynamic loader how
305 to find it. You can choose any of the following strategies:
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000306
Anthony Baxter70e07962006-04-03 14:16:27 +0000307 1. When compiling Python, set LD_RUN_PATH to the directories
308 containing missing libraries.
309 2. When running Python, set LD_LIBRARY_PATH to these directories.
310 3. Use crle(8) to extend the search path of the loader.
311 4. Modify the installed GCC specs file, adding -R options into the
312 *link: section.
Martin v. Löwis9cea5f52002-11-15 07:28:05 +0000313
Skip Montanaro9f6606a2005-11-17 18:19:39 +0000314 The complex object fails to compile on Solaris 10 with gcc 3.4 (at
315 least up to 3.4.3). To work around it, define Py_HUGE_VAL as
316 HUGE_VAL(), e.g.:
317
318 make CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()" -I. -I$(srcdir)/Include'
Anthony Baxter70e07962006-04-03 14:16:27 +0000319 ./python setup.py CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()"'
Skip Montanaro9f6606a2005-11-17 18:19:39 +0000320
Guido van Rossum7ac11532000-08-29 21:36:40 +0000321Linux: A problem with threads and fork() was tracked down to a bug in
Anthony Baxter70e07962006-04-03 14:16:27 +0000322 the pthreads code in glibc version 2.0.5; glibc version 2.0.7
323 solves the problem. This causes the popen2 test to fail;
324 problem and solution reported by Pablo Bleyer.
Guido van Rossum4462e931997-01-22 21:00:32 +0000325
Martin v. Löwis3efa04a2003-06-14 05:29:27 +0000326Red Hat Linux: Red Hat 9 built Python2.2 in UCS-4 mode and hacked
Anthony Baxter70e07962006-04-03 14:16:27 +0000327 Tcl to support it. To compile Python2.3 with Tkinter, you will
328 need to pass --enable-unicode=ucs4 flag to ./configure.
Martin v. Löwis3efa04a2003-06-14 05:29:27 +0000329
Anthony Baxter70e07962006-04-03 14:16:27 +0000330 There's an executable /usr/bin/python which is Python
331 1.5.2 on most older Red Hat installations; several key Red Hat tools
332 require this version. Python 2.1.x may be installed as
333 /usr/bin/python2. The Makefile installs Python as
334 /usr/local/bin/python, which may or may not take precedence
335 over /usr/bin/python, depending on how you have set up $PATH.
Guido van Rossum2dcec0c2002-02-04 01:59:23 +0000336
Guido van Rossum59230501999-06-21 20:51:46 +0000337FreeBSD 3.x and probably platforms with NCurses that use libmytinfo or
Anthony Baxter70e07962006-04-03 14:16:27 +0000338 similar: When using cursesmodule, the linking is not done in
339 the correct order with the defaults. Remove "-ltermcap" from
340 the readline entry in Setup, and use as curses entry: "curses
341 cursesmodule.c -lmytinfo -lncurses -ltermcap" - "mytinfo" (so
342 called on FreeBSD) should be the name of the auxiliary library
343 required on your platform. Normally, it would be linked
344 automatically, but not necessarily in the correct order.
Guido van Rossum59230501999-06-21 20:51:46 +0000345
Anthony Baxter70e07962006-04-03 14:16:27 +0000346BSDI: BSDI versions before 4.1 have known problems with threads,
347 which can cause strange errors in a number of modules (for
348 instance, the 'test_signal' test script will hang forever.)
349 Turning off threads (with --with-threads=no) or upgrading to
350 BSDI 4.1 solves this problem.
Guido van Rossum7ac11532000-08-29 21:36:40 +0000351
352DEC Unix: Run configure with --with-dec-threads, or with
Anthony Baxter70e07962006-04-03 14:16:27 +0000353 --with-threads=no if no threads are desired (threads are on by
354 default). When using GCC, it is possible to get an internal
355 compiler error if optimization is used. This was reported for
356 GCC 2.7.2.3 on selectmodule.c. Manually compile the affected
357 file without optimization to solve the problem.
Guido van Rossum8eca2c21996-02-14 18:37:46 +0000358
Guido van Rossume1cdb161999-04-10 16:04:07 +0000359DEC Ultrix: compile with GCC to avoid bugs in the native compiler,
Anthony Baxter70e07962006-04-03 14:16:27 +0000360 and pass SHELL=/bin/sh5 to Make when installing.
Guido van Rossume1cdb161999-04-10 16:04:07 +0000361
Anthony Baxter70e07962006-04-03 14:16:27 +0000362AIX: A complete overhaul of the shared library support is now in
363 place. See Misc/AIX-NOTES for some notes on how it's done.
364 (The optimizer bug reported at this place in previous releases
365 has been worked around by a minimal code change.) If you get
366 errors about pthread_* functions, during compile or during
367 testing, try setting CC to a thread-safe (reentrant) compiler,
368 like "cc_r". For full C++ module support, set CC="xlC_r" (or
369 CC="xlC" without thread support).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000370
Guido van Rossuma2534c82005-09-20 19:06:23 +0000371AIX 5.3: To build a 64-bit version with IBM's compiler, I used the
372 following:
373
374 export PATH=/usr/bin:/usr/vacpp/bin
Anthony Baxter70e07962006-04-03 14:16:27 +0000375 ./configure --with-gcc="xlc_r -q64" --with-cxx="xlC_r -q64" \
Guido van Rossuma2534c82005-09-20 19:06:23 +0000376 --disable-ipv6 AR="ar -X64"
Anthony Baxter70e07962006-04-03 14:16:27 +0000377 make
Guido van Rossuma2534c82005-09-20 19:06:23 +0000378
Anthony Baxter7c497472003-10-01 07:24:54 +0000379HP-UX: When using threading, you may have to add -D_REENTRANT to the
Anthony Baxter70e07962006-04-03 14:16:27 +0000380 OPT variable in the top-level Makefile; reported by Pat Knight,
381 this seems to make a difference (at least for HP-UX 10.20)
382 even though pyconfig.h defines it. This seems unnecessary when
383 using HP/UX 11 and later - threading seems to work "out of the
384 box".
Anthony Baxter7c497472003-10-01 07:24:54 +0000385
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000386HP-UX ia64: When building on the ia64 (Itanium) platform using HP's
Anthony Baxter70e07962006-04-03 14:16:27 +0000387 compiler, some experience has shown that the compiler's
388 optimiser produces a completely broken version of python
Georg Brandl4492a982009-08-24 17:12:30 +0000389 (see http://bugs.python.org/814976). To work around this,
Anthony Baxter70e07962006-04-03 14:16:27 +0000390 edit the Makefile and remove -O from the OPT line.
Guido van Rossum539c6622005-09-14 17:49:54 +0000391
Anthony Baxter70e07962006-04-03 14:16:27 +0000392 To build a 64-bit executable on an Itanium 2 system using HP's
393 compiler, use these environment variables:
Guido van Rossum539c6622005-09-14 17:49:54 +0000394
Anthony Baxter70e07962006-04-03 14:16:27 +0000395 CC=cc
396 CXX=aCC
397 BASECFLAGS="+DD64"
398 LDFLAGS="+DD64 -lxnet"
Guido van Rossum539c6622005-09-14 17:49:54 +0000399
Anthony Baxter70e07962006-04-03 14:16:27 +0000400 and call configure as:
Guido van Rossum539c6622005-09-14 17:49:54 +0000401
Anthony Baxter70e07962006-04-03 14:16:27 +0000402 ./configure --without-gcc
Guido van Rossum539c6622005-09-14 17:49:54 +0000403
Anthony Baxter70e07962006-04-03 14:16:27 +0000404 then *unset* the environment variables again before running
405 make. (At least one of these flags causes the build to fail
406 if it remains set.) You still have to edit the Makefile and
407 remove -O from the OPT line.
Guido van Rossum2094e041998-05-14 15:47:35 +0000408
Georg Brandl4492a982009-08-24 17:12:30 +0000409HP PA-RISC 2.0: A recent bug report (http://bugs.python.org/546117)
Anthony Baxter70e07962006-04-03 14:16:27 +0000410 suggests that the C compiler in this 64-bit system has bugs
411 in the optimizer that break Python. Compiling without
412 optimization solves the problems.
Guido van Rossum4e1dd7d2002-04-23 13:06:07 +0000413
Anthony Baxter70e07962006-04-03 14:16:27 +0000414SCO: The following apply to SCO 3 only; Python builds out of the box
415 on SCO 5 (or so we've heard).
Guido van Rossuma16e2751998-04-13 20:14:05 +0000416
Anthony Baxter70e07962006-04-03 14:16:27 +0000417 1) Everything works much better if you add -U__STDC__ to the
418 defs. This is because all the SCO header files are broken.
419 Anything that isn't mentioned in the C standard is
420 conditionally excluded when __STDC__ is defined.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000421
Anthony Baxter70e07962006-04-03 14:16:27 +0000422 2) Due to the U.S. export restrictions, SCO broke the crypt
423 stuff out into a separate library, libcrypt_i.a so the LIBS
424 needed be set to:
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000425
Anthony Baxter70e07962006-04-03 14:16:27 +0000426 LIBS=' -lsocket -lcrypt_i'
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000427
Martin v. Löwis387c5472001-09-06 08:16:17 +0000428UnixWare: There are known bugs in the math library of the system, as well as
429 problems in the handling of threads (calling fork in one
430 thread may interrupt system calls in others). Therefore, test_math and
431 tests involving threads will fail until those problems are fixed.
432
Anthony Baxter70e07962006-04-03 14:16:27 +0000433QNX: Chris Herborth (chrish@qnx.com) writes:
434 configure works best if you use GNU bash; a port is available on
435 ftp.qnx.com in /usr/free. I used the following process to build,
436 test and install Python 1.5.x under QNX:
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000437
Anthony Baxter70e07962006-04-03 14:16:27 +0000438 1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \
439 ./configure --verbose --without-gcc --with-libm=""
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000440
Anthony Baxter70e07962006-04-03 14:16:27 +0000441 2) edit Modules/Setup to activate everything that makes sense for
442 your system... tested here at QNX with the following modules:
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000443
Anthony Baxter70e07962006-04-03 14:16:27 +0000444 array, audioop, binascii, cPickle, cStringIO, cmath,
445 crypt, curses, errno, fcntl, gdbm, grp, imageop,
446 _locale, math, md5, new, operator, parser, pcre,
Neal Norwitz90340a12007-05-20 18:06:27 +0000447 posix, pwd, readline, regex, reop,
Anthony Baxter70e07962006-04-03 14:16:27 +0000448 select, signal, socket, soundex, strop, struct,
Brett Cannondc48b742007-05-20 07:09:50 +0000449 syslog, termios, time, timing, zlib, audioop, imageop
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000450
Anthony Baxter70e07962006-04-03 14:16:27 +0000451 3) make SHELL=/usr/local/bin/bash
Guido van Rossum16e809e2001-04-16 02:07:08 +0000452
Anthony Baxter70e07962006-04-03 14:16:27 +0000453 or, if you feel the need for speed:
Guido van Rossum16e809e2001-04-16 02:07:08 +0000454
Anthony Baxter70e07962006-04-03 14:16:27 +0000455 make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000456
Anthony Baxter70e07962006-04-03 14:16:27 +0000457 4) make SHELL=/usr/local/bin/bash test
Guido van Rossumec95c7b1998-08-04 17:59:56 +0000458
Anthony Baxter70e07962006-04-03 14:16:27 +0000459 Using GNU readline 2.2 seems to behave strangely, but I
460 think that's a problem with my readline 2.2 port. :-\
Guido van Rossumec95c7b1998-08-04 17:59:56 +0000461
Anthony Baxter70e07962006-04-03 14:16:27 +0000462 5) make SHELL=/usr/local/bin/bash install
Guido van Rossumb7f454d1997-12-02 19:44:31 +0000463
Anthony Baxter70e07962006-04-03 14:16:27 +0000464 If you get SIGSEGVs while running Python (I haven't yet, but
465 I've only run small programs and the test cases), you're
466 probably running out of stack; the default 32k could be a
467 little tight. To increase the stack size, edit the Makefile
468 to read: LDFLAGS = -N 48k
Guido van Rossum40d63581997-08-14 19:45:30 +0000469
Anthony Baxter70e07962006-04-03 14:16:27 +0000470BeOS: See Misc/BeOS-NOTES for notes about compiling/installing
471 Python on BeOS R3 or later. Note that only the PowerPC
472 platform is supported for R3; both PowerPC and x86 are
473 supported for R4.
Guido van Rossumec95c7b1998-08-04 17:59:56 +0000474
Michael W. Hudson33876f52002-07-31 09:55:25 +0000475Cray T3E: Mark Hadfield (m.hadfield@niwa.co.nz) writes:
Anthony Baxter70e07962006-04-03 14:16:27 +0000476 Python can be built satisfactorily on a Cray T3E but based on
477 my experience with the NIWA T3E (2002-05-22, version 2.2.1)
478 there are a few bugs and gotchas. For more information see a
479 thread on comp.lang.python in May 2002 entitled "Building
480 Python on Cray T3E".
Michael W. Hudson33876f52002-07-31 09:55:25 +0000481
482 1) Use Cray's cc and not gcc. The latter was reported not to
483 work by Konrad Hinsen. It may work now, but it may not.
484
485 2) To set sys.platform to something sensible, pass the
486 following environment variable to the configure script:
487
488 MACHDEP=unicosmk
489
Anthony Baxter70e07962006-04-03 14:16:27 +0000490 2) Run configure with option "--enable-unicode=ucs4".
Michael W. Hudson33876f52002-07-31 09:55:25 +0000491
Anthony Baxter70e07962006-04-03 14:16:27 +0000492 3) The Cray T3E does not support dynamic linking, so extension
493 modules have to be built by adding (or uncommenting) lines
494 in Modules/Setup. The minimum set of modules is
Michael W. Hudson33876f52002-07-31 09:55:25 +0000495
Anthony Baxter70e07962006-04-03 14:16:27 +0000496 posix, new, _sre, unicodedata
Michael W. Hudson33876f52002-07-31 09:55:25 +0000497
Anthony Baxter70e07962006-04-03 14:16:27 +0000498 On NIWA's vanilla T3E system the following have also been
499 included successfully:
Michael W. Hudson33876f52002-07-31 09:55:25 +0000500
Anthony Baxter70e07962006-04-03 14:16:27 +0000501 _codecs, _locale, _socket, _symtable, _testcapi, _weakref
502 array, binascii, cmath, cPickle, crypt, cStringIO, dbm
503 errno, fcntl, grp, math, md5, operator, parser, pcre, pwd
504 regex, rotor, select, struct, strop, syslog, termios
505 time, timing, xreadlines
Michael W. Hudson33876f52002-07-31 09:55:25 +0000506
Anthony Baxter70e07962006-04-03 14:16:27 +0000507 4) Once the python executable and library have been built, make
508 will execute setup.py, which will attempt to build remaining
509 extensions and link them dynamically. Each of these attempts
510 will fail but should not halt the make process. This is
511 normal.
Michael W. Hudson33876f52002-07-31 09:55:25 +0000512
Anthony Baxter70e07962006-04-03 14:16:27 +0000513 5) Running "make test" uses a lot of resources and causes
514 problems on our system. You might want to try running tests
515 singly or in small groups.
Guido van Rossum1bf0bf41997-08-20 23:50:51 +0000516
Anthony Baxter70e07962006-04-03 14:16:27 +0000517SGI: SGI's standard "make" utility (/bin/make or /usr/bin/make)
518 does not check whether a command actually changed the file it
519 is supposed to build. This means that whenever you say "make"
520 it will redo the link step. The remedy is to use SGI's much
521 smarter "smake" utility (/usr/sbin/smake), or GNU make. If
522 you set the first line of the Makefile to #!/usr/sbin/smake
523 smake will be invoked by make (likewise for GNU make).
Guido van Rossum0078aaf1997-08-21 03:05:11 +0000524
Anthony Baxter70e07962006-04-03 14:16:27 +0000525 WARNING: There are bugs in the optimizer of some versions of
526 SGI's compilers that can cause bus errors or other strange
527 behavior, especially on numerical operations. To avoid this,
528 try building with "make OPT=".
Fred Drake0b5fb2b2000-09-29 17:45:05 +0000529
Guido van Rossum64773801997-11-26 17:07:02 +0000530OS/2: If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
531 compiler installed, just change into the pc\os2vacpp directory
532 and type NMAKE. Threading and sockets are supported by default
533 in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
534
Fred Drake36ed5602000-10-06 01:58:48 +0000535Reliant UNIX: The thread support does not compile on Reliant UNIX, and
536 there is a (minor) problem in the configure script for that
537 platform as well. This should be resolved in time for a
538 future release.
Trent Mick635f6fb2000-08-23 21:33:05 +0000539
Barry Warsaw6a8557d2002-10-14 18:04:39 +0000540MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
Barry Warsaw6e753642002-10-14 18:15:35 +0000541 test_re and test_sre due to the small default stack size. If
542 you set the stack size to 2048 before doing a "make test" the
Georg Brandl667eb7c2007-03-06 18:47:31 +0000543 failure can be avoided. If you're using the tcsh or csh shells,
544 use "limit stacksize 2048" and for the bash shell (the default
545 as of OSX 10.3), use "ulimit -s 2048".
Barry Warsaw06557452001-12-14 20:47:12 +0000546
Jack Jansen6a77cf12001-12-06 21:49:02 +0000547 On naked Darwin you may want to add the configure option
Jack Jansen4c398fd2001-10-08 13:21:15 +0000548 "--disable-toolbox-glue" to disable the glue code for the Carbon
Jack Jansen6a77cf12001-12-06 21:49:02 +0000549 interface modules. The modules themselves are currently only built
550 if you add the --enable-framework option, see below.
Barry Warsaw06557452001-12-14 20:47:12 +0000551
552 On a clean OSX /usr/local does not exist. Do a
Jack Jansen61fec302002-01-04 15:59:57 +0000553 "sudo mkdir -m 775 /usr/local"
Jack Jansen84a01642002-08-04 21:19:55 +0000554 before you do a make install. It is probably not a good idea to
555 do "sudo make install" which installs everything as superuser,
556 as this may later cause problems when installing distutils-based
557 additions.
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000558
Jack Jansen84a01642002-08-04 21:19:55 +0000559 Some people have reported problems building Python after using "fink"
Anthony Baxter70e07962006-04-03 14:16:27 +0000560 to install additional unix software. Disabling fink (remove all
561 references to /sw from your .profile or .login) should solve this.
Barry Warsaw06557452001-12-14 20:47:12 +0000562
563 You may want to try the configure option "--enable-framework"
564 which installs Python as a framework. The location can be set
565 as argument to the --enable-framework option (default
Jack Jansen84a01642002-08-04 21:19:55 +0000566 /Library/Frameworks). A framework install is probably needed if you
567 want to use any Aqua-based GUI toolkit (whether Tkinter, wxPython,
568 Carbon, Cocoa or anything else).
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000569
Georg Brandlb0885b72007-12-09 08:59:45 +0000570 You may also want to try the configure option "--enable-universalsdk"
571 which builds Python as a universal binary with support for the
572 i386 and PPC architetures. This requires Xcode 2.1 or later to build.
Ronald Oussoren988117f2006-04-29 11:31:35 +0000573
Georg Brandl3fc792b2007-12-09 08:54:02 +0000574 See Mac/README for more information on framework and
Georg Brandlb0885b72007-12-09 08:59:45 +0000575 universal builds.
Fred Drakedabed752001-02-01 19:41:13 +0000576
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000577Cygwin: With recent (relative to the time of writing, 2001-12-19)
578 Cygwin installations, there are problems with the interaction
579 of dynamic linking and fork(). This manifests itself in build
580 failures during the execution of setup.py.
Tim Peters42fc7cc2001-04-04 18:35:19 +0000581
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000582 There are two workarounds that both enable Python (albeit
583 without threading support) to build and pass all tests on
584 NT/2000 (and most likely XP as well, though reports of testing
585 on XP would be appreciated).
Guido van Rossum16e809e2001-04-16 02:07:08 +0000586
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000587 The workarounds:
588
589 (a) the band-aid fix is to link the _socket module statically
590 rather than dynamically (which is the default).
591
592 To do this, run "./configure --with-threads=no" including any
593 other options you need (--prefix, etc.). Then in Modules/Setup
Walter Dörwald7dc65d62003-02-02 23:37:05 +0000594 uncomment the lines:
Tim Peters42fc7cc2001-04-04 18:35:19 +0000595
Michael W. Hudsonbe5ce182001-12-12 11:46:52 +0000596 #SSL=/usr/local/ssl
597 #_socket socketmodule.c \
Anthony Baxter70e07962006-04-03 14:16:27 +0000598 # -DUSE_SSL -I$(SSL)/include -I$(SSL)/include/openssl \
599 # -L$(SSL)/lib -lssl -lcrypto
Guido van Rossum16e809e2001-04-16 02:07:08 +0000600
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000601 and remove "local/" from the SSL variable. Finally, just run
602 "make"!
Tim Peters42fc7cc2001-04-04 18:35:19 +0000603
Michael W. Hudsonb6554642001-12-19 22:09:09 +0000604 (b) The "proper" fix is to rebase the Cygwin DLLs to prevent
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000605 base address conflicts. Details on how to do this can be
606 found in the following mail:
607
608 http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html
609
610 It is hoped that a version of this solution will be
Michael W. Hudsonb6554642001-12-19 22:09:09 +0000611 incorporated into the Cygwin distribution fairly soon.
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000612
613 Two additional problems:
614
615 (1) Threading support should still be disabled due to a known
616 bug in Cygwin pthreads that causes test_threadedtempfile to
617 hang.
618
Neal Norwitz4ebde092001-12-19 20:44:13 +0000619 (2) The _curses module does not build. This is a known
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000620 Cygwin ncurses problem that should be resolved the next time
621 that this package is released.
Guido van Rossum16e809e2001-04-16 02:07:08 +0000622
Michael W. Hudsonbe5ce182001-12-12 11:46:52 +0000623 On older versions of Cygwin, test_poll may hang and test_strftime
624 may fail.
Tim Peters42fc7cc2001-04-04 18:35:19 +0000625
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000626 The situation on 9X/Me is not accurately known at present.
627 Some time ago, there were reports that the following
628 regression tests failed:
Tim Peters42fc7cc2001-04-04 18:35:19 +0000629
630 test_pwd
631 test_select (hang)
632 test_socket
633
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000634 Due to the test_select hang on 9X/Me, one should run the
635 regression test using the following:
Tim Peters42fc7cc2001-04-04 18:35:19 +0000636
Michael W. Hudsonbe5ce182001-12-12 11:46:52 +0000637 make TESTOPTS='-l -x test_select' test
Tim Peters42fc7cc2001-04-04 18:35:19 +0000638
Michael W. Hudson1c4523f2001-12-19 19:49:58 +0000639 News regarding these platforms with more recent Cygwin
640 versions would be appreciated!
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000641
Georg Brandl69036212009-03-31 21:43:03 +0000642Windows: When executing Python scripts on the command line using file type
643 associations (i.e. starting "script.py" instead of "python script.py"),
644 redirects may not work unless you set a specific registry key. See
645 the Knowledge Base article <http://support.microsoft.com/kb/321788>.
Skip Montanaro56d83012003-01-04 04:05:51 +0000646
647
Skip Montanaro57454e52002-06-14 20:30:31 +0000648Configuring the bsddb and dbm modules
649-------------------------------------
650
Skip Montanaro56d83012003-01-04 04:05:51 +0000651Beginning with Python version 2.3, the PyBsddb package
652<http://pybsddb.sf.net/> was adopted into Python as the bsddb package,
653exposing a set of package-level functions which provide
Gregory P. Smith3adc4aa2006-04-13 19:19:01 +0000654backwards-compatible behavior. Only versions 3.3 through 4.4 of
Skip Montanaro56d83012003-01-04 04:05:51 +0000655Sleepycat's libraries provide the necessary API, so older versions
656aren't supported through this interface. The old bsddb module has
657been retained as bsddb185, though it is not built by default. Users
658wishing to use it will have to tweak Modules/Setup to build it. The
659dbm module will still be built against the Sleepycat libraries if
Gregory P. Smith3adc4aa2006-04-13 19:19:01 +0000660other preferred alternatives (ndbm, gdbm) are not found.
Guido van Rossum62d45c02002-12-02 15:49:13 +0000661
Anthony Baxter70e07962006-04-03 14:16:27 +0000662Building the sqlite3 module
663---------------------------
664
665To build the sqlite3 module, you'll need the sqlite3 or libsqlite3
666packages installed, including the header files. Many modern operating
667systems distribute the headers in a separate package to the library -
668often it will be the same name as the main package, but with a -dev or
669-devel suffix.
670
671The version of pysqlite2 that's including in Python needs sqlite3 3.0.8
672or later. setup.py attempts to check that it can find a correct version.
Skip Montanaro57454e52002-06-14 20:30:31 +0000673
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000674Configuring threads
675-------------------
676
Guido van Rossum7ac11532000-08-29 21:36:40 +0000677As of Python 2.0, threads are enabled by default. If you wish to
678compile without threads, or if your thread support is broken, pass the
679--with-threads=no switch to configure. Unfortunately, on some
680platforms, additional compiler and/or linker options are required for
681threads to work properly. Below is a table of those options,
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000682collected by Bill Janssen. We would love to automate this process
Guido van Rossum7ac11532000-08-29 21:36:40 +0000683more, but the information below is not enough to write a patch for the
684configure.in file, so manual intervention is required. If you patch
685the configure.in file and are confident that the patch works, please
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000686send in the patch. (Don't bother patching the configure script itself
Walter Dörwald7dc65d62003-02-02 23:37:05 +0000687-- it is regenerated each time the configure.in file changes.)
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000688
689Compiler switches for threads
690.............................
691
Martin v. Löwis1c24f9c2001-03-06 12:07:27 +0000692The definition of _REENTRANT should be configured automatically, if
693that does not work on your system, or if _REENTRANT is defined
694incorrectly, please report that as a bug.
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000695
Martin v. Löwis1c24f9c2001-03-06 12:07:27 +0000696 OS/Compiler/threads Switches for use with threads
697 (POSIX is draft 10, DCE is draft 4) compile & link
698
699 SunOS 5.{1-5}/{gcc,SunPro cc}/solaris -mt
700 SunOS 5.5/{gcc,SunPro cc}/POSIX (nothing)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000701 DEC OSF/1 3.x/cc/DCE -threads
Anthony Baxter70e07962006-04-03 14:16:27 +0000702 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000703 Digital UNIX 4.x/cc/DCE -threads
Anthony Baxter70e07962006-04-03 14:16:27 +0000704 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000705 Digital UNIX 4.x/cc/POSIX -pthread
Anthony Baxter70e07962006-04-03 14:16:27 +0000706 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000707 AIX 4.1.4/cc_r/d7 (nothing)
Anthony Baxter70e07962006-04-03 14:16:27 +0000708 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000709 AIX 4.1.4/cc_r4/DCE (nothing)
Anthony Baxter70e07962006-04-03 14:16:27 +0000710 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000711 IRIX 6.2/cc/POSIX (nothing)
Anthony Baxter70e07962006-04-03 14:16:27 +0000712 (robertl@cwi.nl)
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000713
714
715Linker (ld) libraries and flags for threads
716...........................................
717
718 OS/threads Libraries/switches for use with threads
719
720 SunOS 5.{1-5}/solaris -lthread
721 SunOS 5.5/POSIX -lpthread
Guido van Rossum16e809e2001-04-16 02:07:08 +0000722 DEC OSF/1 3.x/DCE -lpthreads -lmach -lc_r -lc
Anthony Baxter70e07962006-04-03 14:16:27 +0000723 (butenhof@zko.dec.com)
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000724 Digital UNIX 4.x/DCE -lpthreads -lpthread -lmach -lexc -lc
Anthony Baxter70e07962006-04-03 14:16:27 +0000725 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000726 Digital UNIX 4.x/POSIX -lpthread -lmach -lexc -lc
Anthony Baxter70e07962006-04-03 14:16:27 +0000727 (butenhof@zko.dec.com)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000728 AIX 4.1.4/{draft7,DCE} (nothing)
Anthony Baxter70e07962006-04-03 14:16:27 +0000729 (buhrt@iquest.net)
Guido van Rossum16e809e2001-04-16 02:07:08 +0000730 IRIX 6.2/POSIX -lpthread
Anthony Baxter70e07962006-04-03 14:16:27 +0000731 (jph@emilia.engr.sgi.com)
Guido van Rossumdc8a3cb1998-05-12 15:29:18 +0000732
733
Martin v. Löwis1142de32002-03-29 16:28:31 +0000734Building a shared libpython
735---------------------------
736
737Starting with Python 2.3, the majority of the interpreter can be built
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000738into a shared library, which can then be used by the interpreter
Martin v. Löwis1142de32002-03-29 16:28:31 +0000739executable, and by applications embedding Python. To enable this feature,
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +0000740configure with --enable-shared.
Martin v. Löwis65069672002-08-03 21:38:27 +0000741
Fred Drake55512dc2003-07-21 16:01:39 +0000742If you enable this feature, the same object files will be used to create
743a static library. In particular, the static library will contain object
744files using position-independent code (PIC) on platforms where PIC flags
745are needed for the shared library.
Martin v. Löwis1142de32002-03-29 16:28:31 +0000746
747
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000748Configuring additional built-in modules
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000749---------------------------------------
Guido van Rossum19e0c261995-01-17 16:36:34 +0000750
Andrew M. Kuchlingebe30452001-02-27 03:24:24 +0000751Starting with Python 2.1, the setup.py script at the top of the source
752distribution attempts to detect which modules can be built and
753automatically compiles them. Autodetection doesn't always work, so
Guido van Rossum59b0b602002-02-08 22:22:35 +0000754you can still customize the configuration by editing the Modules/Setup
755file; but this should be considered a last resort. The rest of this
756section only applies if you decide to edit the Modules/Setup file.
757You also need this to enable static linking of certain modules (which
758is needed to enable profiling on some systems).
759
Andrew M. Kuchlingebe30452001-02-27 03:24:24 +0000760This file is initially copied from Setup.dist by the configure script;
761if it does not exist yet, create it by copying Modules/Setup.dist
762yourself (configure will never overwrite it). Never edit Setup.dist
763-- always edit Setup or Setup.local (see below). Read the comments in
764the file for information on what kind of edits are allowed. When you
765have edited Setup in the Modules directory, the interpreter will
Guido van Rossumef67ded2001-10-05 17:04:42 +0000766automatically be rebuilt the next time you run make (in the toplevel
767directory).
Guido van Rossum627b2d71993-12-24 10:39:16 +0000768
Andrew M. Kuchlingebe30452001-02-27 03:24:24 +0000769Many useful modules can be built on any Unix system, but some optional
770modules can't be reliably autodetected. Often the quickest way to
771determine whether a particular module works or not is to see if it
772will build: enable it in Setup, then if you get compilation or link
Fred Drake6caae142000-10-25 17:51:02 +0000773errors, disable it -- you're either missing support or need to adjust
774the compilation and linking parameters for that module.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000775
776On SGI IRIX, there are modules that interface to many SGI specific
Andrew M. Kuchlingebe30452001-02-27 03:24:24 +0000777system libraries, e.g. the GL library and the audio hardware. These
778modules will not be built by the setup.py script.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000779
Guido van Rossum4462e931997-01-22 21:00:32 +0000780In addition to the file Setup, you can also edit the file Setup.local.
781(the makesetup script processes both). You may find it more
782convenient to edit Setup.local and leave Setup alone. Then, when
783installing a new Python version, you can copy your old Setup.local
784file.
785
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000786
787Setting the optimization/debugging options
788------------------------------------------
789
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000790If you want or need to change the optimization/debugging options for
791the C compiler, assign to the OPT variable on the toplevel make
792command; e.g. "make OPT=-g" will build a debugging version of Python
793on most platforms. The default is OPT=-O; a value for OPT in the
794environment when the configure script is run overrides this default
795(likewise for CC; and the initial value for LIBS is used as the base
796set of libraries to link with).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000797
Fred Drake6caae142000-10-25 17:51:02 +0000798When compiling with GCC, the default value of OPT will also include
799the -Wall and -Wstrict-prototypes options.
800
801Additional debugging code to help debug memory management problems can
802be enabled by using the --with-pydebug option to the configure script.
803
Brett Cannon08cd5982005-04-24 22:26:38 +0000804For flags that change binary compatibility, use the EXTRA_CFLAGS
805variable.
806
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000807
Guido van Rossuma68ca352001-10-04 17:00:07 +0000808Profiling
809---------
810
811If you want C profiling turned on, the easiest way is to run configure
812with the CC environment variable to the necessary compiler
813invocation. For example, on Linux, this works for profiling using
814gprof(1):
815
816 CC="gcc -pg" ./configure
817
818Note that on Linux, gprof apparently does not work for shared
819libraries. The Makefile/Setup mechanism can be used to compile and
Walter Dörwald7dc65d62003-02-02 23:37:05 +0000820link most extension modules statically.
Guido van Rossuma68ca352001-10-04 17:00:07 +0000821
822
Georg Brandl405b5f32008-05-18 11:46:51 +0000823Coverage checking
824-----------------
825
826For C coverage checking using gcov, run "make coverage". This will
827build a Python binary with profiling activated, and a ".gcno" and
828".gcda" file for every source file compiled with that option. With
829the built binary, now run the code whose coverage you want to check.
830Then, you can see coverage statistics for each individual source file
831by running gcov, e.g.
832
833 gcov -o Modules zlibmodule
834
835This will create a "zlibmodule.c.gcov" file in the current directory
836containing coverage info for that source file.
837
838This works only for source files statically compiled into the
839executable; use the Makefile/Setup mechanism to compile and link
840extension modules you want to coverage-check statically.
841
842
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000843Testing
844-------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000845
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000846To test the interpreter, type "make test" in the top-level directory.
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000847This runs the test set twice (once with no compiled files, once with
848the compiled files left by the previous test run). The test set
849produces some output. You can generally ignore the messages about
Guido van Rossum59b0b602002-02-08 22:22:35 +0000850skipped tests due to optional features which can't be imported.
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000851If a message is printed about a failed test or a traceback or core
852dump is produced, something is wrong. On some Linux systems (those
Guido van Rossum24df6841997-12-30 04:32:30 +0000853that are not yet using glibc 6), test_strftime fails due to a
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000854non-standard implementation of strftime() in the C library. Please
855ignore this, or upgrade to glibc version 6.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000856
Benjamin Petersona18736b2009-02-24 02:45:35 +0000857By default, tests are prevented from overusing resources like disk space and
858memory. To enable these tests, run "make testall".
859
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000860IMPORTANT: If the tests fail and you decide to mail a bug report,
861*don't* include the output of "make test". It is useless. Run the
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000862failing test manually, as follows:
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000863
Benjamin Petersona18736b2009-02-24 02:45:35 +0000864 ./python Lib/test/regrtest.py -v test_whatever
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000865
Andrew M. Kuchling83d042d2002-03-21 23:52:20 +0000866(substituting the top of the source tree for '.' if you built in a
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000867different directory). This runs the test in verbose mode.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000868
869
870Installing
871----------
872
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000873To install the Python binary, library modules, shared library modules
874(see below), include files, configuration files, and the manual page,
Guido van Rossum64773801997-11-26 17:07:02 +0000875just type
876
Anthony Baxter70e07962006-04-03 14:16:27 +0000877 make install
Guido van Rossum64773801997-11-26 17:07:02 +0000878
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000879This will install all platform-independent files in subdirectories of
880the directory given with the --prefix option to configure or to the
881`prefix' Make variable (default /usr/local). All binary and other
882platform-specific files will be installed in subdirectories if the
883directory given by --exec-prefix or the `exec_prefix' Make variable
884(defaults to the --prefix directory) is given.
Guido van Rossum64773801997-11-26 17:07:02 +0000885
Martin v. Löwis3b8ee082003-05-11 20:25:35 +0000886If DESTDIR is set, it will be taken as the root directory of the
887installation, and files will be installed into $(DESTDIR)$(prefix),
888$(DESTDIR)$(exec_prefix), etc.
889
Guido van Rossum64773801997-11-26 17:07:02 +0000890All subdirectories created will have Python's version number in their
891name, e.g. the library modules are installed in
Guido van Rossum67345eb2001-01-18 14:51:12 +0000892"/usr/local/lib/python<version>/" by default, where <version> is the
893<major>.<minor> release number (e.g. "2.1"). The Python binary is
894installed as "python<version>" and a hard link named "python" is
895created. The only file not installed with a version number in its
896name is the manual page, installed as "/usr/local/man/man1/python.1"
897by default.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000898
Skip Montanaro86d4e7a2008-03-05 16:41:09 +0000899If you want to install multiple versions of Python see the section below
900entitled "Installing multiple versions".
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000901
902The only thing you may have to install manually is the Python mode for
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000903Emacs found in Misc/python-mode.el. (But then again, more recent
904versions of Emacs may already have it.) Follow the instructions that
905came with Emacs for installation of site-specific files.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000906
Jack Jansena39ef862001-08-19 21:17:03 +0000907On Mac OS X, if you have configured Python with --enable-framework, you
908should use "make frameworkinstall" to do the installation. Note that this
909installs the Python executable in a place that is not normally on your
910PATH, you may want to set up a symlink in /usr/local/bin.
911
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000912
Skip Montanaro86d4e7a2008-03-05 16:41:09 +0000913Installing multiple versions
914----------------------------
915
916On Unix and Mac systems if you intend to install multiple versions of Python
917using the same installation prefix (--prefix argument to the configure
918script) you must take care that your primary python executable is not
Ezio Melotti41c75702009-07-04 01:18:08 +0000919overwritten by the installation of a different version. All files and
Skip Montanaro86d4e7a2008-03-05 16:41:09 +0000920directories installed using "make altinstall" contain the major and minor
921version and can thus live side-by-side. "make install" also creates
922${prefix}/bin/python which refers to ${prefix}/bin/pythonX.Y. If you intend
923to install multiple versions using the same prefix you must decide which
924version (if any) is your "primary" version. Install that version using
925"make install". Install all other versions using "make altinstall".
926
927For example, if you want to install Python 2.5, 2.6 and 3.0 with 2.6 being
928the primary version, you would execute "make install" in your 2.6 build
929directory and "make altinstall" in the others.
930
931
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000932Configuration options and variables
933-----------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000934
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000935Some special cases are handled by passing options to the configure
936script.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000937
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000938WARNING: if you rerun the configure script with different options, you
939must run "make clean" before rebuilding. Exceptions to this rule:
940after changing --prefix or --exec-prefix, all you need to do is remove
Guido van Rossumb06df271997-08-05 21:50:20 +0000941Modules/getpath.o.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000942
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000943--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
Anthony Baxter70e07962006-04-03 14:16:27 +0000944 it finds it. If you don't want this, or if this compiler is
945 installed but broken on your platform, pass the option
946 --without-gcc. You can also pass "CC=cc" (or whatever the
947 name of the proper C compiler is) in the environment, but the
948 advantage of using --without-gcc is that this option is
949 remembered by the config.status script for its --recheck
950 option.
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000951
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000952--prefix, --exec-prefix: If you want to install the binaries and the
Anthony Baxter70e07962006-04-03 14:16:27 +0000953 Python library somewhere else than in /usr/local/{bin,lib},
954 you can pass the option --prefix=DIRECTORY; the interpreter
955 binary will be installed as DIRECTORY/bin/python and the
956 library files as DIRECTORY/lib/python/*. If you pass
957 --exec-prefix=DIRECTORY (as well) this overrides the
958 installation prefix for architecture-dependent files (like the
959 interpreter binary). Note that --prefix=DIRECTORY also
960 affects the default module search path (sys.path), when
961 Modules/config.c is compiled. Passing make the option
962 prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
963 prefix set at configuration time; this may be more convenient
964 than re-running the configure script if you change your mind
965 about the install prefix.
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000966
Guido van Rossum59b0b602002-02-08 22:22:35 +0000967--with-readline: This option is no longer supported. GNU
Anthony Baxter70e07962006-04-03 14:16:27 +0000968 readline is automatically enabled by setup.py when present.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000969
Guido van Rossum7ac11532000-08-29 21:36:40 +0000970--with-threads: On most Unix systems, you can now use multiple
Anthony Baxter70e07962006-04-03 14:16:27 +0000971 threads, and support for this is enabled by default. To
972 disable this, pass --with-threads=no. If the library required
973 for threads lives in a peculiar place, you can use
974 --with-thread=DIRECTORY. IMPORTANT: run "make clean" after
975 changing (either enabling or disabling) this option, or you
976 will get link errors! Note: for DEC Unix use
977 --with-dec-threads instead.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000978
979--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
Anthony Baxter70e07962006-04-03 14:16:27 +0000980 supported by the "dl" library by Jack Jansen, which is
981 ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
982 This is enabled (after you've ftp'ed and compiled the dl
983 library) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
984 is the absolute pathname of the dl library. (Don't bother on
985 IRIX 5, it already has dynamic linking using SunOS style
986 shared libraries.) THIS OPTION IS UNSUPPORTED.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000987
Guido van Rossum4f40c2d2000-09-05 16:46:22 +0000988--with-dl-dld: Dynamic loading of modules is rumored to be supported
Anthony Baxter70e07962006-04-03 14:16:27 +0000989 on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
990 Symmetry (Dynix), and Atari ST. This is done using a
991 combination of the GNU dynamic loading package
992 (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
993 emulation of the SGI dl library mentioned above (the emulation
994 can be found at
995 ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z). To
996 enable this, ftp and compile both libraries, then call
997 configure, passing it the option
998 --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
999 the absolute pathname of the dl emulation library and
1000 DLD_DIRECTORY is the absolute pathname of the GNU dld library.
1001 (Don't bother on SunOS 4 or 5, they already have dynamic
1002 linking using shared libraries.) THIS OPTION IS UNSUPPORTED.
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001003
1004--with-libm, --with-libc: It is possible to specify alternative
Anthony Baxter70e07962006-04-03 14:16:27 +00001005 versions for the Math library (default -lm) and the C library
1006 (default the empty string) using the options
1007 --with-libm=STRING and --with-libc=STRING, respectively. For
1008 example, if your system requires that you pass -lc_s to the C
1009 compiler to use the shared C library, you can pass
1010 --with-libc=-lc_s. These libraries are passed after all other
1011 libraries, the C library last.
Guido van Rossum16e809e2001-04-16 02:07:08 +00001012
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001013--with-libs='libs': Add 'libs' to the LIBS that the python interpreter
Anthony Baxter70e07962006-04-03 14:16:27 +00001014 is linked against.
Guido van Rossumd02ba451996-07-31 17:36:01 +00001015
Martin v. Löwis0f48d982006-04-14 14:34:26 +00001016--with-cxx-main=<compiler>: If you plan to use C++ extension modules,
1017 then -- on some platforms -- you need to compile python's main()
1018 function with the C++ compiler. With this option, make will use
1019 <compiler> to compile main() *and* to link the python executable.
1020 It is likely that the resulting executable depends on the C++
1021 runtime library of <compiler>. (The default is --without-cxx-main.)
1022
1023 There are platforms that do not require you to build Python
1024 with a C++ compiler in order to use C++ extension modules.
1025 E.g., x86 Linux with ELF shared binaries and GCC 3.x, 4.x is such
1026 a platform. We recommend that you configure Python
1027 --without-cxx-main on those platforms because a mismatch
1028 between the C++ compiler version used to build Python and to
1029 build a C++ extension module is likely to cause a crash at
1030 runtime.
1031
1032 The Python installation also stores the variable CXX that
1033 determines, e.g., the C++ compiler distutils calls by default
1034 to build C++ extensions. If you set CXX on the configure command
1035 line to any string of non-zero length, then configure won't
1036 change CXX. If you do not preset CXX but pass
1037 --with-cxx-main=<compiler>, then configure sets CXX=<compiler>.
1038 In all other cases, configure looks for a C++ compiler by
1039 some common names (c++, g++, gcc, CC, cxx, cc++, cl) and sets
1040 CXX to the first compiler it finds. If it does not find any
1041 C++ compiler, then it sets CXX="".
1042
1043 Similarly, if you want to change the command used to link the
1044 python executable, then set LINKCC on the configure command line.
Martin v. Löwis2df66942000-12-13 14:14:32 +00001045
1046
Fred Drake6caae142000-10-25 17:51:02 +00001047--with-pydebug: Enable additional debugging code to help track down
Anthony Baxter70e07962006-04-03 14:16:27 +00001048 memory management problems. This allows printing a list of all
1049 live objects when the interpreter terminates.
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +00001050
Jack Jansen7b8c7542002-04-14 20:12:41 +00001051--with(out)-universal-newlines: enable reading of text files with
Anthony Baxter70e07962006-04-03 14:16:27 +00001052 foreign newline convention (default: enabled). In other words,
1053 any of \r, \n or \r\n is acceptable as end-of-line character.
1054 If enabled import and execfile will automatically accept any newline
1055 in files. Python code can open a file with open(file, 'U') to
1056 read it in universal newline mode. THIS OPTION IS UNSUPPORTED.
Fred Drake6caae142000-10-25 17:51:02 +00001057
Martin v. Löwisf30d60e2004-06-08 08:17:44 +00001058--with-tsc: Profile using the Pentium timestamping counter (TSC).
Guido van Rossum76be6ed1995-01-02 18:33:54 +00001059
Martin v. Löwis9176fc12006-04-11 11:12:43 +00001060--with-system-ffi: Build the _ctypes extension module using an ffi
Georg Brandlb0885b72007-12-09 08:59:45 +00001061 library installed on the system.
Martin v. Löwis9176fc12006-04-11 11:12:43 +00001062
Matthias Klose10cbe482009-04-29 17:18:19 +00001063--with-dbmliborder=db1:db2:...: Specify the order that backends for the
1064 dbm extension are checked. Valid value is a colon separated string
1065 with the backend names `ndbm', `gdbm' and `bdb'.
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +00001066
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001067Building for multiple architectures (using the VPATH feature)
1068-------------------------------------------------------------
1069
1070If your file system is shared between multiple architectures, it
1071usually is not necessary to make copies of the sources for each
1072architecture you want to support. If the make program supports the
1073VPATH feature, you can create an empty build directory for each
1074architecture, and in each directory run the configure script (on the
1075appropriate machine with the appropriate options). This creates the
1076necessary subdirectories and the Makefiles therein. The Makefiles
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001077contain a line VPATH=... which points to a directory containing the
Guido van Rossumd0fe8451996-08-26 03:02:37 +00001078actual sources. (On SGI systems, use "smake -J1" instead of "make" if
1079you use VPATH -- don't try gnumake.)
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001080
1081For example, the following is all you need to build a minimal Python
1082in /usr/tmp/python (assuming ~guido/src/python is the toplevel
1083directory and you want to build in /usr/tmp/python):
1084
Anthony Baxter70e07962006-04-03 14:16:27 +00001085 $ mkdir /usr/tmp/python
1086 $ cd /usr/tmp/python
1087 $ ~guido/src/python/configure
1088 [...]
1089 $ make
1090 [...]
1091 $
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001092
Neil Schemenauer73f8ab22001-01-26 22:18:55 +00001093Note that configure copies the original Setup file to the build
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001094directory if it finds no Setup file there. This means that you can
1095edit the Setup file for each architecture independently. For this
1096reason, subsequent changes to the original Setup file are not tracked
1097automatically, as they might overwrite local changes. To force a copy
1098of a changed original Setup file, delete the target Setup file. (The
1099makesetup script supports multiple input files, so if you want to be
1100fancy you can change the rules to create an empty Setup.local if it
1101doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
1102however this assumes that you only need to add modules.)
1103
Christian Heimes0a0e5832007-12-13 19:23:16 +00001104Also note that you can't use a workspace for VPATH and non VPATH builds. The
1105object files left behind by one version confuses the other.
1106
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001107
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001108Building on non-UNIX systems
1109----------------------------
1110
Martin v. Löwis2eba0d62004-12-24 08:28:28 +00001111For Windows (2000/NT/ME/98/95), assuming you have MS VC++ 7.1, the
Tim Peters03444242000-09-19 00:38:35 +00001112project files are in PCbuild, the workspace is pcbuild.dsw. See
1113PCbuild\readme.txt for detailed instructions.
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +00001114
Martin v. Löwis2eba0d62004-12-24 08:28:28 +00001115For other non-Unix Windows compilers, in particular MS VC++ 6.0 and
Guido van Rossum31ae2071999-04-12 14:47:30 +00001116for OS/2, enter the directory "PC" and read the file "readme.txt".
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001117
1118For the Mac, a separate source distribution will be made available,
1119for use with the CodeWarrior compiler. If you are interested in Mac
1120development, join the PythonMac Special Interest Group
1121(http://www.python.org/sigs/pythonmac-sig/, or send email to
1122pythonmac-sig-request@python.org).
1123
1124Of course, there are also binary distributions available for these
Guido van Rossum67345eb2001-01-18 14:51:12 +00001125platforms -- see http://www.python.org/.
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001126
1127To port Python to a new non-UNIX system, you will have to fake the
1128effect of running the configure script manually (for Mac and PC, this
1129has already been done for you). A good start is to copy the file
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001130pyconfig.h.in to pyconfig.h and edit the latter to reflect the actual
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001131configuration of your system. Most symbols must simply be defined as
11321 only if the corresponding feature is present and can be left alone
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001133otherwise; however the *_t type symbols must be defined as some
1134variant of int if they need to be defined at all.
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001135
Barry Warsaw06557452001-12-14 20:47:12 +00001136For all platforms, it's important that the build arrange to define the
1137preprocessor symbol NDEBUG on the compiler command line in a release
1138build of Python (else assert() calls remain in the code, hurting
1139release-build performance). The Unix, Windows and Mac builds already
1140do this.
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001141
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001142
1143Miscellaneous issues
1144====================
1145
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001146Emacs mode
1147----------
1148
Guido van Rossumc0be2f51997-10-08 05:05:28 +00001149There's an excellent Emacs editing mode for Python code; see the file
1150Misc/python-mode.el. Originally written by the famous Tim Peters, it
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001151is now maintained by the equally famous Barry Warsaw (it's no
Guido van Rossum67345eb2001-01-18 14:51:12 +00001152coincidence that they now both work on the same team). The latest
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001153version, along with various other contributed Python-related Emacs
Georg Brandl4492a982009-08-24 17:12:30 +00001154goodies, is online at http://www.python.org/emacs/python-mode/. And
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001155if you are planning to edit the Python C code, please pick up the
Georg Brandl4492a982009-08-24 17:12:30 +00001156latest version of CC Mode http://www.python.org/emacs/cc-mode/; it
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001157contains a "python" style used throughout most of the Python C source
1158files. (Newer versions of Emacs or XEmacs may already come with the
1159latest version of python-mode.)
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001160
1161
Guido van Rossum59b0b602002-02-08 22:22:35 +00001162Tkinter
1163-------
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001164
Guido van Rossum59b0b602002-02-08 22:22:35 +00001165The setup.py script automatically configures this when it detects a
1166usable Tcl/Tk installation. This requires Tcl/Tk version 8.0 or
Fred Drake8179a9d2000-09-28 23:28:30 +00001167higher.
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001168
Guido van Rossum973e4dc2000-07-01 00:34:39 +00001169For more Tkinter information, see the Tkinter Resource page:
1170http://www.python.org/topics/tkinter/
Guido van Rossumc0be2f51997-10-08 05:05:28 +00001171
Michael W. Hudson71dcc3e2005-02-22 15:33:26 +00001172There are demos in the Demo/tkinter directory.
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001173
1174Note that there's a Python module called "Tkinter" (capital T) which
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001175lives in Lib/lib-tk/Tkinter.py, and a C module called "_tkinter"
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001176(lower case t and leading underscore) which lives in
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001177Modules/_tkinter.c. Demos and normal Tk applications import only the
Guido van Rossum59b0b602002-02-08 22:22:35 +00001178Python Tkinter module -- only the latter imports the C _tkinter
1179module. In order to find the C _tkinter module, it must be compiled
1180and linked into the Python interpreter -- the setup.py script does
1181this. In order to find the Python Tkinter module, sys.path must be
1182set correctly -- normal installation takes care of this.
Guido van Rossum84c8c7f1995-08-28 02:44:24 +00001183
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001184
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001185Distribution structure
1186----------------------
1187
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001188Most subdirectories have their own README files. Most files have
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001189comments.
1190
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001191Demo/ Demonstration scripts, modules and programs
Georg Brandlc207c712008-02-09 21:38:54 +00001192Doc/ Documentation sources (reStructuredText)
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001193Grammar/ Input for the parser generator
1194Include/ Public header files
Anthony Baxter70e07962006-04-03 14:16:27 +00001195LICENSE Licensing information
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001196Lib/ Python library modules
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001197Mac/ Macintosh specific resources
Neil Schemenauer3f52da52001-01-24 17:49:59 +00001198Makefile.pre.in Source from which config.status creates the Makefile.pre
Guido van Rossumc0be2f51997-10-08 05:05:28 +00001199Misc/ Miscellaneous useful files
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001200Modules/ Implementation of most built-in modules
1201Objects/ Implementation of most built-in object types
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001202PC/ Files specific to PC ports (DOS, Windows, OS/2)
Anthony Baxter70e07962006-04-03 14:16:27 +00001203PCbuild/ Build directory for Microsoft Visual C++
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001204Parser/ The parser and tokenizer and their input handling
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001205Python/ The byte-compiler and interpreter
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001206README The file you're reading now
Neal Norwitzf8519c42007-05-20 18:43:00 +00001207RISCOS/ Files specific to RISC OS port
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001208Tools/ Some useful programs written in Python
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001209pyconfig.h.in Source from which pyconfig.h is created (GNU autoheader output)
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001210configure Configuration shell script (GNU autoconf output)
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001211configure.in Configuration specification (input for GNU autoconf)
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001212install-sh Shell script used to install files
Anthony Baxter70e07962006-04-03 14:16:27 +00001213setup.py Python script used to build extension modules
Guido van Rossum91cb9d21995-04-10 11:47:38 +00001214
1215The following files will (may) be created in the toplevel directory by
1216the configuration and build processes:
1217
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001218Makefile Build rules
Neil Schemenauer3f52da52001-01-24 17:49:59 +00001219Makefile.pre Build rules before running Modules/makesetup
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001220buildno Keeps track of the build number
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001221config.cache Cache of configuration variables
Michael W. Hudsonbe6e0f42002-06-23 16:29:36 +00001222pyconfig.h Configuration header
Guido van Rossumc0be2f51997-10-08 05:05:28 +00001223config.log Log from last configure run
Guido van Rossum4f40c2d2000-09-05 16:46:22 +00001224config.status Status from last run of the configure script
Anthony Baxter70e07962006-04-03 14:16:27 +00001225getbuildinfo.o Object file from Modules/getbuildinfo.c
1226libpython<version>.a The library archive
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001227python The executable interpreter
Neal Norwitzf8519c42007-05-20 18:43:00 +00001228reflog.txt Output from running the regression suite with the -R flag
Guido van Rossum6d9cc801996-08-01 17:31:22 +00001229tags, TAGS Tags files for vi and Emacs
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001230
1231
Guido van Rossumc07d5fa2000-09-01 22:50:02 +00001232That's all, folks!
1233------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +00001234
1235
Guido van Rossum67345eb2001-01-18 14:51:12 +00001236--Guido van Rossum (home page: http://www.python.org/~guido/)