home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / py2s152.zip / README < prev    next >
Text File  |  1999-06-27  |  39KB  |  905 lines
  1. This is Python version 1.5.2 -- released April 13, 1999
  2. =======================================================
  3.  
  4.  
  5. What's new in this release?
  6. ---------------------------
  7.  
  8. See the Misc/NEWS file.
  9.  
  10.  
  11. If you don't read instructions
  12. ------------------------------
  13.  
  14. Congratulations on getting this far. :-)
  15.  
  16. To start building right away (on UNIX): type "./configure" in the
  17. current directory and when it finishes, type "make".  The section
  18. Build Instructions below is still recommended reading. :-)
  19.  
  20.  
  21. What is Python anyway?
  22. ----------------------
  23.  
  24. Python is an interpreted object-oriented programming language, and is
  25. often compared to Tcl, Perl, Java or Scheme.  To find out more, point
  26. your browser to http://www.python.org/.
  27.  
  28.  
  29. A modest plug
  30. -------------
  31.  
  32. ************************************************************************
  33. * Without your support, I won't be able to continue to work on Python! *
  34. ************************************************************************
  35.  
  36. If you use Python, please consider joining the Python Software
  37. Activity (PSA).  See http://www.python.org/psa/.
  38.  
  39. Organizations that make heavy use of Python are especially encouraged
  40. to become corporate members -- or better still, to join the Python
  41. Consortium (see http://www.python.org/consortium/).
  42.  
  43.  
  44. How do I learn Python?
  45. ----------------------
  46.  
  47. The official tutorial is still a good place to start (in the Doc
  48. directory as tut/tut.tex; and http://www.python.org/doc/tut/tut.html).
  49. Aaron Watters wrote a second tutorial, that may be more accessible for
  50. some: http://www.networkcomputing.com/unixworld/tutorial/005/005.html.
  51. Both tutorials (as well as most other sources) assume that you already
  52. know how to program -- if you'd like to write "Python for Dummies", I
  53. know a publisher who would like to talk to you...
  54.  
  55. There are now also several books on Python.  While these are still
  56. based on Python 1.3 or 1.4, the information in them is still 99%
  57. correct.  The first two books, both first published in October 1996
  58. and both including a CD-ROM, form excellent companions to each other:
  59.  
  60.     Internet Programming with Python
  61.     by Aaron Watters, Guido van Rossum, and James Ahlstrom
  62.     MIS Press/Henry Holt publishers
  63.     ISBN: 1-55851-484-8
  64.  
  65.     Programming Python
  66.     by Mark Lutz
  67.     O'Reilly & Associates
  68.     ISBN: 1-56592-197-6
  69.  
  70. If you can read German, try:
  71.  
  72.     Das Python-Buch
  73.     by Martin von Loewis and Nils Fischbeck
  74.     Addison-Wesley-Longman, 1997
  75.     ISBN: 3-8273-1110-1
  76.  
  77.  
  78. Copyright issues
  79. ----------------
  80.  
  81. Python is COPYRIGHTED but free to use for all.  See the full copyright
  82. notice at the end of this file and in the file Misc/COPYRIGHT.
  83.  
  84. The Python distribution is *not* affected by the GNU Public Licence
  85. (GPL).  There are interfaces to some GNU code but these are entirely
  86. optional and no GNU code is distributed with Python.
  87.  
  88.  
  89. Build instructions
  90. ==================
  91.  
  92. Before you can build Python, you must first configure it.
  93. Fortunately, the configuration and build process has been streamlined
  94. for most Unix installations, so all you have to do is type a few
  95. commands, optionally edit one file, and sit back.  There are some
  96. platforms where things are not quite as smooth; see the platform
  97. specific notes below.  If you want to build for multiple platforms
  98. sharing the same source tree, see the section on VPATH below.
  99.  
  100. You start by running the script "./configure", which figures out your
  101. system configuration and creates several Makefiles.  (It takes a
  102. minute or two -- please be patient!)  When it's done, you are ready to
  103. run make.  You may want to pass options to the configure script -- see
  104. the section below on configuration options and variables.
  105.  
  106. To build Python, you normally type "make" in the toplevel directory.
  107. This will recursively run make in each of the subdirectories Parser,
  108. Objects, Python and Modules, creating a library file in each one.  The
  109. executable of the interpreter is built in the Modules subdirectory and
  110. moved up here when it is built.  If you want or need to, you can also
  111. chdir into each subdirectory in turn and run make there manually (do
  112. the Modules subdirectory last!).
  113.  
  114. Once you have built an interpreter, see the subsections below on
  115. testing, configuring additional modules, and installation.  If you run
  116. in trouble, see the next section.
  117.  
  118.  
  119. Troubleshooting
  120. ---------------
  121.  
  122. See also the platform specific notes in the next section.
  123.  
  124. If recursive makes fail, try invoking make as "make MAKE=make".
  125.  
  126. If you run into other trouble, see section 3 of the FAQ
  127. (http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
  128. http://www.python.org/doc/FAQ.html) for hints on what can go wrong,
  129. and how to fix it.
  130.  
  131. If you rerun the configure script with different options, remove all
  132. object files by running "make clean" before rebuilding.  Believe it or
  133. not, "make clean" sometimes helps to clean up other inexplicable
  134. problems as well.  Try it before sending in a bug report!
  135.  
  136. If the configure script fails or doesn't seem to find things that
  137. should be there, inspect the config.log file.  When you fix a
  138. configure problem, be sure to remove config.cache!
  139.  
  140. If you get a warning for every file about the -Olimit option being no
  141. longer supported, you can ignore it.  There's no foolproof way to know
  142. whether this option is needed; all I can do is test whether it is
  143. accepted without error.  On some systems, e.g. older SGI compilers, it
  144. is essential for performance (specifically when compiling ceval.c,
  145. which has more basic blocks than the default limit of 1000).  If the
  146. warning bothers you, edit the Makefile to remove "-Olimit 1500" from
  147. the OPT variable.
  148.  
  149.  
  150. Platform specific notes
  151. -----------------------
  152.  
  153. (Some of these may no longer apply.  If you find you can build Python
  154. on these platforms without the special directions mentioned here, let
  155. me know so I can remove them!)
  156.  
  157. 64-bit platforms: The modules audioop, imageop and rgbimg don't work.
  158.     Don't try to enable them in the Modules/Setup file.  They
  159.     contain code that is quite wordsize sensitive.  (If you have a
  160.     fix, let me know!)
  161.  
  162. Solaris: When using Sun's C compiler with threads, at least on Solaris
  163.     2.5.1, you need to add the "-mt" compiler option (the simplest
  164.     way is probably to specify the compiler with this option as
  165.     the "CC" environment variable when running the configure
  166.     script).
  167.  
  168. Linux:  On Linux version 1.x, once you've built Python, use it to run
  169.     the regen script in the Lib/linux1 directory.  Apparently
  170.     the files as distributed don't match the system headers on
  171.     some Linux versions.  (The "h2py" command refers to
  172.     Tools/scripts/h2py.py.)  The modules distributed for Linux 2.x
  173.     should be okay.  Shared library support now works by default
  174.     on ELF-based x86 Linux systems.  (Note: when you change the
  175.     status of a module from static to shared, you must remove its
  176.     .o file or do a "make clean".)
  177.  
  178.     Under RedHat Linux 5.0, if upgraded from a previous version,
  179.     remove the LinuxThreads packages.  This is needed because
  180.     LinuxThreads conflicts with the new thread support provided by
  181.     glibc.  Before running Python's configure script, use the
  182.     following commands as root (version numbers may differ; these
  183.     are from a stock 4.2 install):
  184.  
  185.     % rpm -qa | grep ^linuxthread
  186.     linuxthreads-0.5-1
  187.     linuxthreads-devel-0.5-1
  188.     % rpm -e linuxthreads linuxthreads-devel
  189.  
  190.     While Python only needs this to be done to allow thread
  191.     support to be included, the conflicts these packages create
  192.     with the new glibc may cause other packages which use threads
  193.     to fail as well, so their removal is a good idea regardless of
  194.     how you configure python.
  195.  
  196.     More recently, a problem with threads and fork() was tracked
  197.     down to a bug in the pthreads code in glibc version 2.0.5;
  198.     glibc version 2.0.7 solves the problem.  This causes the
  199.     popen2 test to fail; problem and solution reported by Pablo
  200.     Bleyer.
  201.  
  202.     Also under RedHat Linux 5.0, the crypt module now needs the
  203.     -lcrypt option.  Uncomment this flag in Modules/Setup, or
  204.     comment out the crypt module in the same file.
  205.  
  206. DEC Unix: When enabling threads, use --with-dec-threads, not
  207.     --with-thread.  When using GCC, it is possible to get an
  208.     internal compiler error if optimization is used.  This was
  209.     reported for GCC 2.7.2.3 on selectmodule.c.  Manually compile
  210.     the affected file without optimization to solve the problem.
  211.  
  212. DEC Ultrix: compile with GCC to avoid bugs in the native compiler,
  213.     and pass SHELL=/bin/sh5 to Make when installing.
  214.  
  215. AIX:    A complete overhaul of the shared library support is now in
  216.     place.  See Misc/AIX-NOTES for some notes on how it's done.
  217.     (The optimizer bug reported at this place in previous releases
  218.     has been worked around by a minimal code change.)
  219.  
  220. HP-UX:    Please read the file Misc/HPUX-NOTES for shared libraries.
  221.     When using threading, you may have to add -D_REENTRANT to the
  222.     OPT variable in the top-level Makefile; reported by Pat Knight
  223.     this seems to make a difference (at least for HP-UX 10.20)
  224.     even though config.h defines it.
  225.  
  226. Minix:  When using ack, use "CC=cc AR=aal RANLIB=: ./configure"!
  227.  
  228. SCO:    The following only apply to SCO 3; Python builds out of the box
  229.     on SCO 5 (or so I've heard).
  230.  
  231.     1) Everything works much better if you add -U__STDC__ to the
  232.     defs.  This is because all the SCO header files are broken.
  233.     Anything that isn't mentioned in the C standard is
  234.     conditionally excluded when __STDC__ is defined.
  235.  
  236.     2) Due to the U.S. export restrictions, SCO broke the crypt
  237.     stuff out into a separate library, libcrypt_i.a so the LIBS
  238.     needed be set to:
  239.  
  240.         LIBS=' -lsocket -lcrypt_i'
  241.  
  242. SunOS 4.x: When using the standard "cc" compiler, certain modules may
  243.     not be compilable because they use non-K&R syntax.  You should
  244.     be able to get a basic Python interpreter by commenting out
  245.     such modules in the Modules/Setup file, but I really recommend
  246.     using gcc.
  247.  
  248.     When using the SunPro C compiler, you may want to use the
  249.     '-Xa' option instead of '-Xc', to enable some needed non-ANSI
  250.     Sunisms.
  251.  
  252. NeXT:   To build fat binaries, use the --with-next-archs switch
  253.     described below.
  254.  
  255. QNX:    Chris Herborth (chrish@qnx.com) writes:
  256.     configure works best if you use GNU bash; a port is available on
  257.     ftp.qnx.com in /usr/free.  I used the following process to build,
  258.     test and install Python 1.5.x under QNX:
  259.  
  260.     1) CONFIG_SHELL=/usr/local/bin/bash CC=cc RANLIB=: \
  261.         ./configure --verbose --without-gcc --with-libm=""
  262.  
  263.     2) copy Modules/Setup.in to Modules/Setup; edit Modules/Setup to
  264.        activate everything that makes sense for your system... tested
  265.        here at QNX with the following modules:
  266.  
  267.         array, audioop, binascii, cPickle, cStringIO, cmath,
  268.         crypt, curses, errno, fcntl, gdbm, grp, imageop,
  269.         _locale, math, md5, new, operator, parser, pcre,
  270.         posix, pwd, readline, regex, reop, rgbimg, rotor,
  271.         select, signal, socket, soundex, strop, struct,
  272.         syslog, termios, time, timing, zlib, audioop, imageop, rgbimg
  273.  
  274.     3) make SHELL=/usr/local/bin/bash 
  275.     
  276.        or, if you feel the need for speed:
  277.        
  278.        make SHELL=/usr/local/bin/bash OPT="-5 -Oil+nrt"
  279.  
  280.     4) make SHELL=/usr/local/bin/bash test
  281.  
  282.        Using GNU readline 2.2 seems to behave strangely, but I
  283.        think that's a problem with my readline 2.2 port.  :-\
  284.  
  285.     5) make SHELL=/usr/local/bin/bash install
  286.  
  287.     If you get SIGSEGVs while running Python (I haven't yet, but
  288.     I've only run small programs and the test cases), you're
  289.     probably running out of stack; the default 32k could be a
  290.     little tight.  To increase the stack size, edit the Makefile
  291.     in the Modules directory to read: LDFLAGS = -N 48k
  292.  
  293. BeOS:    Chris Herborth (chrish@qnx.com) writes:
  294.     See BeOS/README for notes about compiling/installing Python on
  295.     BeOS R3 or later.  Note that only the PowerPC platform is
  296.     supported for R3; both PowerPC and x86 are supported for R4.
  297.  
  298. Cray T3E: Konrad Hinsen writes:
  299.     1) Don't use gcc. It compiles Python/graminit.c into something
  300.        that the Cray assembler doesn't like. Cray's cc seems to work
  301.        fine.
  302.     2) Uncomment modules md5 (won't compile) and audioop (will
  303.        crash the interpreter during the test suite).
  304.     If you run the test suite, two tests will fail (rotate and
  305.     binascii), but these are not the modules you'd expect to need
  306.     on a Cray.
  307.  
  308. SGI:    SGI's standard "make" utility (/bin/make or /usr/bin/make)
  309.     does not check whether a command actually changed the file it
  310.     is supposed to build.  This means that whenever you say "make"
  311.     it will redo the link step.  The remedy is to use SGI's much
  312.     smarter "smake " utility (/usr/sbin/smake), or GNU make.  If
  313.     you set the first line of the Makefile to #!/usr/sbin/smake
  314.     smake will be invoked by make (likewise for GNU make).
  315.  
  316.     A bug in the MIPSpro 7.1 compiler's optimizer seems to break
  317.     Modules/pypcre.c.  The short term solution is to compile it
  318.     without optimization.  The bug is fixed in version 7.2.1 of
  319.     the compiler.
  320.  
  321.     A bug in gcc-2.8.1 sets sys.maxint to -1 which *also* seems to
  322.     break Modules/pypcre.c.  The egcs versions of gcc fix this
  323.     problem.  Or use configure --without-gcc to compile with SGI's
  324.     compiler, if you have it.  (Raj Srinivasan, Kelvin Chu)
  325.  
  326. OS/2:   If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
  327.         compiler installed, just change into the pc\os2vacpp directory
  328.         and type NMAKE.  Threading and sockets are supported by default
  329.         in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
  330.  
  331.  
  332. Configuring threads
  333. -------------------
  334.  
  335. The main switch to configure threads is to run the configure script
  336. (see below) with the --with-thread switch (on DEC, use
  337. --with-dec-threads).  Unfortunately, on some platforms, additional
  338. compiler and/or linker options are required.  Below is a table of
  339. those options, collected by Bill Janssen.  I would love to automate
  340. this process more, but the information below is not enough to write a
  341. patch for the configure.in file, so manual intervention is required.
  342. If you patch the configure.in file and are confident that the patch
  343. works, please send me the patch.  (Don't bother patching the configure
  344. script itself -- it is regenerated each the configure.in file
  345. changes.)
  346.  
  347. Compiler switches for threads
  348. .............................
  349.  
  350.     OS/Compiler/threads                     Switches for use with threads
  351.     (POSIX is draft 10, DCE is draft 4)     (1) compile only (2) compile & link
  352.  
  353.     SunOS 5.{1-5}/{gcc,SunPro cc}/solaris   (1) -D_REENTRANT   (2) -mt
  354.     SunOS 5.5/{gcc,SunPro cc}/POSIX         (1) -D_REENTRANT
  355.     DEC OSF/1 3.x/cc/DCE                    (1) -D_REENTRANT   (2) -threads 
  356.         (butenhof@zko.dec.com)
  357.     Digital UNIX 4.x/cc/DCE                 (1) -D_REENTRANT   (2) -threads 
  358.         (butenhof@zko.dec.com)
  359.     Digital UNIX 4.x/cc/POSIX               (1) -D_REENTRANT   (2) -pthread 
  360.         (butenhof@zko.dec.com)
  361.     AIX 4.1.4/cc_r/d7                       (nothing)                       
  362.         (buhrt@iquest.net)
  363.     AIX 4.1.4/cc_r4/DCE                     (nothing)                       
  364.         (buhrt@iquest.net)
  365.     IRIX 6.2/cc/POSIX                       (nothing)                       
  366.         (robertl@cwi.nl)
  367.  
  368.  
  369. Linker (ld) libraries and flags for threads
  370. ...........................................
  371.  
  372.     OS/threads                          Libraries/switches for use with threads
  373.  
  374.     SunOS 5.{1-5}/solaris               -lthread
  375.     SunOS 5.5/POSIX                     -lpthread
  376.     DEC OSF/1 3.x/DCE                   -lpthreads -lmach -lc_r -lc     
  377.         (butenhof@zko.dec.com)
  378.     Digital UNIX 4.x/DCE                -lpthreads -lpthread -lmach -lexc -lc
  379.         (butenhof@zko.dec.com)
  380.     Digital UNIX 4.x/POSIX              -lpthread -lmach -lexc -lc      
  381.         (butenhof@zko.dec.com)
  382.     AIX 4.1.4/{draft7,DCE}              (nothing)                       
  383.         (buhrt@iquest.net)
  384.     IRIX 6.2/POSIX                      -lpthread                       
  385.         (jph@emilia.engr.sgi.com)
  386.  
  387.  
  388. Configuring additional built-in modules
  389. ---------------------------------------
  390.  
  391. You can configure the interpreter to contain fewer or more built-in
  392. modules by editing the file Modules/Setup.  This file is initially
  393. copied (when the toplevel Makefile makes Modules/Makefile for the
  394. first time) from Setup.in; if it does not exist yet, make a copy
  395. yourself.  Never edit Setup.in -- always edit Setup.  Read the
  396. comments in the file for information on what kind of edits you can
  397. make.  When you have edited Setup, Makefile and config.c in Modules
  398. will automatically be rebuilt the next time you run make in the
  399. toplevel directory.  (When working inside the Modules directory, use
  400. "make Makefile; make".)
  401.  
  402. The default collection of modules should build on any Unix system, but
  403. many optional modules should work on all modern Unices (e.g. try dbm,
  404. nis, termios, timing, syslog, curses, new, soundex, parser).  Often
  405. the quickest way to determine whether a particular module works or not
  406. is to see if it will build: enable it in Setup, then if you get
  407. compilation or link errors, disable it -- you're missing support.
  408.  
  409. On SGI IRIX, there are modules that interface to many SGI specific
  410. system libraries, e.g. the GL library and the audio hardware.
  411.  
  412. For SunOS and Solaris, enable module "sunaudiodev" to support the
  413. audio device.
  414.  
  415. In addition to the file Setup, you can also edit the file Setup.local.
  416. (the makesetup script processes both).  You may find it more
  417. convenient to edit Setup.local and leave Setup alone.  Then, when
  418. installing a new Python version, you can copy your old Setup.local
  419. file.
  420.  
  421.  
  422. Setting the optimization/debugging options
  423. ------------------------------------------
  424.  
  425. If you want or need to change the optimization/debugging options for
  426. the C compiler, assign to the OPT variable on the toplevel make
  427. command; e.g. "make OPT=-g" will build a debugging version of Python
  428. on most platforms.  The default is OPT=-O; a value for OPT in the
  429. environment when the configure script is run overrides this default
  430. (likewise for CC; and the initial value for LIBS is used as the base
  431. set of libraries to link with).
  432.  
  433.  
  434. Testing
  435. -------
  436.  
  437. To test the interpreter that you have just built, type "make test".
  438. This runs the test set twice (once with no compiled files, once with
  439. the compiled files left by the previous test run).  The test set
  440. produces some output.  You can generally ignore the messages about
  441. skipped tests due to an optional feature that can't be imported (if
  442. you want to test those modules, edit Modules/Setup to configure them).
  443. If a messages is printed about a failed test or a traceback or core
  444. dump is produced, something's wrong.  On some Linux systems (those
  445. that are not yet using glibc 6), test_strftime fails due to a
  446. non-standard-compliant implementation of strftime() in the C library.
  447. Please ignore this, or upgrade to glibc version 6.
  448.  
  449. IMPORTANT: If the tests fail and you decide to mail a bug report,
  450. *don't* include the output of "make test".  It is useless.  Run the
  451. test that fails manually, as follows:
  452.  
  453.     python ../Lib/test/test_whatever.py
  454.  
  455. (substituting the top of the source tree for .. if you built in a
  456. different directory).  This runs the test in verbose mode.
  457.  
  458.  
  459. Installing
  460. ----------
  461.  
  462. To install the Python binary, library modules, shared library modules
  463. (see below), include files, configuration files, and the manual page,
  464. just type
  465.  
  466.     make install
  467.  
  468. This will install all platform-independent files in subdirectories the
  469. directory given with the --prefix option to configure or the 'prefix'
  470. Make variable (default /usr/local), and all binary and other
  471. platform-specific files in subdirectories if the directory given by
  472. --exec-prefix or the 'exec_prefix' Make variable (defaults to the
  473. --prefix directory).
  474.  
  475. All subdirectories created will have Python's version number in their
  476. name, e.g. the library modules are installed in
  477. "/usr/local/lib/python1.5/" by default.  The Python binary is
  478. installed as "python1.5" and a hard link named "python" is created.
  479. The only file not installed with a version number in its name is the
  480. manual page, installed as "/usr/local/man/man1/python.1" by default.
  481.  
  482. If you have a previous installation of a pre-1.5 Python that you don't
  483. want to replace yet, use
  484.  
  485.     make altinstall
  486.  
  487. This installs the same set of files as "make install" except it
  488. doesn't create the hard link to "python1.5" named "python" and it
  489. doesn't install the manual page at all.
  490.  
  491. The only thing you may have to install manually is the Python mode for
  492. Emacs.  (But then again, more recent versions of Emacs may already
  493. have it!)  This is the file Misc/python-mode.el; follow the
  494. instructions that came with Emacs for installation of site specific
  495. files.
  496.  
  497.  
  498. Configuration options and variables
  499. -----------------------------------
  500.  
  501. Some special cases are handled by passing options to the configure
  502. script.
  503.  
  504. WARNING: if you rerun the configure script with different options, you
  505. must run "make clean" before rebuilding.  Exceptions to this rule:
  506. after changing --prefix or --exec-prefix, all you need to do is remove
  507. Modules/getpath.o.
  508.  
  509. --with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
  510.     it finds it.  If you don't want this, or if this compiler is
  511.     installed but broken on your platform, pass the option
  512.     --without-gcc.  You can also pass "CC=cc" (or whatever the
  513.     name of the proper C compiler is) in the environment, but the
  514.     advantage of using --without-gcc is that this option is
  515.     remembered by the config.status script for its --recheck
  516.     option.
  517.  
  518. --prefix, --exec-prefix: If you want to install the binaries and the
  519.     Python library somewhere else than in /usr/local/{bin,lib},
  520.     you can pass the option --prefix=DIRECTORY; the interpreter
  521.     binary will be installed as DIRECTORY/bin/python and the
  522.     library files as DIRECTORY/lib/python/*.  If you pass
  523.     --exec-prefix=DIRECTORY (as well) this overrides the
  524.     installation prefix for architecture-dependent files (like the
  525.     interpreter binary).  Note that --prefix=DIRECTORY also
  526.     affects the default module search path (sys.path), when
  527.     Modules/config.c is compiled.  Passing make the option
  528.     prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
  529.     prefix set at configuration time; this may be more convenient
  530.     than re-running the configure script if you change your mind
  531.     about the install prefix...
  532.  
  533. --with-readline: This option is no longer supported.  To use GNU
  534.     readline, enable module "readline" in the Modules/Setup file.
  535.  
  536. --with-thread: On most Unix systems, you can now use multiple threads.
  537.     To enable this, pass --with-thread.  (--with-threads is an
  538.     alias.)  If the library required for threads lives in a
  539.     peculiar place, you can use --with-thread=DIRECTORY.  NOTE:
  540.     you must also enable the thread module by uncommenting it in
  541.     the Modules/Setup file.  (Threads aren't enabled automatically
  542.     because there are run-time penalties when support for them is
  543.     compiled in even if you don't use them.)  IMPORTANT: run "make
  544.     clean" after changing (either enabling or disabling) this
  545.     option, or you will get link errors!  Note: for DEC Unix use
  546.     --with-dec-threads instead.
  547.  
  548. --with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
  549.     supported by the "dl" library by Jack Jansen, which is
  550.     ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
  551.     This is enabled (after you've ftp'ed and compiled the dl
  552.     library!) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
  553.     is the absolute pathname of the dl library.  (Don't bother on
  554.     IRIX 5, it already has dynamic linking using SunOS style
  555.     shared libraries.)  Support for this feature is deprecated.
  556.  
  557. --with-dl-dld: Dynamic loading of modules is rumoured to be supported
  558.     on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
  559.     Symmetry (Dynix), and Atari ST.  This is done using a
  560.     combination of the GNU dynamic loading package
  561.     (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
  562.     emulation of the SGI dl library mentioned above (the emulation
  563.     can be found at
  564.     ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z).  To
  565.     enable this, ftp and compile both libraries, then call the
  566.     configure passing it the option
  567.     --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
  568.     the absolute pathname of the dl emulation library and
  569.     DLD_DIRECTORY is the absolute pathname of the GNU dld library.
  570.     (Don't bother on SunOS 4 or 5, they already have dynamic
  571.     linking using shared libraries.)  Support for this feature is
  572.     deprecated.
  573.  
  574. --with-libm, --with-libc: It is possible to specify alternative
  575.     versions for the Math library (default -lm) and the C library
  576.     (default the empty string) using the options
  577.     --with-libm=STRING and --with-libc=STRING, respectively.  E.g.
  578.     if your system requires that you pass -lc_s to the C compiler
  579.     to use the shared C library, you can pass --with-libc=-lc_s.
  580.     These libraries are passed after all other libraries, the C
  581.     library last.
  582.     
  583. --with-next-archs='arch1 arch2': Under NEXTSTEP, this will build
  584.     all compiled binaries with the architectures listed.  Includes
  585.     correctly setting the target architecture specific resource
  586.     directory.  (This option is not supported on other platforms.)
  587.  
  588. --with-libs='libs': Add 'libs' to the LIBS that the python
  589.     linked against.
  590.  
  591.  
  592. Building for multiple architectures (using the VPATH feature)
  593. -------------------------------------------------------------
  594.  
  595. If your file system is shared between multiple architectures, it
  596. usually is not necessary to make copies of the sources for each
  597. architecture you want to support.  If the make program supports the
  598. VPATH feature, you can create an empty build directory for each
  599. architecture, and in each directory run the configure script (on the
  600. appropriate machine with the appropriate options).  This creates the
  601. necessary subdirectories and the Makefiles therein.  The Makefiles
  602. contain a line VPATH=... which points to directory containing the
  603. actual sources.  (On SGI systems, use "smake -J1" instead of "make" if
  604. you use VPATH -- don't try gnumake.)
  605.  
  606. For example, the following is all you need to build a minimal Python
  607. in /usr/tmp/python (assuming ~guido/src/python is the toplevel
  608. directory and you want to build in /usr/tmp/python):
  609.  
  610.     $ mkdir /usr/tmp/python
  611.     $ cd /usr/tmp/python
  612.     $ ~guido/src/python/configure
  613.     [...]
  614.     $ make
  615.     [...]
  616.     $
  617.  
  618. Note that Modules/Makefile copies the original Setup file to the build
  619. directory if it finds no Setup file there.  This means that you can
  620. edit the Setup file for each architecture independently.  For this
  621. reason, subsequent changes to the original Setup file are not tracked
  622. automatically, as they might overwrite local changes.  To force a copy
  623. of a changed original Setup file, delete the target Setup file.  (The
  624. makesetup script supports multiple input files, so if you want to be
  625. fancy you can change the rules to create an empty Setup.local if it
  626. doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
  627. however this assumes that you only need to add modules.)
  628.  
  629.  
  630. Building on non-UNIX systems
  631. ----------------------------
  632.  
  633. For Windows 95/98 or NT, assuming you have MS VC++ 5.0 or 6.0, the
  634. project files are in PCbuild, the workspace is pcbuild.dsw.  (The
  635. project files are for VC++ 5.0, but VC++ 6.0 will convert them for
  636. you -- start VC++ and then use Open Workspace.)
  637.  
  638. For other non-Unix Windows compilers, in particular Windows 3.1 and
  639. for OS/2, enter the directory "PC" and read the file "readme.txt".
  640.  
  641. For the Mac, a separate source distribution will be made available,
  642. for use with the CodeWarrior compiler.  If you are interested in Mac
  643. development, join the PythonMac Special Interest Group
  644. (http://www.python.org/sigs/pythonmac-sig/, or send email to
  645. pythonmac-sig-request@python.org).
  646.  
  647. Of course, there are also binary distributions available for these
  648. platforms -- see http://www.python.org/python/.
  649.  
  650. To port Python to a new non-UNIX system, you will have to fake the
  651. effect of running the configure script manually (for Mac and PC, this
  652. has already been done for you).  A good start is to copy the file
  653. config.h.in to config.h and edit the latter to reflect the actual
  654. configuration of your system.  Most symbols must simply be defined as
  655. 1 only if the corresponding feature is present and can be left alone
  656. otherwise; however RETSIGTYPE must always be defined, either as int or
  657. as void, and the *_t type symbols must be defined as some variant of
  658. int if they need to be defined at all.
  659.  
  660.  
  661.  
  662. Miscellaneous issues
  663. ====================
  664.  
  665. Documentation
  666. -------------
  667.  
  668. All documentation is provided in the subdirectory Doc in the form of
  669. LaTeX files.  In order of importance for new users: Tutorial (tut),
  670. Library Reference (lib), Language Reference (ref), Extending (ext).
  671. Especially the Library Reference is of immense value since much of
  672. Python's power (including the built-in data types and functions!) is
  673. described here.
  674.  
  675. To print the documentation from the LaTeX files, chdir into the Doc
  676. subdirectory, type "make" (let's hope you have LaTeX installed!), and
  677. send the four resulting PostScript files (tut.ps, lib.ps, ref.ps, and
  678. ext.ps) to the printer.  See the README file there.  If you don't have
  679. LaTeX, you can ftp the PostScript files from the ftp archives (see
  680. below).
  681.  
  682. All documentation is also available on-line via the Python web site
  683. (http://www.python.org/, see below).  It can also be downloaded
  684. separately from the ftp archives (see below) in Emacs INFO, HTML or
  685. PostScript form -- see the web site or the FAQ
  686. (http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
  687. http://www.python.org/doc/FAQ.html) for more info.
  688.  
  689.  
  690. Emacs mode
  691. ----------
  692.  
  693. There's an excellent Emacs editing mode for Python code; see the file
  694. Misc/python-mode.el.  Originally written by the famous Tim Peters, it
  695. is now maintained by the equally famous Barry Warsaw
  696. <bwarsaw@cnri.reston.va.us>.  The latest version, along with various
  697. other contributed Python-related Emacs goodies, is online at
  698. <http://www.python.org/emacs/python-mode>.  And if you are planning to
  699. edit the Python C code, please pick up the latest version of CC Mode
  700. <http://www.python.org/emacs/cc-mode>; it contains a "python" style
  701. used throughout most of the Python C source files.
  702.  
  703.  
  704. Web site
  705. --------
  706.  
  707. Python's own web site has URL http://www.python.org/.  Come visit us!
  708. There are a number of mirrors, and a list of mirrors is accessible
  709. from the home page -- try a mirror that's close you you.
  710.  
  711.  
  712. Ftp site
  713. --------
  714.  
  715. Python's own ftp site is ftp://ftp.python.org/pub/python/.  There are
  716. numerous mirrors; the list of mirrors is accessible from
  717. http://www.python.org/.
  718.  
  719.  
  720. Newsgroups
  721. ----------
  722.  
  723. Read comp.lang.python, a high-volume discussion newsgroup about
  724. Python, or comp.lang.python.announce, a low-volume moderated newsgroup
  725. for Python-related announcements.  These are also accessible as
  726. mailing lists, see the next item.
  727.  
  728. Archives are accessible via Deja News; the Python website has a
  729. query form for the archives at http://www.python.org/search/.
  730.  
  731.  
  732. Mailing lists
  733. -------------
  734.  
  735. See http://www.python.org/psa/MailingLists.html for an overview of the 
  736. many Python related mailing lists.
  737.  
  738.  
  739. Bug reports
  740. -----------
  741.  
  742. Bugs are best reported to the comp.lang.python newsgroup (or the
  743. Python mailing list) -- see the section "Newsgroups" above.  Before
  744. posting, check the newsgroup archives (see above) to see if your bug
  745. has already been reported!  If you don't want to go public, send them
  746. to me: <guido@python.org>.
  747.  
  748.  
  749. Questions
  750. ---------
  751.  
  752. For help, if you can't find it in the manuals or on the web site, it's
  753. best to post to the comp.lang.python or the Python mailing list (see
  754. above).  If you specifically don't want to involve the newsgroup or
  755. mailing list, send questions to <python-help@python.org> (a group of
  756. volunteers which does *not* include me).  Because of my work and email
  757. volume, I'm often be slow in answering questions sent to me directly;
  758. I prefer to answer questions posted to the newsgroup.
  759.  
  760.  
  761. The Tk interface
  762. ----------------
  763.  
  764. Tk (the user interface component of John Ousterhout's Tcl language) is
  765. also usable from Python.  Since this requires that you first build and
  766. install Tcl/Tk, the Tk interface is not enabled by default.  Python
  767. supports all Tcl/Tk versions from version 7.5/4.1 through 8.0 (and it
  768. is expected that it will also work with newer versions).  Tcl/Tk
  769. 7.4/4.0 is no longer supported.  8.0 or any later non-alpha non-beta
  770. release is recommended.
  771.  
  772. See http://sunscript.sun.com/ for more info on Tcl/Tk, including the
  773. on-line manual pages.
  774.  
  775.  
  776. To enable the Python/Tk interface, once you've built and installed
  777. Tcl/Tk, load the file Modules/Setup in your favorite text editor and
  778. search for the string "_tkinter".  Then follow the instructions found
  779. there.  If you have installed Tcl/Tk or X11 in unusual places, you
  780. will have to edit the first line to fix or add -I and -L options.
  781. (Also see the general instructions at the top of that file.)
  782.  
  783. There is little documentation on how to use Tkinter; however most of
  784. the Tk manual pages apply quite straightforwardly.  Begin with
  785. fetching the "Tk Lifesaver" document,
  786. e.g. ftp://ftp.python.org/pub/python/doc/tkinter-doc.tar.gz (a gzipped
  787. tar file containing a PostScript file) or the on-line version
  788. http://www.python.org/doc/life-preserver/index.html.  Reading the
  789. Tkinter.py source will reveal most details on how Tkinter calls are
  790. translated into Tcl code.
  791.  
  792. A more recent introduction to Tkinter programming, by Fredrik Lundh,
  793. is at http://www.pythonware.com/library/tkinter/introduction/index.htm.
  794.  
  795. There are demos in the Demo/tkinter directory, in the subdirectories
  796. guido, matt and www (the matt and guido subdirectories have been
  797. overhauled to use more recent Tkinter coding conventions).
  798.  
  799. Note that there's a Python module called "Tkinter" (capital T) which
  800. lives in Lib/tkinter/Tkinter.py, and a C module called "_tkinter"
  801. (lower case t and leading underscore) which lives in
  802. Modules/_tkinter.c.  Demos and normal Tk applications only import the
  803. Python Tkinter module -- only the latter uses the C _tkinter module
  804. directly.  In order to find the C _tkinter module, it must be compiled
  805. and linked into the Python interpreter -- the _tkinter line in the
  806. Setup file does this.  In order to find the Python Tkinter module,
  807. sys.path must be set correctly -- the TKPATH assignment in the Setup
  808. file takes care of this, but only if you install Python properly
  809. ("make install libinstall").  (You can also use dynamic loading for
  810. the C _tkinter module, in which case you must manually fix up sys.path
  811. or set $PYTHONPATH for the Python Tkinter module.)
  812.  
  813.  
  814. Distribution structure
  815. ----------------------
  816.  
  817. Most subdirectories have their own README file.  Most files have
  818. comments.
  819.  
  820. Demo/           Demonstration scripts, modules and programs
  821. Doc/            Documentation (LaTeX sources)
  822. Grammar/        Input for the parser generator
  823. Include/        Public header files
  824. Lib/            Python library modules
  825. Makefile.in     Source from which config.status creates Makefile
  826. Misc/           Miscellaneous useful files
  827. Modules/        Implementation of most built-in modules
  828. Objects/        Implementation of most built-in object types
  829. PC/             PC porting files (DOS, Windows, OS/2)
  830. PCbuild/    Directory where you should build for Windows NT/95
  831. Parser/         The parser and tokenizer and their input handling
  832. Python/         The "compiler" and interpreter
  833. README          The file you're reading now
  834. Tools/          Some useful programs written in Python
  835. acconfig.h      Additional input for the autoheader program
  836. config.h.in     Source from which config.status creates config.h
  837. configure       Configuration shell script (GNU autoconf output)
  838. configure.in    Configuration specification (GNU autoconf input)
  839. install-sh      Shell script used to install files
  840.  
  841. The following files will (may) be created in the toplevel directory by
  842. the configuration and build processes:
  843.  
  844. Makefile        Build rules
  845. config.cache    cache of configuration variables
  846. config.h        Configuration header
  847. config.log      Log from last configure run
  848. config.status   Status from last run of configure script
  849. libpython1.5.a    The library archive
  850. python          The executable interpreter
  851. tags, TAGS      Tags files for vi and Emacs
  852.  
  853.  
  854. Author's address
  855. ================
  856.  
  857. Guido van Rossum
  858. CNRI
  859. 1895 Preston White Drive
  860. Reston, VA 20191
  861. USA
  862.  
  863. E-mail: guido@cnri.reston.va.us or guido@python.org
  864.  
  865.  
  866.  
  867. Copyright notice
  868. ================
  869.  
  870. The Python source is copyrighted, but you can freely use and copy it
  871. as long as you don't change or remove the copyright notice:
  872.  
  873. ----------------------------------------------------------------------
  874. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
  875. The Netherlands.
  876.  
  877.                         All Rights Reserved
  878.  
  879. Permission to use, copy, modify, and distribute this software and its
  880. documentation for any purpose and without fee is hereby granted,
  881. provided that the above copyright notice appear in all copies and that
  882. both that copyright notice and this permission notice appear in
  883. supporting documentation, and that the names of Stichting Mathematisch
  884. Centrum or CWI or Corporation for National Research Initiatives or
  885. CNRI not be used in advertising or publicity pertaining to
  886. distribution of the software without specific, written prior
  887. permission.
  888.  
  889. While CWI is the initial source for this software, a modified version
  890. is made available by the Corporation for National Research Initiatives
  891. (CNRI) at the Internet address ftp://ftp.python.org.
  892.  
  893. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  894. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  895. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  896. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  897. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  898. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  899. TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  900. PERFORMANCE OF THIS SOFTWARE.
  901. ----------------------------------------------------------------------
  902.  
  903.  
  904. --Guido van Rossum (home page: http://www.python.org/~guido/)
  905.