1 This is Python version 2.5.4

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

     3 

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

     5 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

    87 occasional reference, or can be downloaded in many formats for faster

    88 access.  The documentation is available in HTML, PostScript, PDF, and

    89 LaTeX formats; the LaTeX version is primarily for documentation

    90 authors, translators, and people with special formatting requirements.

    91 

    92 Unfortunately, new-style classes (new in Python 2.2) have not yet been

    93 integrated into Python's standard documentation.  A collection of

    94 pointers to what has been written is at:

    95 

    96     http://www.python.org/doc/newstyle.html

    97 

    98 

    99 Web sites

   100 ---------

   101 

   102 New Python releases and related technologies are published at

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

   104 

   105 There's also a Python community web site at

   106 http://starship.python.net/.

   107 

   108 

   109 Newsgroups and Mailing Lists

   110 ----------------------------

   111 

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

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

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

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

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

   117 

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

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

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

   121 

   122 

   123 Bug reports

   124 -----------

   125 

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

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

   128 

   129 

   130 Patches and contributions

   131 -------------------------

   132 

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

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

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

   136 

   137 If you have a proposal to change Python, it's best to submit a Python

   138 Enhancement Proposal (PEP) first.  All current PEPs, as well as

   139 guidelines for submitting a new PEP, are listed at

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

   141 

   142 

   143 Questions

   144 ---------

   145 

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

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

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

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

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

   151 efficient way to ask public questions.

   152 

   153 

   154 Build instructions

   155 ==================

   156 

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

   158 Fortunately, the configuration and build process has been automated

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

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

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

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

   163 tree, see the section on VPATH below.

   164 

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

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

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

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

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

   170 

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

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

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

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

   175 top level directory.

   176 

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

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

   179 section.

   180 

   181 Previous versions of Python used a manual configuration process that

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

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

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

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

   186 interpreter has been built.

   187 

   188 

   189 Troubleshooting

   190 ---------------

   191 

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

   193 

   194 If you run into other trouble, see the FAQ

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

   196 how to fix it.

   197 

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

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

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

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

   202 

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

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

   205 

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

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

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

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

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

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

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

   213 the OPT variable.

   214 

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

   216 are probably experiencing compiler bugs, usually related to

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

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

   219 by turning off optimization.  Consider switching to stable versions

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

   221 

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

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

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

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

   226 

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

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

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

   230 executable which is compiling the library.

   231 

   232 Unsupported systems

   233 -------------------

   234 

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

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

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

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

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

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

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

   242 

   243 More specifically, the following systems are not supported any

   244 longer:

   245 - SunOS 4

   246 - DYNIX

   247 - dgux

   248 - Minix

   249 - NeXT

   250 - Irix 4 and --with-sgi-dl

   251 - Linux 1

   252 - Systems defining __d6_pthread_create (configure.in)

   253 - Systems defining PY_PTHREAD_D4, PY_PTHREAD_D6,

   254   or PY_PTHREAD_D7 in thread_pthread.h

   255 - Systems using --with-dl-dld

   256 - Systems using --without-universal-newlines

   257 - MacOS 9

   258 

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

   260 support will be dropped in 2.6:

   261 - Systems using --with-wctype-functions

   262 - Win9x, WinME

   263 

   264 Warning on install in Windows 98 and Windows Me

   265 -----------------------------------------------

   266 

   267 Following Microsoft's closing of Extended Support for

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

   269 supporting these platforms. Python development and

   270 maintainability becomes easier (and more reliable) when

   271 platform specific code targeting OSes with few users

   272 and no dedicated expert developers is taken out. The

   273 vendor also warns that the OS versions listed above

   274 "can expose customers to security risks" and recommends

   275 upgrade.

   276 

   277 Platform specific notes

   278 -----------------------

   279 

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

   281 on these platforms without the special directions mentioned here,

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

   283 above) so we can remove them!)

   284 

   285 Unix platforms: If your vendor still ships (and you still use) Berkeley DB

   286         1.85 you will need to edit Modules/Setup to build the bsddb185

   287         module and add a line to sitecustomize.py which makes it the

   288         default.  In Modules/Setup a line like

   289 

   290             bsddb185 bsddbmodule.c

   291 

   292         should work.  (You may need to add -I, -L or -l flags to direct the

   293         compiler and linker to your include files and libraries.)

   294 

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

   296 

   297 64-bit platforms: The modules audioop, imageop and rgbimg don't work.

   298         The setup.py script disables them on 64-bit installations.

   299         Don't try to enable them in the Modules/Setup file.  They

   300         contain code that is quite wordsize sensitive.  (If you have a

   301         fix, let us know!)

   302 

   303 Solaris: When using Sun's C compiler with threads, at least on Solaris

   304         2.5.1, you need to add the "-mt" compiler option (the simplest

   305         way is probably to specify the compiler with this option as

   306         the "CC" environment variable when running the configure

   307         script).

   308 

   309         When using GCC on Solaris, beware of binutils 2.13 or GCC

   310         versions built using it.  This mistakenly enables the

   311         -zcombreloc option which creates broken shared libraries on

   312         Solaris.  binutils 2.12 works, and the binutils maintainers

   313         are aware of the problem.  Binutils 2.13.1 only partially

   314         fixed things.  It appears that 2.13.2 solves the problem

   315         completely.  This problem is known to occur with Solaris 2.7

   316         and 2.8, but may also affect earlier and later versions of the

   317         OS.

   318 

   319         When the dynamic loader complains about errors finding shared

   320         libraries, such as

   321 

   322         ld.so.1: ./python: fatal: libstdc++.so.5: open failed:

   323         No such file or directory

   324 

   325         you need to first make sure that the library is available on

   326         your system. Then, you need to instruct the dynamic loader how

   327         to find it. You can choose any of the following strategies:

   328 

   329         1. When compiling Python, set LD_RUN_PATH to the directories

   330            containing missing libraries.

   331         2. When running Python, set LD_LIBRARY_PATH to these directories.

   332         3. Use crle(8) to extend the search path of the loader.

   333         4. Modify the installed GCC specs file, adding -R options into the

   334            *link: section.

   335 

   336         The complex object fails to compile on Solaris 10 with gcc 3.4 (at

   337         least up to 3.4.3).  To work around it, define Py_HUGE_VAL as

   338         HUGE_VAL(), e.g.:

   339 

   340           make CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()" -I. -I$(srcdir)/Include'

   341           ./python setup.py CPPFLAGS='-D"Py_HUGE_VAL=HUGE_VAL()"'

   342 

   343 Linux:  A problem with threads and fork() was tracked down to a bug in

   344         the pthreads code in glibc version 2.0.5; glibc version 2.0.7

   345         solves the problem.  This causes the popen2 test to fail;

   346         problem and solution reported by Pablo Bleyer.

   347 

   348 Red Hat Linux: Red Hat 9 built Python2.2 in UCS-4 mode and hacked

   349         Tcl to support it. To compile Python2.3 with Tkinter, you will

   350         need to pass --enable-unicode=ucs4 flag to ./configure.

   351 

   352         There's an executable /usr/bin/python which is Python

   353         1.5.2 on most older Red Hat installations; several key Red Hat tools

   354         require this version.  Python 2.1.x may be installed as

   355         /usr/bin/python2.  The Makefile installs Python as

   356         /usr/local/bin/python, which may or may not take precedence

   357         over /usr/bin/python, depending on how you have set up $PATH.

   358 

   359 FreeBSD 3.x and probably platforms with NCurses that use libmytinfo or

   360         similar: When using cursesmodule, the linking is not done in

   361         the correct order with the defaults.  Remove "-ltermcap" from

   362         the readline entry in Setup, and use as curses entry: "curses

   363         cursesmodule.c -lmytinfo -lncurses -ltermcap" - "mytinfo" (so

   364         called on FreeBSD) should be the name of the auxiliary library

   365         required on your platform.  Normally, it would be linked

   366         automatically, but not necessarily in the correct order.

   367 

   368 BSDI:   BSDI versions before 4.1 have known problems with threads,

   369         which can cause strange errors in a number of modules (for

   370         instance, the 'test_signal' test script will hang forever.)

   371         Turning off threads (with --with-threads=no) or upgrading to

   372         BSDI 4.1 solves this problem.

   373 

   374 DEC Unix: Run configure with --with-dec-threads, or with

   375         --with-threads=no if no threads are desired (threads are on by

   376         default).  When using GCC, it is possible to get an internal

   377         compiler error if optimization is used.  This was reported for

   378         GCC 2.7.2.3 on selectmodule.c.  Manually compile the affected

   379         file without optimization to solve the problem.

   380 

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

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

   383 

   384 AIX:    A complete overhaul of the shared library support is now in

   385         place.  See Misc/AIX-NOTES for some notes on how it's done.

   386         (The optimizer bug reported at this place in previous releases

   387         has been worked around by a minimal code change.) If you get

   388         errors about pthread_* functions, during compile or during

   389         testing, try setting CC to a thread-safe (reentrant) compiler,

   390         like "cc_r".  For full C++ module support, set CC="xlC_r" (or

   391         CC="xlC" without thread support).

   392 

   393 AIX 5.3: To build a 64-bit version with IBM's compiler, I used the

   394         following:

   395 

   396         export PATH=/usr/bin:/usr/vacpp/bin

   397         ./configure --with-gcc="xlc_r -q64" --with-cxx="xlC_r -q64" \

   398                     --disable-ipv6 AR="ar -X64"

   399         make

   400 

   401 HP-UX:  When using threading, you may have to add -D_REENTRANT to the

   402         OPT variable in the top-level Makefile; reported by Pat Knight,

   403         this seems to make a difference (at least for HP-UX 10.20)

   404         even though pyconfig.h defines it. This seems unnecessary when

   405         using HP/UX 11 and later - threading seems to work "out of the

   406         box".

   407 

   408 HP-UX ia64: When building on the ia64 (Itanium) platform using HP's

   409         compiler, some experience has shown that the compiler's

   410         optimiser produces a completely broken version of python

   411         (see http://www.python.org/sf/814976). To work around this,

   412         edit the Makefile and remove -O from the OPT line.

   413 

   414         To build a 64-bit executable on an Itanium 2 system using HP's

   415         compiler, use these environment variables:

   416 

   417                 CC=cc

   418                 CXX=aCC

   419                 BASECFLAGS="+DD64"

   420                 LDFLAGS="+DD64 -lxnet"

   421 

   422         and call configure as:

   423 

   424                 ./configure --without-gcc

   425 

   426         then *unset* the environment variables again before running

   427         make.  (At least one of these flags causes the build to fail

   428         if it remains set.)  You still have to edit the Makefile and

   429         remove -O from the OPT line.

   430 

   431 HP PA-RISC 2.0: A recent bug report (http://www.python.org/sf/546117)

   432         suggests that the C compiler in this 64-bit system has bugs

   433         in the optimizer that break Python.  Compiling without

   434         optimization solves the problems.

   435 

   436 SCO:    The following apply to SCO 3 only; Python builds out of the box

   437         on SCO 5 (or so we've heard).

   438 

   439         1) Everything works much better if you add -U__STDC__ to the

   440         defs.  This is because all the SCO header files are broken.

   441         Anything that isn't mentioned in the C standard is

   442         conditionally excluded when __STDC__ is defined.

   443 

   444         2) Due to the U.S. export restrictions, SCO broke the crypt

   445         stuff out into a separate library, libcrypt_i.a so the LIBS

   446         needed be set to:

   447 

   448                 LIBS=' -lsocket -lcrypt_i'

   449 

   450 UnixWare: There are known bugs in the math library of the system, as well as

   451         problems in the handling of threads (calling fork in one

   452         thread may interrupt system calls in others). Therefore, test_math and

   453         tests involving threads will fail until those problems are fixed.

   454 

   455 QNX:    Chris Herborth (chrish@qnx.com) writes:

   456         configure works best if you use GNU bash; a port is available on

   457         ftp.qnx.com in /usr/free.  I used the following process to build,

   458         test and install Python 1.5.x under QNX:

   459 

   460         1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \

   461             ./configure --verbose --without-gcc --with-libm=""

   462 

   463         2) edit Modules/Setup to activate everything that makes sense for

   464            your system... tested here at QNX with the following modules:

   465 

   466                 array, audioop, binascii, cPickle, cStringIO, cmath,

   467                 crypt, curses, errno, fcntl, gdbm, grp, imageop,

   468                 _locale, math, md5, new, operator, parser, pcre,

   469                 posix, pwd, readline, regex, reop, rgbimg, rotor,

   470                 select, signal, socket, soundex, strop, struct,

   471                 syslog, termios, time, timing, zlib, audioop, imageop, rgbimg

   472 

   473         3) make SHELL=/usr/local/bin/bash

   474 

   475            or, if you feel the need for speed:

   476 

   477            make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"

   478 

   479         4) make SHELL=/usr/local/bin/bash test

   480 

   481            Using GNU readline 2.2 seems to behave strangely, but I

   482            think that's a problem with my readline 2.2 port.  :-\

   483 

   484         5) make SHELL=/usr/local/bin/bash install

   485 

   486         If you get SIGSEGVs while running Python (I haven't yet, but

   487         I've only run small programs and the test cases), you're

   488         probably running out of stack; the default 32k could be a

   489         little tight.  To increase the stack size, edit the Makefile

   490         to read: LDFLAGS = -N 48k

   491 

   492 BeOS:   See Misc/BeOS-NOTES for notes about compiling/installing

   493         Python on BeOS R3 or later.  Note that only the PowerPC

   494         platform is supported for R3; both PowerPC and x86 are

   495         supported for R4.

   496 

   497 Cray T3E: Mark Hadfield (m.hadfield@niwa.co.nz) writes:

   498         Python can be built satisfactorily on a Cray T3E but based on

   499         my experience with the NIWA T3E (2002-05-22, version 2.2.1)

   500         there are a few bugs and gotchas. For more information see a

   501         thread on comp.lang.python in May 2002 entitled "Building

   502         Python on Cray T3E".

   503 

   504         1) Use Cray's cc and not gcc. The latter was reported not to

   505            work by Konrad Hinsen. It may work now, but it may not.

   506 

   507         2) To set sys.platform to something sensible, pass the

   508            following environment variable to the configure script:

   509 

   510              MACHDEP=unicosmk

   511 

   512         2) Run configure with option "--enable-unicode=ucs4".

   513 

   514         3) The Cray T3E does not support dynamic linking, so extension

   515            modules have to be built by adding (or uncommenting) lines

   516            in Modules/Setup. The minimum set of modules is

   517 

   518              posix, new, _sre, unicodedata

   519 

   520            On NIWA's vanilla T3E system the following have also been

   521            included successfully:

   522 

   523              _codecs, _locale, _socket, _symtable, _testcapi, _weakref

   524              array, binascii, cmath, cPickle, crypt, cStringIO, dbm

   525              errno, fcntl, grp, math, md5, operator, parser, pcre, pwd

   526              regex, rotor, select, struct, strop, syslog, termios

   527              time, timing, xreadlines

   528 

   529         4) Once the python executable and library have been built, make

   530            will execute setup.py, which will attempt to build remaining

   531            extensions and link them dynamically. Each of these attempts

   532            will fail but should not halt the make process. This is

   533            normal.

   534 

   535         5) Running "make test" uses a lot of resources and causes

   536            problems on our system. You might want to try running tests

   537            singly or in small groups.

   538 

   539 SGI:    SGI's standard "make" utility (/bin/make or /usr/bin/make)

   540         does not check whether a command actually changed the file it

   541         is supposed to build.  This means that whenever you say "make"

   542         it will redo the link step.  The remedy is to use SGI's much

   543         smarter "smake" utility (/usr/sbin/smake), or GNU make.  If

   544         you set the first line of the Makefile to #!/usr/sbin/smake

   545         smake will be invoked by make (likewise for GNU make).

   546 

   547         WARNING: There are bugs in the optimizer of some versions of

   548         SGI's compilers that can cause bus errors or other strange

   549         behavior, especially on numerical operations.  To avoid this,

   550         try building with "make OPT=".

   551 

   552 OS/2:   If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++

   553         compiler installed, just change into the pc\os2vacpp directory

   554         and type NMAKE.  Threading and sockets are supported by default

   555         in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.

   556 

   557 Monterey (64-bit AIX): The current Monterey C compiler (Visual Age)

   558         uses the OBJECT_MODE={32|64} environment variable to set the

   559         compilation mode to either 32-bit or 64-bit (32-bit mode is

   560         the default).  Presumably you want 64-bit compilation mode for

   561         this 64-bit OS.  As a result you must first set OBJECT_MODE=64

   562         in your environment before configuring (./configure) or

   563         building (make) Python on Monterey.

   564 

   565 Reliant UNIX: The thread support does not compile on Reliant UNIX, and

   566         there is a (minor) problem in the configure script for that

   567         platform as well.  This should be resolved in time for a

   568         future release.

   569 

   570 MacOSX: The tests will crash on both 10.1 and 10.2 with SEGV in

   571         test_re and test_sre due to the small default stack size.  If

   572         you set the stack size to 2048 before doing a "make test" the

   573         failure can be avoided.  If you're using the tcsh or csh shells,

   574         use "limit stacksize 2048" and for the bash shell (the default

   575         as of OSX 10.3), use "ulimit -s 2048".

   576 

   577         On naked Darwin you may want to add the configure option

   578         "--disable-toolbox-glue" to disable the glue code for the Carbon

   579         interface modules. The modules themselves are currently only built

   580         if you add the --enable-framework option, see below.

   581 

   582         On a clean OSX /usr/local does not exist. Do a

   583         "sudo mkdir -m 775 /usr/local"

   584         before you do a make install. It is probably not a good idea to

   585         do "sudo make install" which installs everything as superuser,

   586         as this may later cause problems when installing distutils-based

   587         additions.

   588 

   589         Some people have reported problems building Python after using "fink"

   590         to install additional unix software. Disabling fink (remove all 

   591         references to /sw from your .profile or .login) should solve this.

   592 

   593         You may want to try the configure option "--enable-framework"

   594         which installs Python as a framework. The location can be set

   595         as argument to the --enable-framework option (default

   596         /Library/Frameworks). A framework install is probably needed if you

   597         want to use any Aqua-based GUI toolkit (whether Tkinter, wxPython,

   598         Carbon, Cocoa or anything else).

   599 

   600 	You may also want to try the configure option "--enable-universalsdk"

   601 	which builds Python as a universal binary with support for the 

   602 	i386 and PPC architectures. This requires Xcode 2.1 or later to build.

   603 

   604         See Mac/OSX/README for more information on framework and 

   605 	universal builds.

   606 

   607 Cygwin: With recent (relative to the time of writing, 2001-12-19)

   608         Cygwin installations, there are problems with the interaction

   609         of dynamic linking and fork().  This manifests itself in build

   610         failures during the execution of setup.py.

   611 

   612         There are two workarounds that both enable Python (albeit

   613         without threading support) to build and pass all tests on

   614         NT/2000 (and most likely XP as well, though reports of testing

   615         on XP would be appreciated).

   616 

   617         The workarounds:

   618 

   619         (a) the band-aid fix is to link the _socket module statically

   620         rather than dynamically (which is the default).

   621 

   622         To do this, run "./configure --with-threads=no" including any

   623         other options you need (--prefix, etc.).  Then in Modules/Setup

   624         uncomment the lines:

   625 

   626         #SSL=/usr/local/ssl

   627         #_socket socketmodule.c \

   628         #       -DUSE_SSL -I$(SSL)/include -I$(SSL)/include/openssl \

   629         #       -L$(SSL)/lib -lssl -lcrypto

   630 

   631         and remove "local/" from the SSL variable.  Finally, just run

   632         "make"!

   633 

   634         (b) The "proper" fix is to rebase the Cygwin DLLs to prevent

   635         base address conflicts.  Details on how to do this can be

   636         found in the following mail:

   637 

   638            http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html

   639 

   640         It is hoped that a version of this solution will be

   641         incorporated into the Cygwin distribution fairly soon.

   642 

   643         Two additional problems:

   644 

   645         (1) Threading support should still be disabled due to a known

   646         bug in Cygwin pthreads that causes test_threadedtempfile to

   647         hang.

   648 

   649         (2) The _curses module does not build.  This is a known

   650         Cygwin ncurses problem that should be resolved the next time

   651         that this package is released.

   652 

   653         On older versions of Cygwin, test_poll may hang and test_strftime

   654         may fail.

   655 

   656         The situation on 9X/Me is not accurately known at present.

   657         Some time ago, there were reports that the following

   658         regression tests failed:

   659 

   660             test_pwd

   661             test_select (hang)

   662             test_socket

   663 

   664         Due to the test_select hang on 9X/Me, one should run the

   665         regression test using the following:

   666 

   667             make TESTOPTS='-l -x test_select' test

   668 

   669         News regarding these platforms with more recent Cygwin

   670         versions would be appreciated!

   671 

   672 AtheOS: 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 Testing

   915 -------

   916 

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

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

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

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

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

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

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

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

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

   926 ignore this, or upgrade to glibc version 6.

   927 

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

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

   930 failing test manually, as follows:

   931 

   932         ./python ./Lib/test/test_whatever.py

   933 

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

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

   936 

   937 

   938 Installing

   939 ----------

   940 

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

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

   943 just type

   944 

   945         make install

   946 

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

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

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

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

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

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

   953 

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

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

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

   957 

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

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

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

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

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

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

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

   965 by default.

   966 

   967 If you have a previous installation of Python that you don't

   968 want to replace yet, use

   969 

   970         make altinstall

   971 

   972 This installs the same set of files as "make install" except it

   973 doesn't create the hard link to "python<version>" named "python" and

   974 it doesn't install the manual page at all.

   975 

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

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

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

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

   980 

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

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

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

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

   985 

   986 

   987 Configuration options and variables

   988 -----------------------------------

   989 

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

   991 script.

   992 

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

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

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

   996 Modules/getpath.o.

   997 

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

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

  1000         installed but broken on your platform, pass the option

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

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

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

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

  1005         option.

  1006 

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

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

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

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

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

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

  1013         installation prefix for architecture-dependent files (like the

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

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

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

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

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

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

  1020         about the install prefix.

  1021 

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

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

  1024 

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

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

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

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

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

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

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

  1032         --with-dec-threads instead.

  1033 

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

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

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

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

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

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

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

  1041         shared libraries.)  THIS OPTION IS UNSUPPORTED.

  1042 

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

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

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

  1046         combination of the GNU dynamic loading package

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

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

  1049         can be found at

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

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

  1052         configure, passing it the option

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

  1054         the absolute pathname of the dl emulation library and

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

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

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

  1058 

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

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

  1061         (default the empty string) using the options

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

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

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

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

  1066         libraries, the C library last.

  1067 

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

  1069         is linked against.

  1070 

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

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

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

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

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

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

  1077 

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

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

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

  1081         a platform. We recommend that you configure Python

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

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

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

  1085         runtime.

  1086 

  1087         The Python installation also stores the variable CXX that

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

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

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

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

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

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

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

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

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

  1097 

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

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

  1100 

  1101 

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

  1103         memory management problems.  This allows printing a list of all

  1104         live objects when the interpreter terminates.

  1105 

  1106 --with(out)-universal-newlines: enable reading of text files with

  1107         foreign newline convention (default: enabled). In other words,

  1108         any of \r, \n or \r\n is acceptable as end-of-line character.

  1109         If enabled import and execfile will automatically accept any newline

  1110         in files. Python code can open a file with open(file, 'U') to

  1111         read it in universal newline mode. THIS OPTION IS UNSUPPORTED.

  1112 

  1113 --with-tsc: Profile using the Pentium timestamping counter (TSC).

  1114 

  1115 --with-system-ffi:  Build the _ctypes extension module using an ffi

  1116 	library installed on the system.

  1117 

  1118 

  1119 Building for multiple architectures (using the VPATH feature)

  1120 -------------------------------------------------------------

  1121 

  1122 If your file system is shared between multiple architectures, it

  1123 usually is not necessary to make copies of the sources for each

  1124 architecture you want to support.  If the make program supports the

  1125 VPATH feature, you can create an empty build directory for each

  1126 architecture, and in each directory run the configure script (on the

  1127 appropriate machine with the appropriate options).  This creates the

  1128 necessary subdirectories and the Makefiles therein.  The Makefiles

  1129 contain a line VPATH=... which points to a directory containing the

  1130 actual sources.  (On SGI systems, use "smake -J1" instead of "make" if

  1131 you use VPATH -- don't try gnumake.)

  1132 

  1133 For example, the following is all you need to build a minimal Python

  1134 in /usr/tmp/python (assuming ~guido/src/python is the toplevel

  1135 directory and you want to build in /usr/tmp/python):