1
This is Python version 2.7.11
2
=============================
4
Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
5
2012, 2013, 2014, 2015 Python Software Foundation. All rights reserved.
7
Copyright (c) 2000 BeOpen.com.
10
Copyright (c) 1995-2001 Corporation for National Research Initiatives.
13
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
20
See the file "LICENSE" for information on the history of this
21
software, terms & conditions for usage, and a DISCLAIMER OF ALL
24
This Python distribution contains no GNU General Public Licensed
25
(GPLed) code so it may be used in proprietary projects just like prior
26
Python distributions. There are interfaces to some GNU code but these
27
are entirely optional.
29
All trademarks referenced herein are property of their respective
33
What's new in this release?
34
---------------------------
36
See the file "Misc/NEWS".
39
If you don't read instructions
40
------------------------------
42
Congratulations on getting this far. :-)
44
To start building right away (on UNIX): type "./configure" in the
45
current directory and when it finishes, type "make". This creates an
46
executable "./python"; to install in /usr/local, first do "su root"
47
and then "make install".
49
The section `Build instructions' below is still recommended reading.
52
What is Python anyway?
53
----------------------
55
Python is an interpreted, interactive object-oriented programming
56
language suitable (amongst other uses) for distributed application
57
development, scripting, numeric computing and system testing. Python
58
is often compared to Tcl, Perl, Java, JavaScript, Visual Basic or
59
Scheme. To find out more about what Python can do for you, point your
60
browser to http://www.python.org/.
63
How do I learn Python?
64
----------------------
66
The official tutorial is still a good place to start; see
67
http://docs.python.org/ for online and downloadable versions, as well
68
as a list of other introductions, and reference documentation.
70
There's a quickly growing set of books on Python. See
71
http://wiki.python.org/moin/PythonBooks for a list.
77
All documentation is provided online in a variety of formats. In
78
order of importance for new users: Tutorial, Library Reference,
79
Language Reference, Extending & Embedding, and the Python/C API. The
80
Library Reference is especially of immense value since much of
81
Python's power is described there, including the built-in data types
84
All documentation is also available online at the Python web site
85
(http://docs.python.org/, see below). It is available online for occasional
86
reference, or can be downloaded in many formats for faster access. The
87
documentation is downloadable in HTML, PostScript, PDF, LaTeX, and
88
reStructuredText (2.6+) formats; the LaTeX and reStructuredText versions are
89
primarily for documentation authors, translators, and people with special
90
formatting requirements.
92
If you would like to contribute to the development of Python, relevant
93
documentation is available at:
95
http://docs.python.org/devguide/
97
For information about building Python's documentation, refer to Doc/README.txt.
103
New Python releases and related technologies are published at
104
http://www.python.org/. Come visit us!
107
Newsgroups and Mailing Lists
108
----------------------------
110
Read comp.lang.python, a high-volume discussion newsgroup about
111
Python, or comp.lang.python.announce, a low-volume moderated newsgroup
112
for Python-related announcements. These are also accessible as
113
mailing lists: see http://www.python.org/community/lists/ for an
114
overview of these and many other Python-related mailing lists.
116
Archives are accessible via the Google Groups Usenet archive; see
117
http://groups.google.com/. The mailing lists are also archived, see
118
http://www.python.org/community/lists/ for details.
124
To report or search for bugs, please use the Python Bug
125
Tracker at http://bugs.python.org/.
128
Patches and contributions
129
-------------------------
131
To submit a patch or other contribution, please use the Python Patch
132
Manager at http://bugs.python.org/. Guidelines
133
for patch submission may be found at http://www.python.org/dev/patches/.
135
If you have a proposal to change Python, you may want to send an email to the
136
comp.lang.python or python-ideas mailing lists for inital feedback. A Python
137
Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
138
current PEPs, as well as guidelines for submitting a new PEP, are listed at
139
http://www.python.org/dev/peps/.
145
For help, if you can't find it in the manuals or on the web site, it's
146
best to post to the comp.lang.python or the Python mailing list (see
147
above). If you specifically don't want to involve the newsgroup or
148
mailing list, send questions to help@python.org (a group of volunteers
149
who answer questions as they can). The newsgroup is the most
150
efficient way to ask public questions.
156
Before you can build Python, you must first configure it.
157
Fortunately, the configuration and build process has been automated
158
for Unix and Linux installations, so all you usually have to do is
159
type a few commands and sit back. There are some platforms where
160
things are not quite as smooth; see the platform specific notes below.
161
If you want to build for multiple platforms sharing the same source
162
tree, see the section on VPATH below.
164
Start by running the script "./configure", which determines your
165
system configuration and creates the Makefile. (It takes a minute or
166
two -- please be patient!) You may want to pass options to the
167
configure script -- see the section below on configuration options and
168
variables. When it's done, you are ready to run make.
170
To build Python, you normally type "make" in the toplevel directory.
171
If you have changed the configuration, the Makefile may have to be
172
rebuilt. In this case, you may have to run make again to correctly
173
build your desired target. The interpreter executable is built in the
176
If you need an optimized version of Python, you type "make profile-opt"
177
in the top level directory. This will rebuild the interpreter executable
178
using Profile Guided Optimization (PGO). For more details, see the
181
Once you have built a Python interpreter, see the subsections below on
182
testing and installation. If you run into trouble, see the next
185
Previous versions of Python used a manual configuration process that
186
involved editing the file Modules/Setup. While this file still exists
187
and manual configuration is still supported, it is rarely needed any
188
more: almost all modules are automatically built as appropriate under
189
guidance of the setup.py script, which is run by Make after the
190
interpreter has been built.
193
Profile Guided Optimization
194
---------------------------
196
PGO takes advantage of recent versions of the GCC or Clang compilers.
197
If ran, the "profile-opt" rule will do several steps.
199
First, the entire Python directory is cleaned of temporary files that
200
may resulted in a previous compilation.
202
Then, an instrumented version of the interpreter is built, using suitable
203
compiler flags for each flavour. Note that this is just an intermediary
204
step and the binary resulted after this step is not good for real life
205
workloads, as it has profiling instructions embedded inside.
207
After this instrumented version of the interpreter is built, the Makefile
208
will automatically run a training workload. This is necessary in order to
209
profile the interpreter execution. Note also that any output, both stdout
210
and stderr, that may appear at this step is supressed.
212
Finally, the last step is to rebuild the interpreter, using the information
213
collected in the previous one. The end result will be a the Python binary
214
that is optimized and suitable for distribution or production installation.
220
See also the platform specific notes in the next section.
222
If you run into other trouble, see the FAQ
223
(http://www.python.org/doc/faq/) for hints on what can go wrong, and
226
If you rerun the configure script with different options, remove all
227
object files by running "make clean" before rebuilding. Believe it or
228
not, "make clean" sometimes helps to clean up other inexplicable
229
problems as well. Try it before sending in a bug report!
231
If the configure script fails or doesn't seem to find things that
232
should be there, inspect the config.log file.
234
If you get a warning for every file about the -Olimit option being no
235
longer supported, you can ignore it. There's no foolproof way to know
236
whether this option is needed; all we can do is test whether it is
237
accepted without error. On some systems, e.g. older SGI compilers, it
238
is essential for performance (specifically when compiling ceval.c,
239
which has more basic blocks than the default limit of 1000). If the
240
warning bothers you, edit the Makefile to remove "-Olimit 1500" from
243
If you get failures in test_long, or sys.maxint gets set to -1, you
244
are probably experiencing compiler bugs, usually related to
245
optimization. This is a common problem with some versions of gcc, and
246
some vendor-supplied compilers, which can sometimes be worked around
247
by turning off optimization. Consider switching to stable versions
248
(gcc 2.95.2, gcc 3.x, or contact your vendor.)
250
From Python 2.0 onward, all Python C code is ANSI C. Compiling using
251
old K&R-C-only compilers is no longer possible. ANSI C compilers are
252
available for all modern systems, either in the form of updated
253
compilers from the vendor, or one of the free compilers (gcc).
255
If "make install" fails mysteriously during the "compiling the library"
256
step, make sure that you don't have any of the PYTHONPATH or PYTHONHOME
257
environment variables set, as they may interfere with the newly built
258
executable which is compiling the library.
263
A number of systems are not supported in Python 2.7 anymore. Some
264
support code is still present, but will be removed in later versions.
265
If you still need to use current Python versions on these systems,
266
please send a message to python-dev@python.org indicating that you
267
volunteer to support this system. For a more detailed discussion
268
regarding no-longer-supported and resupporting platforms, as well
269
as a list of platforms that became or will be unsupported, see PEP 11.
271
More specifically, the following systems are not supported any
278
- Irix 4 and --with-sgi-dl
280
- Systems defining __d6_pthread_create (configure.ac)
281
- Systems defining PY_PTHREAD_D4, PY_PTHREAD_D6,
282
or PY_PTHREAD_D7 in thread_pthread.h
283
- Systems using --with-dl-dld
284
- Systems using --without-universal-newlines
286
- Systems using --with-wctype-functions
290
Platform specific notes
291
-----------------------
293
(Some of these may no longer apply. If you find you can build Python
294
on these platforms without the special directions mentioned here,
295
submit a documentation bug report to SourceForge (see Bug Reports
296
above) so we can remove them!)
298
Unix platforms: If your vendor still ships (and you still use) Berkeley DB
299
1.85 you will need to edit Modules/Setup to build the bsddb185
300
module and add a line to sitecustomize.py which makes it the
301
default. In Modules/Setup a line like
303
bsddb185 bsddbmodule.c
305
should work. (You may need to add -I, -L or -l flags to direct the
306
compiler and linker to your include files and libraries.)
308
XXX I think this next bit is out of date:
310
64-bit platforms: The modules audioop, and imageop don't work.
311
The setup.py script disables them on 64-bit installations.
312
Don't try to enable them in the Modules/Setup file. They
313
contain code that is quite wordsize sensitive. (If you have a
316
Solaris: When using Sun's C compiler with threads, at least on Solaris
317
2.5.1, you need to add the "-mt" compiler option (the simplest
318
way is probably to specify the compiler with this option as
319
the "CC" environment variable when running the configure
322
When using GCC on Solaris, beware of binutils 2.13 or GCC
323
versions built using it. This mistakenly enables the
324
-zcombreloc option which creates broken shared libraries on
325
Solaris. binutils 2.12 works, and the binutils maintainers
326
are aware of the problem. Binutils 2.13.1 only partially
327
fixed things. It appears that 2.13.2 solves the problem
328
completely. This problem is known to occur with Solaris 2.7
329
and 2.8, but may also affect earlier and later versions of the
332
When the dynamic loader complains about errors finding shared
335
ld.so.1: ./python: fatal: libstdc++.so.5: open failed:
336
No such file or directory
338
you need to first make sure that the library is available on
339
your system. Then, you need to instruct the dynamic loader how
340
to find it. You can choose any of the following strategies:
342
1. When compiling Python, set LD_RUN_PATH to the directories
343
containing missing libraries.
344
2. When running Python, set LD_LIBRARY_PATH to these directories.
345
3. Use crle(8) to extend the search path of the loader.
346
4. Modify the installed GCC specs file, adding -R options into the
349
The complex object fails to compile on Solaris 10 with gcc 3.4 (at
350
least up to 3.4.3). To work around it, define Py_HUGE_VAL as
353
make CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()" -I. -I$(srcdir)/Include'
354
./python setup.py CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()"'
356
Linux: A problem with threads and fork() was tracked down to a bug in
357
the pthreads code in glibc version 2.0.5; glibc version 2.0.7
358
solves the problem. This causes the popen2 test to fail;
359
problem and solution reported by Pablo Bleyer.
361
Red Hat Linux: Red Hat 9 built Python2.2 in UCS-4 mode and hacked
362
Tcl to support it. To compile Python2.3 with Tkinter, you will
363
need to pass --enable-unicode=ucs4 flag to ./configure.
365
There's an executable /usr/bin/python which is Python
366
1.5.2 on most older Red Hat installations; several key Red Hat tools
367
require this version. Python 2.1.x may be installed as
368
/usr/bin/python2. The Makefile installs Python as
369
/usr/local/bin/python, which may or may not take precedence
370
over /usr/bin/python, depending on how you have set up $PATH.
372
FreeBSD 3.x and probably platforms with NCurses that use libmytinfo or
373
similar: When using cursesmodule, the linking is not done in
374
the correct order with the defaults. Remove "-ltermcap" from
375
the readline entry in Setup, and use as curses entry: "curses
376
cursesmodule.c -lmytinfo -lncurses -ltermcap" - "mytinfo" (so
377
called on FreeBSD) should be the name of the auxiliary library
378
required on your platform. Normally, it would be linked
379
automatically, but not necessarily in the correct order.
381
BSDI: BSDI versions before 4.1 have known problems with threads,
382
which can cause strange errors in a number of modules (for
383
instance, the 'test_signal' test script will hang forever.)
384
Turning off threads (with --with-threads=no) or upgrading to
385
BSDI 4.1 solves this problem.
387
DEC Unix: Run configure with --with-dec-threads, or with
388
--with-threads=no if no threads are desired (threads are on by
389
default). When using GCC, it is possible to get an internal
390
compiler error if optimization is used. This was reported for
391
GCC 2.7.2.3 on selectmodule.c. Manually compile the affected
392
file without optimization to solve the problem.
394
DEC Ultrix: compile with GCC to avoid bugs in the native compiler,
395
and pass SHELL=/bin/sh5 to Make when installing.
397
AIX: A complete overhaul of the shared library support is now in
398
place. See Misc/AIX-NOTES for some notes on how it's done.
399
(The optimizer bug reported at this place in previous releases
400
has been worked around by a minimal code change.) If you get
401
errors about pthread_* functions, during compile or during
402
testing, try setting CC to a thread-safe (reentrant) compiler,
403
like "cc_r". For full C++ module support, set CC="xlC_r" (or
404
CC="xlC" without thread support).
406
AIX 5.3: To build a 64-bit version with IBM's compiler, I used the
409
export PATH=/usr/bin:/usr/vacpp/bin
410
./configure --with-gcc="xlc_r -q64" --with-cxx="xlC_r -q64" \
411
--disable-ipv6 AR="ar -X64"
414
HP-UX: When using threading, you may have to add -D_REENTRANT to the
415
OPT variable in the top-level Makefile; reported by Pat Knight,
416
this seems to make a difference (at least for HP-UX 10.20)
417
even though pyconfig.h defines it. This seems unnecessary when
418
using HP/UX 11 and later - threading seems to work "out of the
421
HP-UX ia64: When building on the ia64 (Itanium) platform using HP's
422
compiler, some experience has shown that the compiler's
423
optimiser produces a completely broken version of python
424
(see http://bugs.python.org/814976). To work around this,
425
edit the Makefile and remove -O from the OPT line.
427
To build a 64-bit executable on an Itanium 2 system using HP's
428
compiler, use these environment variables:
433
LDFLAGS="+DD64 -lxnet"
435
and call configure as:
437
./configure --without-gcc
439
then *unset* the environment variables again before running
440
make. (At least one of these flags causes the build to fail
441
if it remains set.) You still have to edit the Makefile and
442
remove -O from the OPT line.
444
HP PA-RISC 2.0: A recent bug report (http://bugs.python.org/546117)
445
suggests that the C compiler in this 64-bit system has bugs
446
in the optimizer that break Python. Compiling without
447
optimization solves the problems.
449
SCO: The following apply to SCO 3 only; Python builds out of the box
450
on SCO 5 (or so we've heard).
452
1) Everything works much better if you add -U__STDC__ to the
453
defs. This is because all the SCO header files are broken.
454
Anything that isn't mentioned in the C standard is
455
conditionally excluded when __STDC__ is defined.
457
2) Due to the U.S. export restrictions, SCO broke the crypt
458
stuff out into a separate library, libcrypt_i.a so the LIBS
461
LIBS=' -lsocket -lcrypt_i'
463
UnixWare: There are known bugs in the math library of the system, as well as
464
problems in the handling of threads (calling fork in one
465
thread may interrupt system calls in others). Therefore, test_math and
466
tests involving threads will fail until those problems are fixed.
468
QNX: Chris Herborth (chrish@qnx.com) writes:
469
configure works best if you use GNU bash; a port is available on
470
ftp.qnx.com in /usr/free. I used the following process to build,
471
test and install Python 1.5.x under QNX:
473
1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \
474
./configure --verbose --without-gcc --with-libm=""
476
2) edit Modules/Setup to activate everything that makes sense for
477
your system... tested here at QNX with the following modules:
479
array, audioop, binascii, cPickle, cStringIO, cmath,
480
crypt, curses, errno, fcntl, gdbm, grp, imageop,
481
_locale, math, md5, new, operator, parser, pcre,
482
posix, pwd, readline, regex, reop,
483
select, signal, socket, soundex, strop, struct,
484
syslog, termios, time, timing, zlib, audioop, imageop
486
3) make SHELL=/usr/local/bin/bash
488
or, if you feel the need for speed:
490
make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"
492
4) make SHELL=/usr/local/bin/bash test
494
Using GNU readline 2.2 seems to behave strangely, but I
495
think that's a problem with my readline 2.2 port. :-\
497
5) make SHELL=/usr/local/bin/bash install
499
If you get SIGSEGVs while running Python (I haven't yet, but
500
I've only run small programs and the test cases), you're
501
probably running out of stack; the default 32k could be a
502
little tight. To increase the stack size, edit the Makefile
503
to read: LDFLAGS = -N 48k
505
BeOS: See Misc/BeOS-NOTES for notes about compiling/installing
506
Python on BeOS R3 or later. Note that only the PowerPC
507
platform is supported for R3; both PowerPC and x86 are
510
Cray T3E: Mark Hadfield (m.hadfield@niwa.co.nz) writes:
511
Python can be built satisfactorily on a Cray T3E but based on
512
my experience with the NIWA T3E (2002-05-22, version 2.2.1)
513
there are a few bugs and gotchas. For more information see a
514
thread on comp.lang.python in May 2002 entitled "Building
517
1) Use Cray's cc and not gcc. The latter was reported not to
518
work by Konrad Hinsen. It may work now, but it may not.
520
2) To set sys.platform to something sensible, pass the
521
following environment variable to the configure script:
525
2) Run configure with option "--enable-unicode=ucs4".
527
3) The Cray T3E does not support dynamic linking, so extension
528
modules have to be built by adding (or uncommenting) lines
529
in Modules/Setup. The minimum set of modules is
531
posix, new, _sre, unicodedata
533
On NIWA's vanilla T3E system the following have also been
534
included successfully:
536
_codecs, _locale, _socket, _symtable, _testcapi, _weakref
537
array, binascii, cmath, cPickle, crypt, cStringIO, dbm
538
errno, fcntl, grp, math, md5, operator, parser, pcre, pwd
539
regex, rotor, select, struct, strop, syslog, termios
540
time, timing, xreadlines
542
4) Once the python executable and library have been built, make
543
will execute setup.py, which will attempt to build remaining
544
extensions and link them dynamically. Each of these attempts
545
will fail but should not halt the make process. This is
548
5) Running "make test" uses a lot of resources and causes
549
problems on our system. You might want to try running tests
550
singly or in small groups.
552
SGI: SGI's standard "make" utility (/bin/make or /usr/bin/make)
553
does not check whether a command actually changed the file it
554
is supposed to build. This means that whenever you say "make"
555
it will redo the link step. The remedy is to use SGI's much
556
smarter "smake" utility (/usr/sbin/smake), or GNU make. If
557
you set the first line of the Makefile to #!/usr/sbin/smake
558
smake will be invoked by make (likewise for GNU make).
560
WARNING: There are bugs in the optimizer of some versions of
561
SGI's compilers that can cause bus errors or other strange
562
behavior, especially on numerical operations. To avoid this,
563
try building with "make OPT=".
565
OS/2: If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
566
compiler installed, just change into the pc\os2vacpp directory
567
and type NMAKE. Threading and sockets are supported by default
568
in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
570
Reliant UNIX: The thread support does not compile on Reliant UNIX, and
571
there is a (minor) problem in the configure script for that
572
platform as well. This should be resolved in time for a
575
MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
576
test_re and test_sre due to the small default stack size. If
577
you set the stack size to 2048 before doing a "make test" the
578
failure can be avoided. If you're using the tcsh or csh shells,
579
use "limit stacksize 2048" and for the bash shell (the default
580
as of OSX 10.3), use "ulimit -s 2048".
582
On naked Darwin you may want to add the configure option
583
"--disable-toolbox-glue" to disable the glue code for the Carbon
584
interface modules. The modules themselves are currently only built
585
if you add the --enable-framework option, see below.
587
On a clean OSX /usr/local does not exist. Do a
588
"sudo mkdir -m 775 /usr/local"
589
before you do a make install. It is probably not a good idea to
590
do "sudo make install" which installs everything as superuser,
591
as this may later cause problems when installing distutils-based
594
Some people have reported problems building Python after using "fink"
595
to install additional unix software. Disabling fink (remove all
596
references to /sw from your .profile or .login) should solve this.
598
You may want to try the configure option "--enable-framework"
599
which installs Python as a framework. The location can be set
600
as argument to the --enable-framework option (default
601
/Library/Frameworks). A framework install is probably needed if you
602
want to use any Aqua-based GUI toolkit (whether Tkinter, wxPython,
603
Carbon, Cocoa or anything else).
605
You may also want to try the configure option "--enable-universalsdk"
606
which builds Python as a universal binary with support for the
607
i386 and PPC architetures. This requires Xcode 2.1 or later to build.
609
See Mac/README for more information on framework and
612
Cygwin: With recent (relative to the time of writing, 2001-12-19)
613
Cygwin installations, there are problems with the interaction
614
of dynamic linking and fork(). This manifests itself in build
615
failures during the execution of setup.py.
617
There are two workarounds that both enable Python (albeit
618
without threading support) to build and pass all tests on
619
NT/2000 (and most likely XP as well, though reports of testing
620
on XP would be appreciated).
624
(a) the band-aid fix is to link the _socket module statically
625
rather than dynamically (which is the default).
627
To do this, run "./configure --with-threads=no" including any
628
other options you need (--prefix, etc.). Then in Modules/Setup
632
#_socket socketmodule.c \
633
# -DUSE_SSL -I$(SSL)/include -I$(SSL)/include/openssl \
634
# -L$(SSL)/lib -lssl -lcrypto
636
and remove "local/" from the SSL variable. Finally, just run
639
(b) The "proper" fix is to rebase the Cygwin DLLs to prevent
640
base address conflicts. Details on how to do this can be
641
found in the following mail:
643
http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html
645
It is hoped that a version of this solution will be
646
incorporated into the Cygwin distribution fairly soon.
648
Two additional problems:
650
(1) Threading support should still be disabled due to a known
651
bug in Cygwin pthreads that causes test_threadedtempfile to
654
(2) The _curses module does not build. This is a known
655
Cygwin ncurses problem that should be resolved the next time
656
that this package is released.
658
On older versions of Cygwin, test_poll may hang and test_strftime
661
The situation on 9X/Me is not accurately known at present.
662
Some time ago, there were reports that the following
663
regression tests failed:
669
Due to the test_select hang on 9X/Me, one should run the
670
regression test using the following:
672
make TESTOPTS='-l -x test_select' test
674
News regarding these platforms with more recent Cygwin
675
versions would be appreciated!
677
Windows: When executing Python scripts on the command line using file type
678
associations (i.e. starting "script.py" instead of "python script.py"),
679
redirects may not work unless you set a specific registry key. See
680
the Knowledge Base article <http://support.microsoft.com/kb/321788>.
683
Configuring the bsddb and dbm modules
684
-------------------------------------
686
Beginning with Python version 2.3, the PyBsddb package
687
<http://pybsddb.sf.net/> was adopted into Python as the bsddb package,
688
exposing a set of package-level functions which provide
689
backwards-compatible behavior. Only versions 3.3 through 4.4 of
690
Sleepycat's libraries provide the necessary API, so older versions
691
aren't supported through this interface. The old bsddb module has
692
been retained as bsddb185, though it is not built by default. Users
693
wishing to use it will have to tweak Modules/Setup to build it. The
694
dbm module will still be built against the Sleepycat libraries if
695
other preferred alternatives (ndbm, gdbm) are not found.
697
Building the sqlite3 module
698
---------------------------
700
To build the sqlite3 module, you'll need the sqlite3 or libsqlite3
701
packages installed, including the header files. Many modern operating
702
systems distribute the headers in a separate package to the library -
703
often it will be the same name as the main package, but with a -dev or
706
The version of pysqlite2 that's including in Python needs sqlite3 3.0.8
707
or later. setup.py attempts to check that it can find a correct version.
712
As of Python 2.0, threads are enabled by default. If you wish to
713
compile without threads, or if your thread support is broken, pass the
714
--with-threads=no switch to configure. Unfortunately, on some
715
platforms, additional compiler and/or linker options are required for
716
threads to work properly. Below is a table of those options,
717
collected by Bill Janssen. We would love to automate this process
718
more, but the information below is not enough to write a patch for the
719
configure.ac file, so manual intervention is required. If you patch
720
the configure.ac file and are confident that the patch works, please
721
send in the patch. (Don't bother patching the configure script itself
723
Compiler switches for threads
724
.............................
726
The definition of _REENTRANT should be configured automatically, if
727
that does not work on your system, or if _REENTRANT is defined
728
incorrectly, please report that as a bug.
730
OS/Compiler/threads Switches for use with threads
731
(POSIX is draft 10, DCE is draft 4) compile & link
733
SunOS 5.{1-5}/{gcc,SunPro cc}/solaris -mt
734
SunOS 5.5/{gcc,SunPro cc}/POSIX (nothing)
735
DEC OSF/1 3.x/cc/DCE -threads
736
(butenhof@zko.dec.com)
737
Digital UNIX 4.x/cc/DCE -threads
738
(butenhof@zko.dec.com)
739
Digital UNIX 4.x/cc/POSIX -pthread
740
(butenhof@zko.dec.com)
741
AIX 4.1.4/cc_r/d7 (nothing)
743
AIX 4.1.4/cc_r4/DCE (nothing)
745
IRIX 6.2/cc/POSIX (nothing)
749
Linker (ld) libraries and flags for threads
750
...........................................
752
OS/threads Libraries/switches for use with threads
754
SunOS 5.{1-5}/solaris -lthread
755
SunOS 5.5/POSIX -lpthread
756
DEC OSF/1 3.x/DCE -lpthreads -lmach -lc_r -lc
757
(butenhof@zko.dec.com)
758
Digital UNIX 4.x/DCE -lpthreads -lpthread -lmach -lexc -lc
759
(butenhof@zko.dec.com)
760
Digital UNIX 4.x/POSIX -lpthread -lmach -lexc -lc
761
(butenhof@zko.dec.com)
762
AIX 4.1.4/{draft7,DCE} (nothing)
764
IRIX 6.2/POSIX -lpthread
765
(jph@emilia.engr.sgi.com)
768
Building a shared libpython
769
---------------------------
771
Starting with Python 2.3, the majority of the interpreter can be built
772
into a shared library, which can then be used by the interpreter
773
executable, and by applications embedding Python. To enable this feature,
774
configure with --enable-shared.
776
If you enable this feature, the same object files will be used to create
777
a static library. In particular, the static library will contain object
778
files using position-independent code (PIC) on platforms where PIC flags
779
are needed for the shared library.
782
Configuring additional built-in modules
783
---------------------------------------
785
Starting with Python 2.1, the setup.py script at the top of the source
786
distribution attempts to detect which modules can be built and
787
automatically compiles them. Autodetection doesn't always work, so
788
you can still customize the configuration by editing the Modules/Setup
789
file; but this should be considered a last resort. The rest of this
790
section only applies if you decide to edit the Modules/Setup file.
791
You also need this to enable static linking of certain modules (which
792
is needed to enable profiling on some systems).
794
This file is initially copied from Setup.dist by the configure script;
795
if it does not exist yet, create it by copying Modules/Setup.dist
796
yourself (configure will never overwrite it). Never edit Setup.dist
797
the file for information on what kind of edits are allowed. When you
798
have edited Setup in the Modules directory, the interpreter will
799
automatically be rebuilt the next time you run make (in the toplevel
802
Many useful modules can be built on any Unix system, but some optional
803
modules can't be reliably autodetected. Often the quickest way to
804
determine whether a particular module works or not is to see if it
805
will build: enable it in Setup, then if you get compilation or link
806
errors, disable it -- you're either missing support or need to adjust
807
the compilation and linking parameters for that module.
809
On SGI IRIX, there are modules that interface to many SGI specific
810
system libraries, e.g. the GL library and the audio hardware. These
811
modules will not be built by the setup.py script.
813
In addition to the file Setup, you can also edit the file Setup.local.
814
(the makesetup script processes both). You may find it more
815
convenient to edit Setup.local and leave Setup alone. Then, when
816
installing a new Python version, you can copy your old Setup.local
820
Setting the optimization/debugging options
821
------------------------------------------
823
If you want or need to change the optimization/debugging options for
824
the C compiler, assign to the OPT variable on the toplevel make
825
command; e.g. "make OPT=-g" will build a debugging version of Python
826
on most platforms. The default is OPT=-O; a value for OPT in the
827
environment when the configure script is run overrides this default
828
(likewise for CC; and the initial value for LIBS is used as the base
829
set of libraries to link with).
831
When compiling with GCC, the default value of OPT will also include
832
the -Wall and -Wstrict-prototypes options.
834
Additional debugging code to help debug memory management problems can
835
be enabled by using the --with-pydebug option to the configure script.
837
For flags that change binary compatibility, use the EXTRA_CFLAGS
844
If you want C profiling turned on, the easiest way is to run configure
845
with the CC environment variable to the necessary compiler
846
invocation. For example, on Linux, this works for profiling using
849
CC="gcc -pg" ./configure
851
Note that on Linux, gprof apparently does not work for shared
852
libraries. The Makefile/Setup mechanism can be used to compile and
853
link most extension modules statically.
859
For C coverage checking using gcov, run "make coverage". This will
860
build a Python binary with profiling activated, and a ".gcno" and
861
".gcda" file for every source file compiled with that option. With
862
the built binary, now run the code whose coverage you want to check.
863
Then, you can see coverage statistics for each individual source file
864
by running gcov, e.g.
866
gcov -o Modules zlibmodule
868
This will create a "zlibmodule.c.gcov" file in the current directory
869
containing coverage info for that source file.
871
This works only for source files statically compiled into the
872
executable; use the Makefile/Setup mechanism to compile and link
873
extension modules you want to coverage-check statically.
879
To test the interpreter, type "make test" in the top-level directory.
880
This runs the test set twice (once with no compiled files, once with
881
the compiled files left by the previous test run). The test set
882
produces some output. You can generally ignore the messages about
883
skipped tests due to optional features which can't be imported.
884
If a message is printed about a failed test or a traceback or core
885
dump is produced, something is wrong. On some Linux systems (those
886
that are not yet using glibc 6), test_strftime fails due to a
887
non-standard implementation of strftime() in the C library. Please
888
ignore this, or upgrade to glibc version 6.
890
By default, tests are prevented from overusing resources like disk space and
891
memory. To enable these tests, run "make testall".
893
IMPORTANT: If the tests fail and you decide to mail a bug report,
894
*don't* include the output of "make test". It is useless. Run the
895
failing test manually, as follows:
897
./python Lib/test/regrtest.py -v test_whatever
899
(substituting the top of the source tree for '.' if you built in a
900
different directory). This runs the test in verbose mode.
906
To install the Python binary, library modules, shared library modules
907
(see below), include files, configuration files, and the manual page,
912
This will install all platform-independent files in subdirectories of
913
the directory given with the --prefix option to configure or to the
914
`prefix' Make variable (default /usr/local). All binary and other
915
platform-specific files will be installed in subdirectories if the
916
directory given by --exec-prefix or the `exec_prefix' Make variable
917
(defaults to the --prefix directory) is given.
919
If DESTDIR is set, it will be taken as the root directory of the
920
installation, and files will be installed into $(DESTDIR)$(prefix),
921
$(DESTDIR)$(exec_prefix), etc.
923
All subdirectories created will have Python's version number in their
924
name, e.g. the library modules are installed in
925
"/usr/local/lib/python<version>/" by default, where <version> is the
926
<major>.<minor> release number (e.g. "2.1"). The Python binary is
927
installed as "python<version>" and a hard link named "python" is
928
created. The only file not installed with a version number in its
929
name is the manual page, installed as "/usr/local/man/man1/python.1"
932
If you want to install multiple versions of Python see the section below
933
entitled "Installing multiple versions".
935
The only thing you may have to install manually is the Python mode for
936
Emacs found in Misc/python-mode.el. (But then again, more recent
937
versions of Emacs may already have it.) Follow the instructions that
938
came with Emacs for installation of site-specific files.
940
On Mac OS X, if you have configured Python with --enable-framework, you
941
should use "make frameworkinstall" to do the installation. Note that this
942
installs the Python executable in a place that is not normally on your
943
PATH, you may want to set up a symlink in /usr/local/bin.
946
Installing multiple versions
947
----------------------------
949
On Unix and Mac systems if you intend to install multiple versions of Python
950
using the same installation prefix (--prefix argument to the configure
951
script) you must take care that your primary python executable is not
952
overwritten by the installation of a different version. All files and
953
directories installed using "make altinstall" contain the major and minor
954
version and can thus live side-by-side. "make install" also creates
955
${prefix}/bin/python which refers to ${prefix}/bin/pythonX.Y. If you intend
956
to install multiple versions using the same prefix you must decide which
957
version (if any) is your "primary" version. Install that version using
958
"make install". Install all other versions using "make altinstall".
960
For example, if you want to install Python 2.5, 2.6 and 3.0 with 2.6 being
961
the primary version, you would execute "make install" in your 2.6 build
962
directory and "make altinstall" in the others.
965
Configuration options and variables
966
-----------------------------------
968
Some special cases are handled by passing options to the configure
971
WARNING: if you rerun the configure script with different options, you
972
must run "make clean" before rebuilding. Exceptions to this rule:
973
after changing --prefix or --exec-prefix, all you need to do is remove
976
--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
977
it finds it. If you don't want this, or if this compiler is
978
installed but broken on your platform, pass the option
979
--without-gcc. You can also pass "CC=cc" (or whatever the
980
name of the proper C compiler is) in the environment, but the
981
advantage of using --without-gcc is that this option is
982
remembered by the config.status script for its --recheck
985
--prefix, --exec-prefix: If you want to install the binaries and the
986
Python library somewhere else than in /usr/local/{bin,lib},
987
you can pass the option --prefix=DIRECTORY; the interpreter
988
binary will be installed as DIRECTORY/bin/python and the
989
library files as DIRECTORY/lib/python/*. If you pass
990
--exec-prefix=DIRECTORY (as well) this overrides the
991
installation prefix for architecture-dependent files (like the
992
interpreter binary). Note that --prefix=DIRECTORY also
993
affects the default module search path (sys.path), when
994
Modules/config.c is compiled. Passing make the option
995
prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
996
prefix set at configuration time; this may be more convenient
997
than re-running the configure script if you change your mind
998
about the install prefix.
1000
--with-readline: This option is no longer supported. GNU
1001
readline is automatically enabled by setup.py when present.
1003
--with-threads: On most Unix systems, you can now use multiple
1004
threads, and support for this is enabled by default. To
1005
disable this, pass --with-threads=no. If the library required
1006
for threads lives in a peculiar place, you can use
1007
--with-thread=DIRECTORY. IMPORTANT: run "make clean" after
1008
changing (either enabling or disabling) this option, or you
1009
will get link errors! Note: for DEC Unix use
1010
--with-dec-threads instead.
1012
--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
1013
supported by the "dl" library by Jack Jansen, which is
1014
ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
1015
This is enabled (after you've ftp'ed and compiled the dl
1016
library) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
1017
is the absolute pathname of the dl library. (Don't bother on
1018
IRIX 5, it already has dynamic linking using SunOS style
1019
shared libraries.) THIS OPTION IS UNSUPPORTED.
1021
--with-dl-dld: Dynamic loading of modules is rumored to be supported
1022
on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
1023
Symmetry (Dynix), and Atari ST. This is done using a
1024
combination of the GNU dynamic loading package
1025
(ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
1026
emulation of the SGI dl library mentioned above (the emulation
1028
ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z). To
1029
enable this, ftp and compile both libraries, then call
1030
configure, passing it the option
1031
--with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
1032
the absolute pathname of the dl emulation library and
1033
DLD_DIRECTORY is the absolute pathname of the GNU dld library.
1034
(Don't bother on SunOS 4 or 5, they already have dynamic
1035
linking using shared libraries.) THIS OPTION IS UNSUPPORTED.
1037
--with-libm, --with-libc: It is possible to specify alternative
1038
versions for the Math library (default -lm) and the C library
1039
(default the empty string) using the options
1040
--with-libm=STRING and --with-libc=STRING, respectively. For
1041
example, if your system requires that you pass -lc_s to the C
1042
compiler to use the shared C library, you can pass
1043
--with-libc=-lc_s. These libraries are passed after all other
1044
libraries, the C library last.
1046
--with-libs='libs': Add 'libs' to the LIBS that the python interpreter
1049
--with-cxx-main=<compiler>: If you plan to use C++ extension modules,
1050
then -- on some platforms -- you need to compile python's main()
1051
function with the C++ compiler. With this option, make will use
1052
<compiler> to compile main() *and* to link the python executable.
1053
It is likely that the resulting executable depends on the C++
1054
runtime library of <compiler>. (The default is --without-cxx-main.)
1056
There are platforms that do not require you to build Python
1057
with a C++ compiler in order to use C++ extension modules.
1058
E.g., x86 Linux with ELF shared binaries and GCC 3.x, 4.x is such
1059
a platform. We recommend that you configure Python
1060
--without-cxx-main on those platforms because a mismatch
1061
between the C++ compiler version used to build Python and to
1062
build a C++ extension module is likely to cause a crash at
1065
The Python installation also stores the variable CXX that
1066
determines, e.g., the C++ compiler distutils calls by default
1067
to build C++ extensions. If you set CXX on the configure command
1068
line to any string of non-zero length, then configure won't
1069
change CXX. If you do not preset CXX but pass
1070
--with-cxx-main=<compiler>, then configure sets CXX=<compiler>.
1071
In all other cases, configure looks for a C++ compiler by
1072
some common names (c++, g++, gcc, CC, cxx, cc++, cl) and sets
1073
CXX to the first compiler it finds. If it does not find any
1074
C++ compiler, then it sets CXX="".
1076
Similarly, if you want to change the command used to link the
1077
python executable, then set LINKCC on the configure command line.
1080
--with-pydebug: Enable additional debugging code to help track down
1081
memory management problems. This allows printing a list of all
1082
live objects when the interpreter terminates.
1084
--with(out)-universal-newlines: enable reading of text files with
1085
foreign newline convention (default: enabled). In other words,
1086
any of \r, \n or \r\n is acceptable as end-of-line character.
1087
If enabled import and execfile will automatically accept any newline
1088
in files. Python code can open a file with open(file, 'U') to
1089
read it in universal newline mode. THIS OPTION IS UNSUPPORTED.
1091
--with-tsc: Profile using the Pentium timestamping counter (TSC).
1093
--with-system-ffi: Build the _ctypes extension module using an ffi
1094
library installed on the system.
1096
--with-dbmliborder=db1:db2:...: Specify the order that backends for the
1097
dbm extension are checked. Valid value is a colon separated string
1098
with the backend names `ndbm', `gdbm' and `bdb'.
1100
Building for multiple architectures (using the VPATH feature)
1101
-------------------------------------------------------------
1103
If your file system is shared between multiple architectures, it
1104
usually is not necessary to make copies of the sources for each
1105
architecture you want to support. If the make program supports the
1106
VPATH feature, you can create an empty build directory for each
1107
architecture, and in each directory run the configure script (on the
1108
appropriate machine with the appropriate options). This creates the
1109
necessary subdirectories and the Makefiles therein. The Makefiles
1110
contain a line VPATH=... which points to a directory containing the
1111
actual sources. (On SGI systems, use "smake -J1" instead of "make" if
1112
you use VPATH -- don't try gnumake.)
1114
For example, the following is all you need to build a minimal Python
1115
in /usr/tmp/python (assuming ~guido/src/python is the toplevel
1116
directory and you want to build in /usr/tmp/python):
1118
$ mkdir /usr/tmp/python
1119
$ cd /usr/tmp/python
1120
$ ~guido/src/python/configure
1126
Note that configure copies the original Setup file to the build
1127
directory if it finds no Setup file there. This means that you can
1128
edit the Setup file for each architecture independently. For this
1129
reason, subsequent changes to the original Setup file are not tracked
1130
automatically, as they might overwrite local changes. To force a copy
1131
of a changed original Setup file, delete the target Setup file. (The
1132
makesetup script supports multiple input files, so if you want to be
1133
fancy you can change the rules to create an empty Setup.local if it
1134
doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
1135
however this assumes that you only need to add modules.)
1137
Also note that you can't use a workspace for VPATH and non VPATH builds. The
1138
object files left behind by one version confuses the other.
1141
Building on non-UNIX systems
1142
----------------------------
1144
For Windows (2000/NT/ME/98/95), assuming you have MS VC++ 7.1, the
1145
project files are in PCbuild, the workspace is pcbuild.dsw. See
1146
PCbuild\readme.txt for detailed instructions.
1148
For other non-Unix Windows compilers, in particular MS VC++ 6.0 and
1149
for OS/2, enter the directory "PC" and read the file "readme.txt".
1151
For the Mac, a separate source distribution will be made available,
1152
for use with the CodeWarrior compiler. If you are interested in Mac
1153
development, join the PythonMac Special Interest Group
1154
(http://www.python.org/sigs/pythonmac-sig/, or send email to
1155
pythonmac-sig-request@python.org).
1157
Of course, there are also binary distributions available for these
1158
platforms -- see http://www.python.org/.
1160
To port Python to a new non-UNIX system, you will have to fake the
1161
effect of running the configure script manually (for Mac and PC, this
1162
has already been done for you). A good start is to copy the file
1163
pyconfig.h.in to pyconfig.h and edit the latter to reflect the actual
1164
configuration of your system. Most symbols must simply be defined as
1165
1 only if the corresponding feature is present and can be left alone
1166
otherwise; however the *_t type symbols must be defined as some
1167
variant of int if they need to be defined at all.
1169
For all platforms, it's important that the build arrange to define the
1170
preprocessor symbol NDEBUG on the compiler command line in a release
1171
build of Python (else assert() calls remain in the code, hurting
1172
release-build performance). The Unix, Windows and Mac builds already
1176
Miscellaneous issues
1177
====================
1182
There's an excellent Emacs editing mode for Python code; see the file
1183
Misc/python-mode.el. Originally written by the famous Tim Peters, it is now
1184
maintained by the equally famous Barry Warsaw. The latest version, along with
1185
various other contributed Python-related Emacs goodies, is online at
1186
http://launchpad.net/python-mode/.
1192
The setup.py script automatically configures this when it detects a
1193
usable Tcl/Tk installation. This requires Tcl/Tk version 8.0 or
1196
For more Tkinter information, see the Tkinter Resource page:
1197
http://www.python.org/topics/tkinter/
1199
There are demos in the Demo/tkinter directory.
1201
Note that there's a Python module called "Tkinter" (capital T) which
1202
lives in Lib/lib-tk/Tkinter.py, and a C module called "_tkinter"
1203
(lower case t and leading underscore) which lives in
1204
Modules/_tkinter.c. Demos and normal Tk applications import only the
1205
Python Tkinter module -- only the latter imports the C _tkinter
1206
module. In order to find the C _tkinter module, it must be compiled
1207
and linked into the Python interpreter -- the setup.py script does
1208
this. In order to find the Python Tkinter module, sys.path must be
1209
set correctly -- normal installation takes care of this.
1212
Distribution structure
1213
----------------------
1215
Most subdirectories have their own README files. Most files have
1218
Demo/ Demonstration scripts, modules and programs
1219
Doc/ Documentation sources (reStructuredText)
1220
Grammar/ Input for the parser generator
1221
Include/ Public header files
1222
LICENSE Licensing information
1223
Lib/ Python library modules
1224
Mac/ Macintosh specific resources
1225
Makefile.pre.in Source from which config.status creates the Makefile.pre
1226
Misc/ Miscellaneous useful files
1227
Modules/ Implementation of most built-in modules
1228
Objects/ Implementation of most built-in object types
1229
PC/ Files specific to PC ports (DOS, Windows, OS/2)
1230
PCbuild/ Build directory for Microsoft Visual C++
1231
Parser/ The parser and tokenizer and their input handling
1232
Python/ The byte-compiler and interpreter
1233
README The file you're reading now
1234
RISCOS/ Files specific to RISC OS port
1235
Tools/ Some useful programs written in Python
1236
pyconfig.h.in Source from which pyconfig.h is created (GNU autoheader output)
1237
configure Configuration shell script (GNU autoconf output)
1238
configure.ac Configuration specification (input for GNU autoconf)
1239
install-sh Shell script used to install files
1240
setup.py Python script used to build extension modules
1242
The following files will (may) be created in the toplevel directory by
1243
the configuration and build processes:
1245
Makefile Build rules
1246
Makefile.pre Build rules before running Modules/makesetup
1247
buildno Keeps track of the build number
1248
config.cache Cache of configuration variables
1249
pyconfig.h Configuration header
1250
config.log Log from last configure run
1251
config.status Status from last run of the configure script
1252
getbuildinfo.o Object file from Modules/getbuildinfo.c
1253
libpython<version>.a The library archive
1254
python The executable interpreter
1255
reflog.txt Output from running the regression suite with the -R flag
1256
tags, TAGS Tags files for vi and Emacs
1263
--Guido van Rossum (home page: http://www.python.org/~guido/)
1
This is Python version 2.7.12
2
=============================
4
Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
5
2012, 2013, 2014, 2015, 2016 Python Software Foundation. All rights reserved.
7
Copyright (c) 2000 BeOpen.com.
10
Copyright (c) 1995-2001 Corporation for National Research Initiatives.
13
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
20
See the file "LICENSE" for information on the history of this
21
software, terms & conditions for usage, and a DISCLAIMER OF ALL
24
This Python distribution contains no GNU General Public Licensed
25
(GPLed) code so it may be used in proprietary projects just like prior
26
Python distributions. There are interfaces to some GNU code but these
27
are entirely optional.
29
All trademarks referenced herein are property of their respective
33
What's new in this release?
34
---------------------------
36
See the file "Misc/NEWS".
39
If you don't read instructions
40
------------------------------
42
Congratulations on getting this far. :-)
44
To start building right away (on UNIX): type "./configure" in the
45
current directory and when it finishes, type "make". This creates an
46
executable "./python"; to install in /usr/local, first do "su root"
47
and then "make install".
49
The section `Build instructions' below is still recommended reading.
52
What is Python anyway?
53
----------------------
55
Python is an interpreted, interactive object-oriented programming
56
language suitable (amongst other uses) for distributed application
57
development, scripting, numeric computing and system testing. Python
58
is often compared to Tcl, Perl, Java, JavaScript, Visual Basic or
59
Scheme. To find out more about what Python can do for you, point your
60
browser to http://www.python.org/.
63
How do I learn Python?
64
----------------------
66
The official tutorial is still a good place to start; see
67
http://docs.python.org/ for online and downloadable versions, as well
68
as a list of other introductions, and reference documentation.
70
There's a quickly growing set of books on Python. See
71
http://wiki.python.org/moin/PythonBooks for a list.
77
All documentation is provided online in a variety of formats. In
78
order of importance for new users: Tutorial, Library Reference,
79
Language Reference, Extending & Embedding, and the Python/C API. The
80
Library Reference is especially of immense value since much of
81
Python's power is described there, including the built-in data types
84
All documentation is also available online at the Python web site
85
(http://docs.python.org/, see below). It is available online for occasional
86
reference, or can be downloaded in many formats for faster access. The
87
documentation is downloadable in HTML, PostScript, PDF, LaTeX, and
88
reStructuredText (2.6+) formats; the LaTeX and reStructuredText versions are
89
primarily for documentation authors, translators, and people with special
90
formatting requirements.
92
If you would like to contribute to the development of Python, relevant
93
documentation is available at:
95
http://docs.python.org/devguide/
97
For information about building Python's documentation, refer to Doc/README.txt.
103
New Python releases and related technologies are published at
104
http://www.python.org/. Come visit us!
107
Newsgroups and Mailing Lists
108
----------------------------
110
Read comp.lang.python, a high-volume discussion newsgroup about
111
Python, or comp.lang.python.announce, a low-volume moderated newsgroup
112
for Python-related announcements. These are also accessible as
113
mailing lists: see http://www.python.org/community/lists/ for an
114
overview of these and many other Python-related mailing lists.
116
Archives are accessible via the Google Groups Usenet archive; see
117
http://groups.google.com/. The mailing lists are also archived, see
118
http://www.python.org/community/lists/ for details.
124
To report or search for bugs, please use the Python Bug
125
Tracker at http://bugs.python.org/.
128
Patches and contributions
129
-------------------------
131
To submit a patch or other contribution, please use the Python Patch
132
Manager at http://bugs.python.org/. Guidelines
133
for patch submission may be found at http://www.python.org/dev/patches/.
135
If you have a proposal to change Python, you may want to send an email to the
136
comp.lang.python or python-ideas mailing lists for inital feedback. A Python
137
Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
138
current PEPs, as well as guidelines for submitting a new PEP, are listed at
139
http://www.python.org/dev/peps/.
145
For help, if you can't find it in the manuals or on the web site, it's
146
best to post to the comp.lang.python or the Python mailing list (see
147
above). If you specifically don't want to involve the newsgroup or
148
mailing list, send questions to help@python.org (a group of volunteers
149
who answer questions as they can). The newsgroup is the most
150
efficient way to ask public questions.
156
Before you can build Python, you must first configure it.
157
Fortunately, the configuration and build process has been automated
158
for Unix and Linux installations, so all you usually have to do is
159
type a few commands and sit back. There are some platforms where
160
things are not quite as smooth; see the platform specific notes below.
161
If you want to build for multiple platforms sharing the same source
162
tree, see the section on VPATH below.
164
Start by running the script "./configure", which determines your
165
system configuration and creates the Makefile. (It takes a minute or
166
two -- please be patient!) You may want to pass options to the
167
configure script -- see the section below on configuration options and
168
variables. When it's done, you are ready to run make.
170
To build Python, you normally type "make" in the toplevel directory.
171
If you have changed the configuration, the Makefile may have to be
172
rebuilt. In this case, you may have to run make again to correctly
173
build your desired target. The interpreter executable is built in the
176
If you need an optimized version of Python, you type "make profile-opt"
177
in the top level directory. This will rebuild the interpreter executable
178
using Profile Guided Optimization (PGO). For more details, see the
181
Once you have built a Python interpreter, see the subsections below on
182
testing and installation. If you run into trouble, see the next
185
Previous versions of Python used a manual configuration process that
186
involved editing the file Modules/Setup. While this file still exists
187
and manual configuration is still supported, it is rarely needed any
188
more: almost all modules are automatically built as appropriate under
189
guidance of the setup.py script, which is run by Make after the
190
interpreter has been built.
193
Profile Guided Optimization
194
---------------------------
196
PGO takes advantage of recent versions of the GCC or Clang compilers.
197
If ran, the "profile-opt" rule will do several steps.
199
First, the entire Python directory is cleaned of temporary files that
200
may have resulted in a previous compilation.
202
Then, an instrumented version of the interpreter is built, using suitable
203
compiler flags for each flavour. Note that this is just an intermediary
204
step and the binary resulted after this step is not good for real life
205
workloads, as it has profiling instructions embedded inside.
207
After this instrumented version of the interpreter is built, the Makefile
208
will automatically run a training workload. This is necessary in order to
209
profile the interpreter execution. Note also that any output, both stdout
210
and stderr, that may appear at this step is supressed.
212
Finally, the last step is to rebuild the interpreter, using the information
213
collected in the previous one. The end result will be a Python binary
214
that is optimized and suitable for distribution or production installation.
220
See also the platform specific notes in the next section.
222
If you run into other trouble, see the FAQ
223
(http://www.python.org/doc/faq/) for hints on what can go wrong, and
226
If you rerun the configure script with different options, remove all
227
object files by running "make clean" before rebuilding. Believe it or
228
not, "make clean" sometimes helps to clean up other inexplicable
229
problems as well. Try it before sending in a bug report!
231
If the configure script fails or doesn't seem to find things that
232
should be there, inspect the config.log file.
234
If you get a warning for every file about the -Olimit option being no
235
longer supported, you can ignore it. There's no foolproof way to know
236
whether this option is needed; all we can do is test whether it is
237
accepted without error. On some systems, e.g. older SGI compilers, it
238
is essential for performance (specifically when compiling ceval.c,
239
which has more basic blocks than the default limit of 1000). If the
240
warning bothers you, edit the Makefile to remove "-Olimit 1500" from
243
If you get failures in test_long, or sys.maxint gets set to -1, you
244
are probably experiencing compiler bugs, usually related to
245
optimization. This is a common problem with some versions of gcc, and
246
some vendor-supplied compilers, which can sometimes be worked around
247
by turning off optimization. Consider switching to stable versions
248
(gcc 2.95.2, gcc 3.x, or contact your vendor.)
250
From Python 2.0 onward, all Python C code is ANSI C. Compiling using
251
old K&R-C-only compilers is no longer possible. ANSI C compilers are
252
available for all modern systems, either in the form of updated
253
compilers from the vendor, or one of the free compilers (gcc).
255
If "make install" fails mysteriously during the "compiling the library"
256
step, make sure that you don't have any of the PYTHONPATH or PYTHONHOME
257
environment variables set, as they may interfere with the newly built
258
executable which is compiling the library.
263
A number of systems are not supported in Python 2.7 anymore. Some
264
support code is still present, but will be removed in later versions.
265
If you still need to use current Python versions on these systems,
266
please send a message to python-dev@python.org indicating that you
267
volunteer to support this system. For a more detailed discussion
268
regarding no-longer-supported and resupporting platforms, as well
269
as a list of platforms that became or will be unsupported, see PEP 11.
271
More specifically, the following systems are not supported any
278
- Irix 4 and --with-sgi-dl
280
- Systems defining __d6_pthread_create (configure.ac)
281
- Systems defining PY_PTHREAD_D4, PY_PTHREAD_D6,
282
or PY_PTHREAD_D7 in thread_pthread.h
283
- Systems using --with-dl-dld
284
- Systems using --without-universal-newlines
286
- Systems using --with-wctype-functions
290
Platform specific notes
291
-----------------------
293
(Some of these may no longer apply. If you find you can build Python
294
on these platforms without the special directions mentioned here,
295
submit a documentation bug report to SourceForge (see Bug Reports
296
above) so we can remove them!)
298
Unix platforms: If your vendor still ships (and you still use) Berkeley DB
299
1.85 you will need to edit Modules/Setup to build the bsddb185
300
module and add a line to sitecustomize.py which makes it the
301
default. In Modules/Setup a line like
303
bsddb185 bsddbmodule.c
305
should work. (You may need to add -I, -L or -l flags to direct the
306
compiler and linker to your include files and libraries.)
308
XXX I think this next bit is out of date:
310
64-bit platforms: The modules audioop, and imageop don't work.
311
The setup.py script disables them on 64-bit installations.
312
Don't try to enable them in the Modules/Setup file. They
313
contain code that is quite wordsize sensitive. (If you have a
316
Solaris: When using Sun's C compiler with threads, at least on Solaris
317
2.5.1, you need to add the "-mt" compiler option (the simplest
318
way is probably to specify the compiler with this option as
319
the "CC" environment variable when running the configure
322
When using GCC on Solaris, beware of binutils 2.13 or GCC
323
versions built using it. This mistakenly enables the
324
-zcombreloc option which creates broken shared libraries on
325
Solaris. binutils 2.12 works, and the binutils maintainers
326
are aware of the problem. Binutils 2.13.1 only partially
327
fixed things. It appears that 2.13.2 solves the problem
328
completely. This problem is known to occur with Solaris 2.7
329
and 2.8, but may also affect earlier and later versions of the
332
When the dynamic loader complains about errors finding shared
335
ld.so.1: ./python: fatal: libstdc++.so.5: open failed:
336
No such file or directory
338
you need to first make sure that the library is available on
339
your system. Then, you need to instruct the dynamic loader how
340
to find it. You can choose any of the following strategies:
342
1. When compiling Python, set LD_RUN_PATH to the directories
343
containing missing libraries.
344
2. When running Python, set LD_LIBRARY_PATH to these directories.
345
3. Use crle(8) to extend the search path of the loader.
346
4. Modify the installed GCC specs file, adding -R options into the
349
The complex object fails to compile on Solaris 10 with gcc 3.4 (at
350
least up to 3.4.3). To work around it, define Py_HUGE_VAL as
353
make CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()" -I. -I$(srcdir)/Include'
354
./python setup.py CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()"'
356
Linux: A problem with threads and fork() was tracked down to a bug in
357
the pthreads code in glibc version 2.0.5; glibc version 2.0.7
358
solves the problem. This causes the popen2 test to fail;
359
problem and solution reported by Pablo Bleyer.
361
Red Hat Linux: Red Hat 9 built Python2.2 in UCS-4 mode and hacked
362
Tcl to support it. To compile Python2.3 with Tkinter, you will
363
need to pass --enable-unicode=ucs4 flag to ./configure.
365
There's an executable /usr/bin/python which is Python
366
1.5.2 on most older Red Hat installations; several key Red Hat tools
367
require this version. Python 2.1.x may be installed as
368
/usr/bin/python2. The Makefile installs Python as
369
/usr/local/bin/python, which may or may not take precedence
370
over /usr/bin/python, depending on how you have set up $PATH.
372
FreeBSD 3.x and probably platforms with NCurses that use libmytinfo or
373
similar: When using cursesmodule, the linking is not done in
374
the correct order with the defaults. Remove "-ltermcap" from
375
the readline entry in Setup, and use as curses entry: "curses
376
cursesmodule.c -lmytinfo -lncurses -ltermcap" - "mytinfo" (so
377
called on FreeBSD) should be the name of the auxiliary library
378
required on your platform. Normally, it would be linked
379
automatically, but not necessarily in the correct order.
381
BSDI: BSDI versions before 4.1 have known problems with threads,
382
which can cause strange errors in a number of modules (for
383
instance, the 'test_signal' test script will hang forever.)
384
Turning off threads (with --with-threads=no) or upgrading to
385
BSDI 4.1 solves this problem.
387
DEC Unix: Run configure with --with-dec-threads, or with
388
--with-threads=no if no threads are desired (threads are on by
389
default). When using GCC, it is possible to get an internal
390
compiler error if optimization is used. This was reported for
391
GCC 2.7.2.3 on selectmodule.c. Manually compile the affected
392
file without optimization to solve the problem.
394
DEC Ultrix: compile with GCC to avoid bugs in the native compiler,
395
and pass SHELL=/bin/sh5 to Make when installing.
397
AIX: A complete overhaul of the shared library support is now in
398
place. See Misc/AIX-NOTES for some notes on how it's done.
399
(The optimizer bug reported at this place in previous releases
400
has been worked around by a minimal code change.) If you get
401
errors about pthread_* functions, during compile or during
402
testing, try setting CC to a thread-safe (reentrant) compiler,
403
like "cc_r". For full C++ module support, set CC="xlC_r" (or
404
CC="xlC" without thread support).
406
AIX 5.3: To build a 64-bit version with IBM's compiler, I used the
409
export PATH=/usr/bin:/usr/vacpp/bin
410
./configure --with-gcc="xlc_r -q64" --with-cxx="xlC_r -q64" \
411
--disable-ipv6 AR="ar -X64"
414
HP-UX: When using threading, you may have to add -D_REENTRANT to the
415
OPT variable in the top-level Makefile; reported by Pat Knight,
416
this seems to make a difference (at least for HP-UX 10.20)
417
even though pyconfig.h defines it. This seems unnecessary when
418
using HP/UX 11 and later - threading seems to work "out of the
421
HP-UX ia64: When building on the ia64 (Itanium) platform using HP's
422
compiler, some experience has shown that the compiler's
423
optimiser produces a completely broken version of python
424
(see http://bugs.python.org/814976). To work around this,
425
edit the Makefile and remove -O from the OPT line.
427
To build a 64-bit executable on an Itanium 2 system using HP's
428
compiler, use these environment variables:
433
LDFLAGS="+DD64 -lxnet"
435
and call configure as:
437
./configure --without-gcc
439
then *unset* the environment variables again before running
440
make. (At least one of these flags causes the build to fail
441
if it remains set.) You still have to edit the Makefile and
442
remove -O from the OPT line.
444
HP PA-RISC 2.0: A recent bug report (http://bugs.python.org/546117)
445
suggests that the C compiler in this 64-bit system has bugs
446
in the optimizer that break Python. Compiling without
447
optimization solves the problems.
449
SCO: The following apply to SCO 3 only; Python builds out of the box
450
on SCO 5 (or so we've heard).
452
1) Everything works much better if you add -U__STDC__ to the
453
defs. This is because all the SCO header files are broken.
454
Anything that isn't mentioned in the C standard is
455
conditionally excluded when __STDC__ is defined.
457
2) Due to the U.S. export restrictions, SCO broke the crypt
458
stuff out into a separate library, libcrypt_i.a so the LIBS
461
LIBS=' -lsocket -lcrypt_i'
463
UnixWare: There are known bugs in the math library of the system, as well as
464
problems in the handling of threads (calling fork in one
465
thread may interrupt system calls in others). Therefore, test_math and
466
tests involving threads will fail until those problems are fixed.
468
QNX: Chris Herborth (chrish@qnx.com) writes:
469
configure works best if you use GNU bash; a port is available on
470
ftp.qnx.com in /usr/free. I used the following process to build,
471
test and install Python 1.5.x under QNX:
473
1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \
474
./configure --verbose --without-gcc --with-libm=""
476
2) edit Modules/Setup to activate everything that makes sense for
477
your system... tested here at QNX with the following modules:
479
array, audioop, binascii, cPickle, cStringIO, cmath,
480
crypt, curses, errno, fcntl, gdbm, grp, imageop,
481
_locale, math, md5, new, operator, parser, pcre,
482
posix, pwd, readline, regex, reop,
483
select, signal, socket, soundex, strop, struct,
484
syslog, termios, time, timing, zlib, audioop, imageop
486
3) make SHELL=/usr/local/bin/bash
488
or, if you feel the need for speed:
490
make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"
492
4) make SHELL=/usr/local/bin/bash test
494
Using GNU readline 2.2 seems to behave strangely, but I
495
think that's a problem with my readline 2.2 port. :-\
497
5) make SHELL=/usr/local/bin/bash install
499
If you get SIGSEGVs while running Python (I haven't yet, but
500
I've only run small programs and the test cases), you're
501
probably running out of stack; the default 32k could be a
502
little tight. To increase the stack size, edit the Makefile
503
to read: LDFLAGS = -N 48k
505
BeOS: See Misc/BeOS-NOTES for notes about compiling/installing
506
Python on BeOS R3 or later. Note that only the PowerPC
507
platform is supported for R3; both PowerPC and x86 are
510
Cray T3E: Mark Hadfield (m.hadfield@niwa.co.nz) writes:
511
Python can be built satisfactorily on a Cray T3E but based on
512
my experience with the NIWA T3E (2002-05-22, version 2.2.1)
513
there are a few bugs and gotchas. For more information see a
514
thread on comp.lang.python in May 2002 entitled "Building
517
1) Use Cray's cc and not gcc. The latter was reported not to
518
work by Konrad Hinsen. It may work now, but it may not.
520
2) To set sys.platform to something sensible, pass the
521
following environment variable to the configure script:
525
2) Run configure with option "--enable-unicode=ucs4".
527
3) The Cray T3E does not support dynamic linking, so extension
528
modules have to be built by adding (or uncommenting) lines
529
in Modules/Setup. The minimum set of modules is
531
posix, new, _sre, unicodedata
533
On NIWA's vanilla T3E system the following have also been
534
included successfully:
536
_codecs, _locale, _socket, _symtable, _testcapi, _weakref
537
array, binascii, cmath, cPickle, crypt, cStringIO, dbm
538
errno, fcntl, grp, math, md5, operator, parser, pcre, pwd
539
regex, rotor, select, struct, strop, syslog, termios
540
time, timing, xreadlines
542
4) Once the python executable and library have been built, make
543
will execute setup.py, which will attempt to build remaining
544
extensions and link them dynamically. Each of these attempts
545
will fail but should not halt the make process. This is
548
5) Running "make test" uses a lot of resources and causes
549
problems on our system. You might want to try running tests
550
singly or in small groups.
552
SGI: SGI's standard "make" utility (/bin/make or /usr/bin/make)
553
does not check whether a command actually changed the file it
554
is supposed to build. This means that whenever you say "make"
555
it will redo the link step. The remedy is to use SGI's much
556
smarter "smake" utility (/usr/sbin/smake), or GNU make. If
557
you set the first line of the Makefile to #!/usr/sbin/smake
558
smake will be invoked by make (likewise for GNU make).
560
WARNING: There are bugs in the optimizer of some versions of
561
SGI's compilers that can cause bus errors or other strange
562
behavior, especially on numerical operations. To avoid this,
563
try building with "make OPT=".
565
OS/2: If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
566
compiler installed, just change into the pc\os2vacpp directory
567
and type NMAKE. Threading and sockets are supported by default
568
in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
570
Reliant UNIX: The thread support does not compile on Reliant UNIX, and
571
there is a (minor) problem in the configure script for that
572
platform as well. This should be resolved in time for a
575
MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in
576
test_re and test_sre due to the small default stack size. If
577
you set the stack size to 2048 before doing a "make test" the
578
failure can be avoided. If you're using the tcsh or csh shells,
579
use "limit stacksize 2048" and for the bash shell (the default
580
as of OSX 10.3), use "ulimit -s 2048".
582
On naked Darwin you may want to add the configure option
583
"--disable-toolbox-glue" to disable the glue code for the Carbon
584
interface modules. The modules themselves are currently only built
585
if you add the --enable-framework option, see below.
587
On a clean OSX /usr/local does not exist. Do a
588
"sudo mkdir -m 775 /usr/local"
589
before you do a make install. It is probably not a good idea to
590
do "sudo make install" which installs everything as superuser,
591
as this may later cause problems when installing distutils-based
594
Some people have reported problems building Python after using "fink"
595
to install additional unix software. Disabling fink (remove all
596
references to /sw from your .profile or .login) should solve this.
598
You may want to try the configure option "--enable-framework"
599
which installs Python as a framework. The location can be set
600
as argument to the --enable-framework option (default
601
/Library/Frameworks). A framework install is probably needed if you
602
want to use any Aqua-based GUI toolkit (whether Tkinter, wxPython,
603
Carbon, Cocoa or anything else).
605
You may also want to try the configure option "--enable-universalsdk"
606
which builds Python as a universal binary with support for the
607
i386 and PPC architetures. This requires Xcode 2.1 or later to build.
609
See Mac/README for more information on framework and
612
Cygwin: With recent (relative to the time of writing, 2001-12-19)
613
Cygwin installations, there are problems with the interaction
614
of dynamic linking and fork(). This manifests itself in build
615
failures during the execution of setup.py.
617
There are two workarounds that both enable Python (albeit
618
without threading support) to build and pass all tests on
619
NT/2000 (and most likely XP as well, though reports of testing
620
on XP would be appreciated).
624
(a) the band-aid fix is to link the _socket module statically
625
rather than dynamically (which is the default).
627
To do this, run "./configure --with-threads=no" including any
628
other options you need (--prefix, etc.). Then in Modules/Setup
632
#_socket socketmodule.c \
633
# -DUSE_SSL -I$(SSL)/include -I$(SSL)/include/openssl \
634
# -L$(SSL)/lib -lssl -lcrypto
636
and remove "local/" from the SSL variable. Finally, just run
639
(b) The "proper" fix is to rebase the Cygwin DLLs to prevent
640
base address conflicts. Details on how to do this can be
641
found in the following mail:
643
http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html
645
It is hoped that a version of this solution will be
646
incorporated into the Cygwin distribution fairly soon.
648
Two additional problems:
650
(1) Threading support should still be disabled due to a known
651
bug in Cygwin pthreads that causes test_threadedtempfile to
654
(2) The _curses module does not build. This is a known
655
Cygwin ncurses problem that should be resolved the next time
656
that this package is released.
658
On older versions of Cygwin, test_poll may hang and test_strftime
661
The situation on 9X/Me is not accurately known at present.
662
Some time ago, there were reports that the following
663
regression tests failed:
669
Due to the test_select hang on 9X/Me, one should run the
670
regression test using the following:
672
make TESTOPTS='-l -x test_select' test
674
News regarding these platforms with more recent Cygwin
675
versions would be appreciated!
677
Windows: When executing Python scripts on the command line using file type
678
associations (i.e. starting "script.py" instead of "python script.py"),
679
redirects may not work unless you set a specific registry key. See
680
the Knowledge Base article <http://support.microsoft.com/kb/321788>.
683
Configuring the bsddb and dbm modules
684
-------------------------------------
686
Beginning with Python version 2.3, the PyBsddb package
687
<http://pybsddb.sf.net/> was adopted into Python as the bsddb package,
688
exposing a set of package-level functions which provide
689
backwards-compatible behavior. Only versions 3.3 through 4.4 of
690
Sleepycat's libraries provide the necessary API, so older versions
691
aren't supported through this interface. The old bsddb module has
692
been retained as bsddb185, though it is not built by default. Users
693
wishing to use it will have to tweak Modules/Setup to build it. The
694
dbm module will still be built against the Sleepycat libraries if
695
other preferred alternatives (ndbm, gdbm) are not found.
697
Building the sqlite3 module
698
---------------------------
700
To build the sqlite3 module, you'll need the sqlite3 or libsqlite3
701
packages installed, including the header files. Many modern operating
702
systems distribute the headers in a separate package to the library -
703
often it will be the same name as the main package, but with a -dev or
706
The version of pysqlite2 that's including in Python needs sqlite3 3.0.8
707
or later. setup.py attempts to check that it can find a correct version.
712
As of Python 2.0, threads are enabled by default. If you wish to
713
compile without threads, or if your thread support is broken, pass the
714
--with-threads=no switch to configure. Unfortunately, on some
715
platforms, additional compiler and/or linker options are required for
716
threads to work properly. Below is a table of those options,
717
collected by Bill Janssen. We would love to automate this process
718
more, but the information below is not enough to write a patch for the
719
configure.ac file, so manual intervention is required. If you patch
720
the configure.ac file and are confident that the patch works, please
721
send in the patch. (Don't bother patching the configure script itself
722
-- it is regenerated each time the configure.ac file changes.)
724
Compiler switches for threads
725
.............................
727
The definition of _REENTRANT should be configured automatically, if
728
that does not work on your system, or if _REENTRANT is defined
729
incorrectly, please report that as a bug.
731
OS/Compiler/threads Switches for use with threads
732
(POSIX is draft 10, DCE is draft 4) compile & link
734
SunOS 5.{1-5}/{gcc,SunPro cc}/solaris -mt
735
SunOS 5.5/{gcc,SunPro cc}/POSIX (nothing)
736
DEC OSF/1 3.x/cc/DCE -threads
737
(butenhof@zko.dec.com)
738
Digital UNIX 4.x/cc/DCE -threads
739
(butenhof@zko.dec.com)
740
Digital UNIX 4.x/cc/POSIX -pthread
741
(butenhof@zko.dec.com)
742
AIX 4.1.4/cc_r/d7 (nothing)
744
AIX 4.1.4/cc_r4/DCE (nothing)
746
IRIX 6.2/cc/POSIX (nothing)
750
Linker (ld) libraries and flags for threads
751
...........................................
753
OS/threads Libraries/switches for use with threads
755
SunOS 5.{1-5}/solaris -lthread
756
SunOS 5.5/POSIX -lpthread
757
DEC OSF/1 3.x/DCE -lpthreads -lmach -lc_r -lc
758
(butenhof@zko.dec.com)
759
Digital UNIX 4.x/DCE -lpthreads -lpthread -lmach -lexc -lc
760
(butenhof@zko.dec.com)
761
Digital UNIX 4.x/POSIX -lpthread -lmach -lexc -lc
762
(butenhof@zko.dec.com)
763
AIX 4.1.4/{draft7,DCE} (nothing)
765
IRIX 6.2/POSIX -lpthread
766
(jph@emilia.engr.sgi.com)
769
Building a shared libpython
770
---------------------------
772
Starting with Python 2.3, the majority of the interpreter can be built
773
into a shared library, which can then be used by the interpreter
774
executable, and by applications embedding Python. To enable this feature,
775
configure with --enable-shared.
777
If you enable this feature, the same object files will be used to create
778
a static library. In particular, the static library will contain object
779
files using position-independent code (PIC) on platforms where PIC flags
780
are needed for the shared library.
783
Configuring additional built-in modules
784
---------------------------------------
786
Starting with Python 2.1, the setup.py script at the top of the source
787
distribution attempts to detect which modules can be built and
788
automatically compiles them. Autodetection doesn't always work, so
789
you can still customize the configuration by editing the Modules/Setup
790
file; but this should be considered a last resort. The rest of this
791
section only applies if you decide to edit the Modules/Setup file.
792
You also need this to enable static linking of certain modules (which
793
is needed to enable profiling on some systems).
795
This file is initially copied from Setup.dist by the configure script;
796
if it does not exist yet, create it by copying Modules/Setup.dist
797
yourself (configure will never overwrite it). Never edit Setup.dist
798
-- always edit Setup or Setup.local (see below). Read the comments in
799
the file for information on what kind of edits are allowed. When you
800
have edited Setup in the Modules directory, the interpreter will
801
automatically be rebuilt the next time you run make (in the toplevel
804
Many useful modules can be built on any Unix system, but some optional
805
modules can't be reliably autodetected. Often the quickest way to
806
determine whether a particular module works or not is to see if it
807
will build: enable it in Setup, then if you get compilation or link
808
errors, disable it -- you're either missing support or need to adjust
809
the compilation and linking parameters for that module.
811
On SGI IRIX, there are modules that interface to many SGI specific
812
system libraries, e.g. the GL library and the audio hardware. These
813
modules will not be built by the setup.py script.
815
In addition to the file Setup, you can also edit the file Setup.local.
816
(the makesetup script processes both). You may find it more
817
convenient to edit Setup.local and leave Setup alone. Then, when
818
installing a new Python version, you can copy your old Setup.local
822
Setting the optimization/debugging options
823
------------------------------------------
825
If you want or need to change the optimization/debugging options for
826
the C compiler, assign to the OPT variable on the toplevel make
827
command; e.g. "make OPT=-g" will build a debugging version of Python
828
on most platforms. The default is OPT=-O; a value for OPT in the
829
environment when the configure script is run overrides this default
830
(likewise for CC; and the initial value for LIBS is used as the base
831
set of libraries to link with).
833
When compiling with GCC, the default value of OPT will also include
834
the -Wall and -Wstrict-prototypes options.
836
Additional debugging code to help debug memory management problems can
837
be enabled by using the --with-pydebug option to the configure script.
839
For flags that change binary compatibility, use the EXTRA_CFLAGS
846
If you want C profiling turned on, the easiest way is to run configure
847
with the CC environment variable to the necessary compiler
848
invocation. For example, on Linux, this works for profiling using
851
CC="gcc -pg" ./configure
853
Note that on Linux, gprof apparently does not work for shared
854
libraries. The Makefile/Setup mechanism can be used to compile and
855
link most extension modules statically.
861
For C coverage checking using gcov, run "make coverage". This will
862
build a Python binary with profiling activated, and a ".gcno" and
863
".gcda" file for every source file compiled with that option. With
864
the built binary, now run the code whose coverage you want to check.
865
Then, you can see coverage statistics for each individual source file
866
by running gcov, e.g.
868
gcov -o Modules zlibmodule
870
This will create a "zlibmodule.c.gcov" file in the current directory
871
containing coverage info for that source file.
873
This works only for source files statically compiled into the
874
executable; use the Makefile/Setup mechanism to compile and link
875
extension modules you want to coverage-check statically.
881
To test the interpreter, type "make test" in the top-level directory.
882
This runs the test set twice (once with no compiled files, once with
883
the compiled files left by the previous test run). The test set
884
produces some output. You can generally ignore the messages about
885
skipped tests due to optional features which can't be imported.
886
If a message is printed about a failed test or a traceback or core
887
dump is produced, something is wrong. On some Linux systems (those
888
that are not yet using glibc 6), test_strftime fails due to a
889
non-standard implementation of strftime() in the C library. Please
890
ignore this, or upgrade to glibc version 6.
892
By default, tests are prevented from overusing resources like disk space and
893
memory. To enable these tests, run "make testall".
895
IMPORTANT: If the tests fail and you decide to mail a bug report,
896
*don't* include the output of "make test". It is useless. Run the
897
failing test manually, as follows:
899
./python Lib/test/regrtest.py -v test_whatever
901
(substituting the top of the source tree for '.' if you built in a
902
different directory). This runs the test in verbose mode.
908
To install the Python binary, library modules, shared library modules
909
(see below), include files, configuration files, and the manual page,
914
This will install all platform-independent files in subdirectories of
915
the directory given with the --prefix option to configure or to the
916
`prefix' Make variable (default /usr/local). All binary and other
917
platform-specific files will be installed in subdirectories if the
918
directory given by --exec-prefix or the `exec_prefix' Make variable
919
(defaults to the --prefix directory) is given.
921
If DESTDIR is set, it will be taken as the root directory of the
922
installation, and files will be installed into $(DESTDIR)$(prefix),
923
$(DESTDIR)$(exec_prefix), etc.
925
All subdirectories created will have Python's version number in their
926
name, e.g. the library modules are installed in
927
"/usr/local/lib/python<version>/" by default, where <version> is the
928
<major>.<minor> release number (e.g. "2.1"). The Python binary is
929
installed as "python<version>" and a hard link named "python" is
930
created. The only file not installed with a version number in its
931
name is the manual page, installed as "/usr/local/man/man1/python.1"
934
If you want to install multiple versions of Python see the section below
935
entitled "Installing multiple versions".
937
The only thing you may have to install manually is the Python mode for
938
Emacs found in Misc/python-mode.el. (But then again, more recent
939
versions of Emacs may already have it.) Follow the instructions that
940
came with Emacs for installation of site-specific files.
942
On Mac OS X, if you have configured Python with --enable-framework, you
943
should use "make frameworkinstall" to do the installation. Note that this
944
installs the Python executable in a place that is not normally on your
945
PATH, you may want to set up a symlink in /usr/local/bin.
948
Installing multiple versions
949
----------------------------
951
On Unix and Mac systems if you intend to install multiple versions of Python
952
using the same installation prefix (--prefix argument to the configure
953
script) you must take care that your primary python executable is not
954
overwritten by the installation of a different version. All files and
955
directories installed using "make altinstall" contain the major and minor
956
version and can thus live side-by-side. "make install" also creates
957
${prefix}/bin/python which refers to ${prefix}/bin/pythonX.Y. If you intend
958
to install multiple versions using the same prefix you must decide which
959
version (if any) is your "primary" version. Install that version using
960
"make install". Install all other versions using "make altinstall".
962
For example, if you want to install Python 2.5, 2.6 and 3.0 with 2.6 being
963
the primary version, you would execute "make install" in your 2.6 build
964
directory and "make altinstall" in the others.
967
Configuration options and variables
968
-----------------------------------
970
Some special cases are handled by passing options to the configure
973
WARNING: if you rerun the configure script with different options, you
974
must run "make clean" before rebuilding. Exceptions to this rule:
975
after changing --prefix or --exec-prefix, all you need to do is remove
978
--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
979
it finds it. If you don't want this, or if this compiler is
980
installed but broken on your platform, pass the option
981
--without-gcc. You can also pass "CC=cc" (or whatever the
982
name of the proper C compiler is) in the environment, but the
983
advantage of using --without-gcc is that this option is
984
remembered by the config.status script for its --recheck
987
--prefix, --exec-prefix: If you want to install the binaries and the
988
Python library somewhere else than in /usr/local/{bin,lib},
989
you can pass the option --prefix=DIRECTORY; the interpreter
990
binary will be installed as DIRECTORY/bin/python and the
991
library files as DIRECTORY/lib/python/*. If you pass
992
--exec-prefix=DIRECTORY (as well) this overrides the
993
installation prefix for architecture-dependent files (like the
994
interpreter binary). Note that --prefix=DIRECTORY also
995
affects the default module search path (sys.path), when
996
Modules/config.c is compiled. Passing make the option
997
prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
998
prefix set at configuration time; this may be more convenient
999
than re-running the configure script if you change your mind
1000
about the install prefix.
1002
--with-readline: This option is no longer supported. GNU
1003
readline is automatically enabled by setup.py when present.
1005
--with-threads: On most Unix systems, you can now use multiple
1006
threads, and support for this is enabled by default. To
1007
disable this, pass --with-threads=no. If the library required
1008
for threads lives in a peculiar place, you can use
1009
--with-thread=DIRECTORY. IMPORTANT: run "make clean" after
1010
changing (either enabling or disabling) this option, or you
1011
will get link errors! Note: for DEC Unix use
1012
--with-dec-threads instead.
1014
--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
1015
supported by the "dl" library by Jack Jansen, which is
1016
ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
1017
This is enabled (after you've ftp'ed and compiled the dl
1018
library) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
1019
is the absolute pathname of the dl library. (Don't bother on
1020
IRIX 5, it already has dynamic linking using SunOS style
1021
shared libraries.) THIS OPTION IS UNSUPPORTED.
1023
--with-dl-dld: Dynamic loading of modules is rumored to be supported
1024
on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
1025
Symmetry (Dynix), and Atari ST. This is done using a
1026
combination of the GNU dynamic loading package
1027
(ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
1028
emulation of the SGI dl library mentioned above (the emulation
1030
ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z). To
1031
enable this, ftp and compile both libraries, then call
1032
configure, passing it the option
1033
--with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
1034
the absolute pathname of the dl emulation library and
1035
DLD_DIRECTORY is the absolute pathname of the GNU dld library.
1036
(Don't bother on SunOS 4 or 5, they already have dynamic
1037
linking using shared libraries.) THIS OPTION IS UNSUPPORTED.
1039
--with-libm, --with-libc: It is possible to specify alternative
1040
versions for the Math library (default -lm) and the C library
1041
(default the empty string) using the options
1042
--with-libm=STRING and --with-libc=STRING, respectively. For
1043
example, if your system requires that you pass -lc_s to the C
1044
compiler to use the shared C library, you can pass
1045
--with-libc=-lc_s. These libraries are passed after all other
1046
libraries, the C library last.
1048
--with-libs='libs': Add 'libs' to the LIBS that the python interpreter
1051
--with-cxx-main=<compiler>: If you plan to use C++ extension modules,
1052
then -- on some platforms -- you need to compile python's main()
1053
function with the C++ compiler. With this option, make will use
1054
<compiler> to compile main() *and* to link the python executable.
1055
It is likely that the resulting executable depends on the C++
1056
runtime library of <compiler>. (The default is --without-cxx-main.)
1058
There are platforms that do not require you to build Python
1059
with a C++ compiler in order to use C++ extension modules.
1060
E.g., x86 Linux with ELF shared binaries and GCC 3.x, 4.x is such
1061
a platform. We recommend that you configure Python
1062
--without-cxx-main on those platforms because a mismatch
1063
between the C++ compiler version used to build Python and to
1064
build a C++ extension module is likely to cause a crash at
1067
The Python installation also stores the variable CXX that
1068
determines, e.g., the C++ compiler distutils calls by default
1069
to build C++ extensions. If you set CXX on the configure command
1070
line to any string of non-zero length, then configure won't
1071
change CXX. If you do not preset CXX but pass
1072
--with-cxx-main=<compiler>, then configure sets CXX=<compiler>.
1073
In all other cases, configure looks for a C++ compiler by
1074
some common names (c++, g++, gcc, CC, cxx, cc++, cl) and sets
1075
CXX to the first compiler it finds. If it does not find any
1076
C++ compiler, then it sets CXX="".
1078
Similarly, if you want to change the command used to link the
1079
python executable, then set LINKCC on the configure command line.
1082
--with-pydebug: Enable additional debugging code to help track down
1083
memory management problems. This allows printing a list of all
1084
live objects when the interpreter terminates.
1086
--with(out)-universal-newlines: enable reading of text files with
1087
foreign newline convention (default: enabled). In other words,
1088
any of \r, \n or \r\n is acceptable as end-of-line character.
1089
If enabled import and execfile will automatically accept any newline
1090
in files. Python code can open a file with open(file, 'U') to
1091
read it in universal newline mode. THIS OPTION IS UNSUPPORTED.
1093
--with-tsc: Profile using the Pentium timestamping counter (TSC).
1095
--with-system-ffi: Build the _ctypes extension module using an ffi
1096
library installed on the system.
1098
--with-dbmliborder=db1:db2:...: Specify the order that backends for the
1099
dbm extension are checked. Valid value is a colon separated string
1100
with the backend names `ndbm', `gdbm' and `bdb'.
1102
Building for multiple architectures (using the VPATH feature)
1103
-------------------------------------------------------------
1105
If your file system is shared between multiple architectures, it
1106
usually is not necessary to make copies of the sources for each
1107
architecture you want to support. If the make program supports the
1108
VPATH feature, you can create an empty build directory for each
1109
architecture, and in each directory run the configure script (on the
1110
appropriate machine with the appropriate options). This creates the
1111
necessary subdirectories and the Makefiles therein. The Makefiles
1112
contain a line VPATH=... which points to a directory containing the
1113
actual sources. (On SGI systems, use "smake -J1" instead of "make" if
1114
you use VPATH -- don't try gnumake.)
1116
For example, the following is all you need to build a minimal Python
1117
in /usr/tmp/python (assuming ~guido/src/python is the toplevel
1118
directory and you want to build in /usr/tmp/python):
1120
$ mkdir /usr/tmp/python
1121
$ cd /usr/tmp/python
1122
$ ~guido/src/python/configure
1128
Note that configure copies the original Setup file to the build
1129
directory if it finds no Setup file there. This means that you can
1130
edit the Setup file for each architecture independently. For this
1131
reason, subsequent changes to the original Setup file are not tracked
1132
automatically, as they might overwrite local changes. To force a copy
1133
of a changed original Setup file, delete the target Setup file. (The
1134
makesetup script supports multiple input files, so if you want to be
1135
fancy you can change the rules to create an empty Setup.local if it
1136
doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
1137
however this assumes that you only need to add modules.)
1139
Also note that you can't use a workspace for VPATH and non VPATH builds. The
1140
object files left behind by one version confuses the other.
1143
Building on non-UNIX systems
1144
----------------------------
1146
For Windows (2000/NT/ME/98/95), assuming you have MS VC++ 7.1, the
1147
project files are in PCbuild, the workspace is pcbuild.dsw. See
1148
PCbuild\readme.txt for detailed instructions.
1150
For other non-Unix Windows compilers, in particular MS VC++ 6.0 and
1151
for OS/2, enter the directory "PC" and read the file "readme.txt".
1153
For the Mac, a separate source distribution will be made available,
1154
for use with the CodeWarrior compiler. If you are interested in Mac
1155
development, join the PythonMac Special Interest Group
1156
(http://www.python.org/sigs/pythonmac-sig/, or send email to
1157
pythonmac-sig-request@python.org).
1159
Of course, there are also binary distributions available for these
1160
platforms -- see http://www.python.org/.
1162
To port Python to a new non-UNIX system, you will have to fake the
1163
effect of running the configure script manually (for Mac and PC, this
1164
has already been done for you). A good start is to copy the file
1165
pyconfig.h.in to pyconfig.h and edit the latter to reflect the actual
1166
configuration of your system. Most symbols must simply be defined as
1167
1 only if the corresponding feature is present and can be left alone
1168
otherwise; however the *_t type symbols must be defined as some
1169
variant of int if they need to be defined at all.
1171
For all platforms, it's important that the build arrange to define the
1172
preprocessor symbol NDEBUG on the compiler command line in a release
1173
build of Python (else assert() calls remain in the code, hurting
1174
release-build performance). The Unix, Windows and Mac builds already
1178
Miscellaneous issues
1179
====================
1184
There's an excellent Emacs editing mode for Python code; see the file
1185
Misc/python-mode.el. Originally written by the famous Tim Peters, it is now
1186
maintained by the equally famous Barry Warsaw. The latest version, along with
1187
various other contributed Python-related Emacs goodies, is online at
1188
http://launchpad.net/python-mode/.
1194
The setup.py script automatically configures this when it detects a
1195
usable Tcl/Tk installation. This requires Tcl/Tk version 8.0 or
1198
For more Tkinter information, see the Tkinter Resource page:
1199
http://www.python.org/topics/tkinter/
1201
There are demos in the Demo/tkinter directory.
1203
Note that there's a Python module called "Tkinter" (capital T) which
1204
lives in Lib/lib-tk/Tkinter.py, and a C module called "_tkinter"
1205
(lower case t and leading underscore) which lives in
1206
Modules/_tkinter.c. Demos and normal Tk applications import only the
1207
Python Tkinter module -- only the latter imports the C _tkinter
1208
module. In order to find the C _tkinter module, it must be compiled
1209
and linked into the Python interpreter -- the setup.py script does
1210
this. In order to find the Python Tkinter module, sys.path must be
1211
set correctly -- normal installation takes care of this.
1214
Distribution structure
1215
----------------------
1217
Most subdirectories have their own README files. Most files have
1220
Demo/ Demonstration scripts, modules and programs
1221
Doc/ Documentation sources (reStructuredText)
1222
Grammar/ Input for the parser generator
1223
Include/ Public header files
1224
LICENSE Licensing information
1225
Lib/ Python library modules
1226
Mac/ Macintosh specific resources
1227
Makefile.pre.in Source from which config.status creates the Makefile.pre
1228
Misc/ Miscellaneous useful files
1229
Modules/ Implementation of most built-in modules
1230
Objects/ Implementation of most built-in object types
1231
PC/ Files specific to PC ports (DOS, Windows, OS/2)
1232
PCbuild/ Build directory for Microsoft Visual C++
1233
Parser/ The parser and tokenizer and their input handling
1234
Python/ The byte-compiler and interpreter
1235
README The file you're reading now
1236
RISCOS/ Files specific to RISC OS port
1237
Tools/ Some useful programs written in Python
1238
pyconfig.h.in Source from which pyconfig.h is created (GNU autoheader output)
1239
configure Configuration shell script (GNU autoconf output)
1240
configure.ac Configuration specification (input for GNU autoconf)
1241
install-sh Shell script used to install files
1242
setup.py Python script used to build extension modules
1244
The following files will (may) be created in the toplevel directory by
1245
the configuration and build processes:
1247
Makefile Build rules
1248
Makefile.pre Build rules before running Modules/makesetup
1249
buildno Keeps track of the build number
1250
config.cache Cache of configuration variables
1251
pyconfig.h Configuration header
1252
config.log Log from last configure run
1253
config.status Status from last run of the configure script
1254
getbuildinfo.o Object file from Modules/getbuildinfo.c
1255
libpython<version>.a The library archive
1256
python The executable interpreter
1257
reflog.txt Output from running the regression suite with the -R flag
1258
tags, TAGS Tags files for vi and Emacs
1265
--Guido van Rossum (home page: http://www.python.org/~guido/)
added
removed
python/README.txt
