PageRenderTime 1133ms CodeModel.GetById 192ms app.highlight 347ms RepoModel.GetById 579ms app.codeStats 0ms

/README

http://unladen-swallow.googlecode.com/
#! | 1256 lines | 974 code | 282 blank | 0 comment | 0 complexity | cee2251d191c01a7d5bab51f05aef612 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file