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