README

   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/)