1 This is Python version 2.6.1

     2 ============================

     3 

     4 Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008

     5 Python Software Foundation.

     6 All rights reserved.

     7 

     8 Copyright (c) 2000 BeOpen.com.

     9 All rights reserved.

    10 

    11 Copyright (c) 1995-2001 Corporation for National Research Initiatives.

    12 All rights reserved.

    13 

    14 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.

    15 All rights reserved.

    16 

    17 

    18 License information

    19 -------------------

    20 

    21 See the file "LICENSE" for information on the history of this

    22 software, terms & conditions for usage, and a DISCLAIMER OF ALL

    23 WARRANTIES.

    24 

    25 This Python distribution contains no GNU General Public Licensed

    26 (GPLed) code so it may be used in proprietary projects just like prior

    27 Python distributions.  There are interfaces to some GNU code but these

    28 are entirely optional.

    29 

    30 All trademarks referenced herein are property of their respective

    31 holders.

    32 

    33 

    34 What's new in this release?

    35 ---------------------------

    36 

    37 See the file "Misc/NEWS".

    38 

    39 

    40 If you don't read instructions

    41 ------------------------------

    42 

    43 Congratulations on getting this far. :-)

    44 

    45 To start building right away (on UNIX): type "./configure" in the

    46 current directory and when it finishes, type "make".  This creates an

    47 executable "./python"; to install in /usr/local, first do "su root"

    48 and then "make install".

    49 

    50 The section `Build instructions' below is still recommended reading.

    51 

    52 

    53 What is Python anyway?

    54 ----------------------

    55 

    56 Python is an interpreted, interactive object-oriented programming

    57 language suitable (amongst other uses) for distributed application

    58 development, scripting, numeric computing and system testing.  Python

    59 is often compared to Tcl, Perl, Java, JavaScript, Visual Basic or

    60 Scheme.  To find out more about what Python can do for you, point your

    61 browser to http://www.python.org/.

    62 

    63 

    64 How do I learn Python?

    65 ----------------------

    66 

    67 The official tutorial is still a good place to start; see

    68 http://docs.python.org/ for online and downloadable versions, as well

    69 as a list of other introductions, and reference documentation.

    70 

    71 There's a quickly growing set of books on Python.  See

    72 http://wiki.python.org/moin/PythonBooks for a list.

    73 

    74 

    75 Documentation

    76 -------------

    77 

    78 All documentation is provided online in a variety of formats.  In

    79 order of importance for new users: Tutorial, Library Reference,

    80 Language Reference, Extending & Embedding, and the Python/C API.  The

    81 Library Reference is especially of immense value since much of

    82 Python's power is described there, including the built-in data types

    83 and functions!

    84 

    85 All documentation is also available online at the Python web site

    86 (http://docs.python.org/, see below).  It is available online for occasional

    87 reference, or can be downloaded in many formats for faster access.  The

    88 documentation is downloadable in HTML, PostScript, PDF, LaTeX, and

    89 reStructuredText (2.6+) formats; the LaTeX and reStructuredText versions are

    90 primarily for documentation authors, translators, and people with special

    91 formatting requirements.

    92 

    93 

    94 Web sites

    95 ---------

    96 

    97 New Python releases and related technologies are published at

    98 http://www.python.org/.  Come visit us!

    99 

   100 There's also a Python community web site at

   101 http://starship.python.net/.

   102 

   103 

   104 Newsgroups and Mailing Lists

   105 ----------------------------

   106 

   107 Read comp.lang.python, a high-volume discussion newsgroup about

   108 Python, or comp.lang.python.announce, a low-volume moderated newsgroup

   109 for Python-related announcements.  These are also accessible as

   110 mailing lists: see http://www.python.org/community/lists.html for an

   111 overview of these and many other Python-related mailing lists.

   112 

   113 Archives are accessible via the Google Groups Usenet archive; see

   114 http://groups.google.com/.  The mailing lists are also archived, see

   115 http://www.python.org/community/lists.html for details.

   116 

   117 

   118 Bug reports

   119 -----------

   120 

   121 To report or search for bugs, please use the Python Bug

   122 Tracker at http://bugs.python.org.

   123 

   124 

   125 Patches and contributions

   126 -------------------------

   127 

   128 To submit a patch or other contribution, please use the Python Patch

   129 Manager at http://bugs.python.org.  Guidelines

   130 for patch submission may be found at http://www.python.org/dev/patches/.

   131 

   132 If you have a proposal to change Python, you may want to send an email to the

   133 comp.lang.python or python-ideas mailing lists for inital feedback. A Python

   134 Enhancement Proposal (PEP) may be submitted if your idea gains ground. All

   135 current PEPs, as well as guidelines for submitting a new PEP, are listed at

   136 http://www.python.org/dev/peps/.

   137 

   138 

   139 Questions

   140 ---------

   141 

   142 For help, if you can't find it in the manuals or on the web site, it's

   143 best to post to the comp.lang.python or the Python mailing list (see

   144 above).  If you specifically don't want to involve the newsgroup or

   145 mailing list, send questions to help@python.org (a group of volunteers

   146 who answer questions as they can).  The newsgroup is the most

   147 efficient way to ask public questions.

   148 

   149 

   150 Build instructions

   151 ==================

   152 

   153 Before you can build Python, you must first configure it.

   154 Fortunately, the configuration and build process has been automated

   155 for Unix and Linux installations, so all you usually have to do is

   156 type a few commands and sit back.  There are some platforms where

   157 things are not quite as smooth; see the platform specific notes below.

   158 If you want to build for multiple platforms sharing the same source

   159 tree, see the section on VPATH below.

   160 

   161 Start by running the script "./configure", which determines your

   162 system configuration and creates the Makefile.  (It takes a minute or

   163 two -- please be patient!)  You may want to pass options to the

   164 configure script -- see the section below on configuration options and

   165 variables.  When it's done, you are ready to run make.

   166 

   167 To build Python, you normally type "make" in the toplevel directory.

   168 If you have changed the configuration, the Makefile may have to be

   169 rebuilt.  In this case you may have to run make again to correctly

   170 build your desired target.  The interpreter executable is built in the

   171 top level directory.

   172 

   173 Once you have built a Python interpreter, see the subsections below on

   174 testing and installation.  If you run into trouble, see the next

   175 section.

   176 

   177 Previous versions of Python used a manual configuration process that

   178 involved editing the file Modules/Setup.  While this file still exists

   179 and manual configuration is still supported, it is rarely needed any

   180 more: almost all modules are automatically built as appropriate under

   181 guidance of the setup.py script, which is run by Make after the

   182 interpreter has been built.

   183 

   184 

   185 Troubleshooting

   186 ---------------

   187 

   188 See also the platform specific notes in the next section.

   189 

   190 If you run into other trouble, see the FAQ

   191 (http://www.python.org/doc/faq) for hints on what can go wrong, and

   192 how to fix it.

   193 

   194 If you rerun the configure script with different options, remove all

   195 object files by running "make clean" before rebuilding.  Believe it or

   196 not, "make clean" sometimes helps to clean up other inexplicable

   197 problems as well.  Try it before sending in a bug report!

   198 

   199 If the configure script fails or doesn't seem to find things that

   200 should be there, inspect the config.log file.

   201 

   202 If you get a warning for every file about the -Olimit option being no

   203 longer supported, you can ignore it.  There's no foolproof way to know

   204 whether this option is needed; all we can do is test whether it is

   205 accepted without error.  On some systems, e.g. older SGI compilers, it

   206 is essential for performance (specifically when compiling ceval.c,

   207 which has more basic blocks than the default limit of 1000).  If the

   208 warning bothers you, edit the Makefile to remove "-Olimit 1500" from

   209 the OPT variable.

   210 

   211 If you get failures in test_long, or sys.maxint gets set to -1, you

   212 are probably experiencing compiler bugs, usually related to

   213 optimization.  This is a common problem with some versions of gcc, and

   214 some vendor-supplied compilers, which can sometimes be worked around

   215 by turning off optimization.  Consider switching to stable versions

   216 (gcc 2.95.2, gcc 3.x, or contact your vendor.)

   217 

   218 From Python 2.0 onward, all Python C code is ANSI C.  Compiling using

   219 old K&R-C-only compilers is no longer possible.  ANSI C compilers are

   220 available for all modern systems, either in the form of updated

   221 compilers from the vendor, or one of the free compilers (gcc).

   222 

   223 If "make install" fails mysteriously during the "compiling the library"

   224 step, make sure that you don't have any of the PYTHONPATH or PYTHONHOME

   225 environment variables set, as they may interfere with the newly built

   226 executable which is compiling the library.

   227 

   228 Unsupported systems

   229 -------------------

   230 

   231 A number of features are not supported in Python 2.5 anymore. Some

   232 support code is still present, but will be removed in Python 2.6. 

   233 If you still need to use current Python versions on these systems,

   234 please send a message to python-dev@python.org indicating that you

   235 volunteer to support this system. For a more detailed discussion 

   236 regarding no-longer-supported and resupporting platforms, as well

   237 as a list of platforms that became or will be unsupported, see PEP 11.

   238 

   239 More specifically, the following systems are not supported any

   240 longer:

   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 

   255 The following systems are still supported in Python 2.5, but

   256 support will be dropped in 2.6:

   257 - Systems using --with-wctype-functions

   258 - Win9x, WinME

   259 

   260 Warning on install in Windows 98 and Windows Me

   261 -----------------------------------------------

   262 

   263 Following Microsoft's closing of Extended Support for

   264 Windows 98/ME (July 11, 2006), Python 2.6 will stop

   265 supporting these platforms. Python development and

   266 maintainability becomes easier (and more reliable) when

   267 platform specific code targeting OSes with few users

   268 and no dedicated expert developers is taken out. The

   269 vendor also warns that the OS versions listed above

   270 "can expose customers to security risks" and recommends

   271 upgrade.

   272 

   273 Platform specific notes

   274 -----------------------

   275 

   276 (Some of these may no longer apply.  If you find you can build Python

   277 on these platforms without the special directions mentioned here,

   278 submit a documentation bug report to SourceForge (see Bug Reports

   279 above) so we can remove them!)

   280 

   281 Unix 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 

   291 XXX I think this next bit is out of date:

   292 

   293 64-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 

   299 Solaris: 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 

   339 Linux:  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 

   344 Red 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 

   355 FreeBSD 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 

   364 BSDI:   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 

   370 DEC 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 

   377 DEC Ultrix: compile with GCC to avoid bugs in the native compiler,

   378         and pass SHELL=/bin/sh5 to Make when installing.

   379 

   380 AIX:    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 

   389 AIX 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 

   397 HP-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 

   404 HP-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 

   427 HP 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 

   432 SCO:    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 

   446 UnixWare: 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 

   451 QNX:    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 

   488 BeOS:   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 

   493 Cray 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 

   535 SGI:    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 

   548 OS/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 

   553 Monterey (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 

   561 Reliant 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 

   566 MacOSX: 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 

   603 Cygwin: 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 

   668 AtheOS: Official support has been stopped as of Python 2.6.  All code will be

   669         removed in Python 2.7 unless a maintainer steps forward for this

   670         platform.

   671 

   672         From Octavian Cerna <tavy at ylabs.com>:

   673 

   674         Before building:

   675 

   676             Make sure you have shared versions of the libraries you

   677             want to use with Python. You will have to compile them

   678             yourself, or download precompiled packages.

   679 

   680             Recommended libraries:

   681 

   682                 ncurses-4.2

   683                 readline-4.2a

   684                 zlib-1.1.4

   685 

   686         Build:

   687 

   688             $ ./configure --prefix=/usr/python

   689             $ make

   690 

   691             Python is always built as a shared library, otherwise

   692             dynamic loading would not work.

   693 

   694         Testing:

   695 

   696             $ make test

   697 

   698         Install:

   699 

   700             # make install

   701             # pkgmanager -a /usr/python

   702 

   703 

   704         AtheOS issues:

   705 

   706             - large file support: due to a stdio bug in glibc/libio,

   707               access to large files may not work correctly.  fseeko()

   708               tries to seek to a negative offset.  ftello() returns a

   709               negative offset, it looks like a 32->64bit

   710               sign-extension issue.  The lowlevel functions (open,

   711               lseek, etc) are OK.

   712             - sockets: AF_UNIX is defined in the C library and in

   713               Python, but not implemented in the system.

   714             - select: poll is available in the C library, but does not

   715               work (It does not return POLLNVAL for bad fds and

   716               hangs).

   717             - posix: statvfs and fstatvfs always return ENOSYS.

   718             - disabled modules:

   719                 - mmap: not yet implemented in AtheOS

   720                 - nis: broken (on an unconfigured system

   721                   yp_get_default_domain() returns junk instead of

   722                   error)

   723                 - dl: dynamic loading doesn't work via dlopen()

   724                 - resource: getrimit and setrlimit are not yet

   725                   implemented

   726 

   727             - if you are getting segmentation faults, you probably are

   728               low on memory.  AtheOS doesn't handle very well an

   729               out-of-memory condition and simply SEGVs the process.

   730 

   731         Tested on:

   732 

   733             AtheOS-0.3.7

   734             gcc-2.95

   735             binutils-2.10

   736             make-3.78

   737 

   738 

   739 Configuring the bsddb and dbm modules

   740 -------------------------------------

   741 

   742 Beginning with Python version 2.3, the PyBsddb package

   743 <http://pybsddb.sf.net/> was adopted into Python as the bsddb package,

   744 exposing a set of package-level functions which provide

   745 backwards-compatible behavior.  Only versions 3.3 through 4.4 of

   746 Sleepycat's libraries provide the necessary API, so older versions

   747 aren't supported through this interface.  The old bsddb module has

   748 been retained as bsddb185, though it is not built by default.  Users

   749 wishing to use it will have to tweak Modules/Setup to build it.  The

   750 dbm module will still be built against the Sleepycat libraries if

   751 other preferred alternatives (ndbm, gdbm) are not found.

   752 

   753 Building the sqlite3 module

   754 ---------------------------

   755 

   756 To build the sqlite3 module, you'll need the sqlite3 or libsqlite3

   757 packages installed, including the header files. Many modern operating

   758 systems distribute the headers in a separate package to the library -

   759 often it will be the same name as the main package, but with a -dev or

   760 -devel suffix. 

   761 

   762 The version of pysqlite2 that's including in Python needs sqlite3 3.0.8

   763 or later. setup.py attempts to check that it can find a correct version.

   764 

   765 Configuring threads

   766 -------------------

   767 

   768 As of Python 2.0, threads are enabled by default.  If you wish to

   769 compile without threads, or if your thread support is broken, pass the

   770 --with-threads=no switch to configure.  Unfortunately, on some

   771 platforms, additional compiler and/or linker options are required for

   772 threads to work properly.  Below is a table of those options,

   773 collected by Bill Janssen.  We would love to automate this process

   774 more, but the information below is not enough to write a patch for the

   775 configure.in file, so manual intervention is required.  If you patch

   776 the configure.in file and are confident that the patch works, please

   777 send in the patch.  (Don't bother patching the configure script itself

   778 -- it is regenerated each time the configure.in file changes.)

   779 

   780 Compiler switches for threads

   781 .............................

   782 

   783 The definition of _REENTRANT should be configured automatically, if

   784 that does not work on your system, or if _REENTRANT is defined

   785 incorrectly, please report that as a bug.

   786 

   787     OS/Compiler/threads                     Switches for use with threads

   788     (POSIX is draft 10, DCE is draft 4)     compile & link

   789 

   790     SunOS 5.{1-5}/{gcc,SunPro cc}/solaris   -mt

   791     SunOS 5.5/{gcc,SunPro cc}/POSIX         (nothing)

   792     DEC OSF/1 3.x/cc/DCE                    -threads

   793             (butenhof@zko.dec.com)

   794     Digital UNIX 4.x/cc/DCE                 -threads

   795             (butenhof@zko.dec.com)

   796     Digital UNIX 4.x/cc/POSIX               -pthread

   797             (butenhof@zko.dec.com)

   798     AIX 4.1.4/cc_r/d7                       (nothing)

   799             (buhrt@iquest.net)

   800     AIX 4.1.4/cc_r4/DCE                     (nothing)

   801             (buhrt@iquest.net)

   802     IRIX 6.2/cc/POSIX                       (nothing)

   803             (robertl@cwi.nl)

   804 

   805 

   806 Linker (ld) libraries and flags for threads

   807 ...........................................

   808 

   809     OS/threads                          Libraries/switches for use with threads

   810 

   811     SunOS 5.{1-5}/solaris               -lthread

   812     SunOS 5.5/POSIX                     -lpthread

   813     DEC OSF/1 3.x/DCE                   -lpthreads -lmach -lc_r -lc

   814             (butenhof@zko.dec.com)

   815     Digital UNIX 4.x/DCE                -lpthreads -lpthread -lmach -lexc -lc

   816             (butenhof@zko.dec.com)

   817     Digital UNIX 4.x/POSIX              -lpthread -lmach -lexc -lc

   818             (butenhof@zko.dec.com)

   819     AIX 4.1.4/{draft7,DCE}              (nothing)

   820             (buhrt@iquest.net)

   821     IRIX 6.2/POSIX                      -lpthread

   822             (jph@emilia.engr.sgi.com)

   823 

   824 

   825 Building a shared libpython

   826 ---------------------------

   827 

   828 Starting with Python 2.3, the majority of the interpreter can be built

   829 into a shared library, which can then be used by the interpreter

   830 executable, and by applications embedding Python. To enable this feature,

   831 configure with --enable-shared.

   832 

   833 If you enable this feature, the same object files will be used to create

   834 a static library.  In particular, the static library will contain object

   835 files using position-independent code (PIC) on platforms where PIC flags

   836 are needed for the shared library.

   837 

   838 

   839 Configuring additional built-in modules

   840 ---------------------------------------

   841 

   842 Starting with Python 2.1, the setup.py script at the top of the source

   843 distribution attempts to detect which modules can be built and

   844 automatically compiles them.  Autodetection doesn't always work, so

   845 you can still customize the configuration by editing the Modules/Setup

   846 file; but this should be considered a last resort.  The rest of this

   847 section only applies if you decide to edit the Modules/Setup file.

   848 You also need this to enable static linking of certain modules (which

   849 is needed to enable profiling on some systems).

   850 

   851 This file is initially copied from Setup.dist by the configure script;

   852 if it does not exist yet, create it by copying Modules/Setup.dist

   853 yourself (configure will never overwrite it).  Never edit Setup.dist

   854 -- always edit Setup or Setup.local (see below).  Read the comments in

   855 the file for information on what kind of edits are allowed.  When you

   856 have edited Setup in the Modules directory, the interpreter will

   857 automatically be rebuilt the next time you run make (in the toplevel

   858 directory).

   859 

   860 Many useful modules can be built on any Unix system, but some optional

   861 modules can't be reliably autodetected.  Often the quickest way to

   862 determine whether a particular module works or not is to see if it

   863 will build: enable it in Setup, then if you get compilation or link

   864 errors, disable it -- you're either missing support or need to adjust

   865 the compilation and linking parameters for that module.

   866 

   867 On SGI IRIX, there are modules that interface to many SGI specific

   868 system libraries, e.g. the GL library and the audio hardware.  These

   869 modules will not be built by the setup.py script.

   870 

   871 In addition to the file Setup, you can also edit the file Setup.local.

   872 (the makesetup script processes both).  You may find it more

   873 convenient to edit Setup.local and leave Setup alone.  Then, when

   874 installing a new Python version, you can copy your old Setup.local

   875 file.

   876 

   877 

   878 Setting the optimization/debugging options

   879 ------------------------------------------

   880 

   881 If you want or need to change the optimization/debugging options for

   882 the C compiler, assign to the OPT variable on the toplevel make

   883 command; e.g. "make OPT=-g" will build a debugging version of Python

   884 on most platforms.  The default is OPT=-O; a value for OPT in the

   885 environment when the configure script is run overrides this default

   886 (likewise for CC; and the initial value for LIBS is used as the base

   887 set of libraries to link with).

   888 

   889 When compiling with GCC, the default value of OPT will also include

   890 the -Wall and -Wstrict-prototypes options.

   891 

   892 Additional debugging code to help debug memory management problems can

   893 be enabled by using the --with-pydebug option to the configure script.

   894 

   895 For flags that change binary compatibility, use the EXTRA_CFLAGS

   896 variable.

   897 

   898 

   899 Profiling

   900 ---------

   901 

   902 If you want C profiling turned on, the easiest way is to run configure

   903 with the CC environment variable to the necessary compiler

   904 invocation.  For example, on Linux, this works for profiling using

   905 gprof(1):

   906 

   907     CC="gcc -pg" ./configure

   908 

   909 Note that on Linux, gprof apparently does not work for shared

   910 libraries.  The Makefile/Setup mechanism can be used to compile and

   911 link most extension modules statically.

   912 

   913 

   914 Coverage checking

   915 -----------------

   916 

   917 For C coverage checking using gcov, run "make coverage".  This will

   918 build a Python binary with profiling activated, and a ".gcno" and

   919 ".gcda" file for every source file compiled with that option.  With

   920 the built binary, now run the code whose coverage you want to check.

   921 Then, you can see coverage statistics for each individual source file

   922 by running gcov, e.g.

   923 

   924     gcov -o Modules zlibmodule

   925 

   926 This will create a "zlibmodule.c.gcov" file in the current directory

   927 containing coverage info for that source file.

   928 

   929 This works only for source files statically compiled into the

   930 executable; use the Makefile/Setup mechanism to compile and link

   931 extension modules you want to coverage-check statically.

   932 

   933 

   934 Testing

   935 -------

   936 

   937 To test the interpreter, type "make test" in the top-level directory.

   938 This runs the test set twice (once with no compiled files, once with

   939 the compiled files left by the previous test run).  The test set

   940 produces some output.  You can generally ignore the messages about

   941 skipped tests due to optional features which can't be imported.

   942 If a message is printed about a failed test or a traceback or core

   943 dump is produced, something is wrong.  On some Linux systems (those

   944 that are not yet using glibc 6), test_strftime fails due to a

   945 non-standard implementation of strftime() in the C library. Please

   946 ignore this, or upgrade to glibc version 6.

   947 

   948 IMPORTANT: If the tests fail and you decide to mail a bug report,

   949 *don't* include the output of "make test".  It is useless.  Run the

   950 failing test manually, as follows:

   951 

   952         ./python ./Lib/test/test_whatever.py

   953 

   954 (substituting the top of the source tree for '.' if you built in a

   955 different directory).  This runs the test in verbose mode.

   956 

   957 

   958 Installing

   959 ----------

   960 

   961 To install the Python binary, library modules, shared library modules

   962 (see below), include files, configuration files, and the manual page,

   963 just type

   964 

   965         make install

   966 

   967 This will install all platform-independent files in subdirectories of

   968 the directory given with the --prefix option to configure or to the

   969 `prefix' Make variable (default /usr/local).  All binary and other

   970 platform-specific files will be installed in subdirectories if the

   971 directory given by --exec-prefix or the `exec_prefix' Make variable

   972 (defaults to the --prefix directory) is given.

   973 

   974 If DESTDIR is set, it will be taken as the root directory of the

   975 installation, and files will be installed into $(DESTDIR)$(prefix),

   976 $(DESTDIR)$(exec_prefix), etc.

   977 

   978 All subdirectories created will have Python's version number in their

   979 name, e.g. the library modules are installed in

   980 "/usr/local/lib/python<version>/" by default, where <version> is the

   981 <major>.<minor> release number (e.g. "2.1").  The Python binary is

   982 installed as "python<version>" and a hard link named "python" is

   983 created.  The only file not installed with a version number in its

   984 name is the manual page, installed as "/usr/local/man/man1/python.1"

   985 by default.

   986 

   987 If you want to install multiple versions of Python see the section below

   988 entitled "Installing multiple versions".

   989 

   990 The only thing you may have to install manually is the Python mode for

   991 Emacs found in Misc/python-mode.el.  (But then again, more recent

   992 versions of Emacs may already have it.)  Follow the instructions that

   993 came with Emacs for installation of site-specific files.

   994 

   995 On Mac OS X, if you have configured Python with --enable-framework, you

   996 should use "make frameworkinstall" to do the installation. Note that this

   997 installs the Python executable in a place that is not normally on your

   998 PATH, you may want to set up a symlink in /usr/local/bin.

   999 

  1000 

  1001 Installing multiple versions

  1002 ----------------------------

  1003 

  1004 On Unix and Mac systems if you intend to install multiple versions of Python

  1005 using the same installation prefix (--prefix argument to the configure

  1006 script) you must take care that your primary python executable is not

  1007 overwritten by the installation of a different versio.  All files and

  1008 directories installed using "make altinstall" contain the major and minor

  1009 version and can thus live side-by-side.  "make install" also creates

  1010 ${prefix}/bin/python which refers to ${prefix}/bin/pythonX.Y.  If you intend

  1011 to install multiple versions using the same prefix you must decide which

  1012 version (if any) is your "primary" version.  Install that version using

  1013 "make install".  Install all other versions using "make altinstall".

  1014 

  1015 For example, if you want to install Python 2.5, 2.6 and 3.0 with 2.6 being

  1016 the primary version, you would execute "make install" in your 2.6 build

  1017 directory and "make altinstall" in the others.

  1018 

  1019 

  1020 Configuration options and variables

  1021 -----------------------------------

  1022 

  1023 Some special cases are handled by passing options to the configure

  1024 script.

  1025 

  1026 WARNING: if you rerun the configure script with different options, you

  1027 must run "make clean" before rebuilding.  Exceptions to this rule:

  1028 after changing --prefix or --exec-prefix, all you need to do is remove

  1029 Modules/getpath.o.

  1030 

  1031 --with(out)-gcc: The configure script uses gcc (the GNU C compiler) if

  1032         it finds it.  If you don't want this, or if this compiler is

  1033         installed but broken on your platform, pass the option

  1034         --without-gcc.  You can also pass "CC=cc" (or whatever the

  1035         name of the proper C compiler is) in the environment, but the

  1036         advantage of using --without-gcc is that this option is

  1037         remembered by the config.status script for its --recheck

  1038         option.

  1039 

  1040 --prefix, --exec-prefix: If you want to install the binaries and the

  1041         Python library somewhere else than in /usr/local/{bin,lib},

  1042         you can pass the option --prefix=DIRECTORY; the interpreter

  1043         binary will be installed as DIRECTORY/bin/python and the

  1044         library files as DIRECTORY/lib/python/*.  If you pass

  1045         --exec-prefix=DIRECTORY (as well) this overrides the

  1046         installation prefix for architecture-dependent files (like the

  1047         interpreter binary).  Note that --prefix=DIRECTORY also

  1048         affects the default module search path (sys.path), when

  1049         Modules/config.c is compiled.  Passing make the option

  1050         prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the

  1051         prefix set at configuration time; this may be more convenient

  1052         than re-running the configure script if you change your mind

  1053         about the install prefix.

  1054 

  1055 --with-readline: This option is no longer supported.  GNU

  1056         readline is automatically enabled by setup.py when present.

  1057 

  1058 --with-threads: On most Unix systems, you can now use multiple

  1059         threads, and support for this is enabled by default.  To

  1060         disable this, pass --with-threads=no.  If the library required

  1061         for threads lives in a peculiar place, you can use

  1062         --with-thread=DIRECTORY.  IMPORTANT: run "make clean" after

  1063         changing (either enabling or disabling) this option, or you

  1064         will get link errors!  Note: for DEC Unix use

  1065         --with-dec-threads instead.

  1066 

  1067 --with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is

  1068         supported by the "dl" library by Jack Jansen, which is

  1069         ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.

  1070         This is enabled (after you've ftp'ed and compiled the dl

  1071         library) by passing --with-sgi-dl=DIRECTORY where DIRECTORY

  1072         is the absolute pathname of the dl library.  (Don't bother on

  1073         IRIX 5, it already has dynamic linking using SunOS style

  1074         shared libraries.)  THIS OPTION IS UNSUPPORTED.

  1075 

  1076 --with-dl-dld: Dynamic loading of modules is rumored to be supported

  1077         on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent

  1078         Symmetry (Dynix), and Atari ST.  This is done using a

  1079         combination of the GNU dynamic loading package

  1080         (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an

  1081         emulation of the SGI dl library mentioned above (the emulation

  1082         can be found at

  1083         ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z).  To

  1084         enable this, ftp and compile both libraries, then call

  1085         configure, passing it the option

  1086         --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is

  1087         the absolute pathname of the dl emulation library and

  1088         DLD_DIRECTORY is the absolute pathname of the GNU dld library.

  1089         (Don't bother on SunOS 4 or 5, they already have dynamic

  1090         linking using shared libraries.)  THIS OPTION IS UNSUPPORTED.

  1091 

  1092 --with-libm, --with-libc: It is possible to specify alternative

  1093         versions for the Math library (default -lm) and the C library

  1094         (default the empty string) using the options

  1095         --with-libm=STRING and --with-libc=STRING, respectively.  For

  1096         example, if your system requires that you pass -lc_s to the C

  1097         compiler to use the shared C library, you can pass

  1098         --with-libc=-lc_s. These libraries are passed after all other

  1099         libraries, the C library last.

  1100 

  1101 --with-libs='libs': Add 'libs' to the LIBS that the python interpreter

  1102         is linked against.

  1103 

  1104 --with-cxx-main=<compiler>: If you plan to use C++ extension modules,

  1105         then -- on some platforms -- you need to compile python's main()

  1106         function with the C++ compiler. With this option, make will use

  1107         <compiler> to compile main() *and* to link the python executable.

  1108         It is likely that the resulting executable depends on the C++

  1109         runtime library of <compiler>. (The default is --without-cxx-main.)

  1110 

  1111         There are platforms that do not require you to build Python

  1112         with a C++ compiler in order to use C++ extension modules.

  1113         E.g., x86 Linux with ELF shared binaries and GCC 3.x, 4.x is such

  1114         a platform. We recommend that you configure Python

  1115         --without-cxx-main on those platforms because a mismatch

  1116         between the C++ compiler version used to build Python and to

  1117         build a C++ extension module is likely to cause a crash at

  1118         runtime.

  1119 

  1120         The Python installation also stores the variable CXX that

  1121         determines, e.g., the C++ compiler distutils calls by default

  1122         to build C++ extensions. If you set CXX on the configure command

  1123         line to any string of non-zero length, then configure won't

  1124         change CXX. If you do not preset CXX but pass

  1125         --with-cxx-main=<compiler>, then configure sets CXX=<compiler>.

  1126         In all other cases, configure looks for a C++ compiler by

  1127         some common names (c++, g++, gcc, CC, cxx, cc++, cl) and sets

  1128         CXX to the first compiler it finds. If it does not find any

  1129         C++ compiler, then it sets CXX="".

  1130 

  1131         Similarly, if you want to change the command used to link the

  1132         python executable, then set LINKCC on the configure command line.

  1133 

  1134 

  1135 --with-pydebug:  Enable additional debugging code to help track down