blob: a9499dc22f36c27cabae921caca4ef725783c229 [file] [log] [blame]
Guido van Rossumb06df271997-08-05 21:50:20 +00001This is Python release 1.5 alpha 3
Guido van Rossumf501b4e1996-10-25 14:32:48 +00002==================================
Guido van Rossumfaf681a1996-06-20 14:32:08 +00003
Guido van Rossum33fde571997-05-09 02:40:09 +00004******************************************
5*** RELEASE RESTRICTED TO PSA MEMBERS! ***
6******************************************
Guido van Rossum627b2d71993-12-24 10:39:16 +00007
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +00008What's new in this release?
9---------------------------
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000010
Guido van Rossum49523691997-08-15 18:30:14 +000011Too much has changed to list it all here. There's a long list of
12changes in Misc/NEWS. That's still not complete, but it's getting
13there... I'm working my way through a year of change logs to extract
14meaningful descriptions of all but the most insignificant changes.
Guido van Rossum33fde571997-05-09 02:40:09 +000015
Guido van Rossum1fed5b31997-08-15 20:18:44 +000016Here are the most important changes since 1.5a2:
Guido van Rossumb06df271997-08-05 21:50:20 +000017
Guido van Rossum49523691997-08-15 18:30:14 +000018 - The new "re" module is here (still very experimental). This is a
19 new regular expression package that uses Perl syntax and solves some
20 thread-safeness problems with the matching interface.
Guido van Rossumb06df271997-08-05 21:50:20 +000021
Guido van Rossum49523691997-08-15 18:30:14 +000022 - In support of the re module, a new form of string literals is
23 introduced, "raw strings": e.g. r"\n" is equal to "\\n".
Guido van Rossumb06df271997-08-05 21:50:20 +000024
Guido van Rossum49523691997-08-15 18:30:14 +000025 - Many previously undocumented modules are now documented; some are
Guido van Rossumbda6fe61997-08-15 20:09:56 +000026 now officially obsolete or deprecated.
Guido van Rossumb06df271997-08-05 21:50:20 +000027
Guido van Rossum49523691997-08-15 18:30:14 +000028 - The build process now builds a single library (libpython1.5.a)
29 which contains everything except for the main() entry point. This
30 makes life much easier for applications that embed Python.
Guido van Rossumb06df271997-08-05 21:50:20 +000031
Guido van Rossum49523691997-08-15 18:30:14 +000032 - GNU readline is now configured as an extension module.
Guido van Rossumb06df271997-08-05 21:50:20 +000033
Guido van Rossum49523691997-08-15 18:30:14 +000034 - There is much better support for embedding Python in applications
35 that use threads. Such applications can now create multiple
36 interpreter instances if they like to. Embedding applications can
37 also uninitialize or reinitialize Python, and explicitly manipulate
38 the global lock.
Guido van Rossumb06df271997-08-05 21:50:20 +000039
Guido van Rossum49523691997-08-15 18:30:14 +000040 - Tk 8.0b2 is supported. Support for Tk 4.0 is dropped (4.1 and
41 higher are still supported).
Guido van Rossumb06df271997-08-05 21:50:20 +000042
Guido van Rossum49523691997-08-15 18:30:14 +000043 - New Tk dialog modules by Fredrik Lundh: tkColorChooser.py,
44 tkCommonDialog.py, tkMessageBox.py, tkFileDialog.py,
45 tkSimpleDialog.py.
Guido van Rossumb06df271997-08-05 21:50:20 +000046
Guido van Rossum49523691997-08-15 18:30:14 +000047 - I've redone many aspects of the Windows version -- e.g. sys.path
48 is set more like it is done on Unix, there's a new module msvcrt
49 which exports a bunch of MS VC runtime functions like setmode() and
50 kbhit(), and there are new project files for DevStudio VC++ 5.0.
51
Guido van Rossumbda6fe61997-08-15 20:09:56 +000052 - Some new speedups, e.g. inlined some opcodes for int arguments.
Guido van Rossum49523691997-08-15 18:30:14 +000053
54 - All known leaks have been plugged.
55
56 - New dictionary d.update(e): for k, v in e.items(): d[k] = v.
57
58 - New strategy for clearing modules: globals whose name starts with
59 a single underscore are deleted first.
60
61 - Comparisons can now raise exceptions.
62
63 - Metaclasses can now be programmed in Python (see Misc/NEWS, search
64 for "corollary").
65
66 - New tools faqwiz and webchecker included.
67
Guido van Rossume7fe8641997-08-15 18:51:38 +000068Other important changes, if this is the first release you see since
Guido van Rossum49523691997-08-15 18:30:14 +0000691.4:
70
71 - It's much faster (almost twice for pystone.py -- see
72 Tools/scripts.)
73
74 - There's an assert statement.
75
76 - There's a -O option that removes SET_LINENO instructions, assert
77 statements and code prefixed with ``if __debug__: ...''.
78
79 - It's much smarter about the initial value for sys.path; you can
80 control it easier using $PYTHONHOME (see the usage message, e.g. try
81 ``python -h''). In most situations, the interpreter can be
82 installed at an arbitrary location without having to recompile.
83
84 - The Grand Renaming is completed: all linker-visible symbols
85 defined by Python now have a "Py" or "_Py" prefix, and the same is
86 true for most macros and typedefs.
87
Guido van Rossumbda6fe61997-08-15 20:09:56 +000088 - New regression test harness tests more.
Guido van Rossum3ff96dd1996-07-30 18:05:04 +000089
90
Guido van Rossum91cb9d21995-04-10 11:47:38 +000091What is Python anyway?
92----------------------
93
94Python is an interpreted object-oriented programming language, and is
Guido van Rossum8d90f9d1997-05-22 20:13:25 +000095often compared to Tcl, Perl, Java or Scheme. For a quick summary of
Guido van Rossum6d9cc801996-08-01 17:31:22 +000096what Python can mean for a UNIX/C programmer, read Misc/BLURB.LUTZ.
Guido van Rossumdfcf35d1996-08-26 17:52:09 +000097If you have web access, point your browser to http://www.python.org.
Guido van Rossum91cb9d21995-04-10 11:47:38 +000098
99
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000100How do I learn Python?
101----------------------
102
103The official tutorial is still a good place to start (in the Doc
104directory as tut.tex; and http://www.python.org/doc/tut/tut.html).
105Aaron Watters wrote a second tutorial, that may be more accessible for
106some: http://www.wcmh.com/uworld/archives/95/tutorial/005.html.
107
Guido van Rossum8d90f9d1997-05-22 20:13:25 +0000108There are now also several books on Python. While these are still
109based on Python 1.3 or 1.4, the language is so stable now that you'd
110be hard pressed to find places where the books are out of date. The
111first two books, both first published in October 1996 and both
112including a CD-ROM, form excellent companions to each other:
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000113
114 Internet Programming with Python
115 by Aaron Watters, Guido van Rossum, and James Ahlstrom
116 MIS Press/Henry Holt publishers
117 ISBN: 1-55851-484-8
118
119 Programming Python
120 by Mark Lutz
121 O'Reilly & Associates
122 ISBN: 1-56592-197-6
123
Guido van Rossum8d90f9d1997-05-22 20:13:25 +0000124If you prefer to read German, try:
125
126 Das Python-Buch
127 by Martin von Loewis and Nils Fischbeck
128 Addison-Wesley-Longman, 1997
129 ISBN: 3-8273-1110-1
130
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000131
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000132If you don't read instructions
133------------------------------
134
135Congratulations on getting this far. :-)
136
137To start building right away (on UNIX): type "./configure" in the
138current directory and when it finishes, type "make". The section
139Build Instructions below is still recommended reading. :-)
140
141
142Copyright issues
143----------------
144
145Python is COPYRIGHTED but free to use for all. See the full copyright
146notice at the end of this file.
147
148The Python distribution is *not* affected by the GNU Public Licence
149(GPL). There are interfaces to some GNU code but these are entirely
150optional and no GNU code is distributed with Python. For all these
151packages, GPL-free public domain versions also exist.
152
Guido van Rossum627b2d71993-12-24 10:39:16 +0000153
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000154
Guido van Rossumff840491995-09-18 22:02:47 +0000155A modest plug
156=============
157
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000158*********************************************************************
159* Without your help, I won't be able to continue to support Python! *
160*********************************************************************
Guido van Rossumff840491995-09-18 22:02:47 +0000161
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000162If you use Python, please consider joining the Python Software
163Activity (PSA). See http://www.python.org/psa/.
164
165Organizations that make heavy use of Python are especially encouraged
166to become corporate members!
Guido van Rossum627b2d71993-12-24 10:39:16 +0000167
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000168
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000169Build instructions
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000170==================
Guido van Rossum627b2d71993-12-24 10:39:16 +0000171
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000172Before you can build Python, you must first configure it.
173Fortunately, the configuration and build process has been streamlined
174for most Unix installations, so all you have to do is type a few
175commands, optionally edit one file, and sit back. There are some
176platforms where things are not quite as smooth; see the platform
177specific notes below. If you want to build for multiple platforms
178sharing the same source tree, see the section on VPATH below.
Guido van Rossum627b2d71993-12-24 10:39:16 +0000179
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000180You start by running the script "./configure", which figures out your
181system configuration and creates several Makefiles. (It takes a
182minute or two -- please be patient!) When it's done, you are ready to
183run make. You may want to pass options to the configure script -- see
184the section below on configuration options and variables.
185
186To build Python, you normally type "make" in the toplevel directory.
187This will recursively run make in each of the subdirectories Parser,
188Objects, Python and Modules, creating a library file in each one. The
189executable of the interpreter is built in the Modules subdirectory and
190moved up here when it is built. If you want or need to, you can also
191chdir into each subdirectory in turn and run make there manually (do
192the Modules subdirectory last!).
193
194Once you have built an interpreter, see the subsections below on
195testing, configuring additional modules, and installation. If you run
196in trouble, see the next section.
Guido van Rossum627b2d71993-12-24 10:39:16 +0000197
Guido van Rossum0a516c91994-09-12 10:58:40 +0000198
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000199Troubleshooting
200---------------
Guido van Rossum627b2d71993-12-24 10:39:16 +0000201
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000202See also the platform specific notes in the next section.
203
Guido van Rossumfaf681a1996-06-20 14:32:08 +0000204If recursive makes fail, try invoking make as "make MAKE=make".
205
Guido van Rossum49523691997-08-15 18:30:14 +0000206If you run into other trouble, see section 3 of the FAQ
207(http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
208http://www.python.org/doc/FAQ.html) for hints on what can go wrong,
209and how to fix it.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000210
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000211If you rerun the configure script with different options, remove all
212object files by running "make clean" before rebuilding. Believe it or
213not, "make clean" sometimes helps to clean up other inexplicable
214problems as well. Try it before sending in a bug report!
215
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000216If the configure script fails or doesn't seem to find things that
217should be there, inspect the config.log file.
218
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000219
220Platform specific notes
221-----------------------
222
Guido van Rossum0447a321995-10-08 01:22:33 +0000223(Some of these may no longer apply. If you find you can build Python
224on these platforms without the special directions mentioned here, let
225me know so I can remove them!)
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000226
Guido van Rossum4462e931997-01-22 21:00:32 +0000227Solaris: When using Sun's C compiler with threads, at least on Solaris
228 2.5.1, you need to add the "-mt" compiler option (the simplest
229 way is probably to specify the compiler with this option as
230 the "CC" environment variable when running the configure
231 script).
232
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000233Linux: On Linux version 1.x, once you've built Python, use it to run
234 the regen script in the Lib/linux1 directory. Apparently
235 the files as distributed don't match the system headers on
236 some Linux versions. (The "h2py" command refers to
237 Tools/scripts/h2py.py.) The modules distributed for Linux 2.x
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000238 should be okay. Shared library support now works by default
Guido van Rossum4462e931997-01-22 21:00:32 +0000239 on ELF-based x86 Linux systems. (Note: when you change the
240 status of a module from static to shared, you must remove its
241 .o file or do a "make clean".)
242
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000243DEC Unix: When enabling threads, use --with-dec-threads, not
Guido van Rossum4462e931997-01-22 21:00:32 +0000244 --with-thread.
Guido van Rossum8eca2c21996-02-14 18:37:46 +0000245
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000246AIX: A complete overhaul of the shared library support is now in
247 place. To enable it, uncomment the LINKCC line in the Setup
248 file. See Misc/AIX-NOTES for some notes on how it's done.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000249
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000250 WARNING! In some versions of AIX, you get errors about
Guido van Rossuma3b4b611996-07-21 02:48:16 +0000251 Invalid Indent when running the Python test set. This appears
252 to be a bug in the AIX compiler. Rebuild Parser/tokenizer.c
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000253 using OPT="" or OPT=-g, or use gcc. According to the latest
254 reports, it seems this compiler bug is still present in 4.2.1.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000255
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000256Minix: When using ack, use "CC=cc AR=aal RANLIB=: ./configure"!
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000257
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000258SCO: 1) Everything works much better if you add -U__STDC__ to the
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000259 defs. This is because all the SCO header files are broken.
260 Anything that isn't mentioned in the C standard it's
261 conditionally excluded when __STDC__ is defined.
262
263 2) Due to the U.S. export restrictions, SCO broke the crypt
264 stuff out into a separate library, libcrypt_i.a so the LIBS
265 needed be set to:
266
267 LIBS=' -lsocket -lcrypt_i'
268
Guido van Rossuma3b4b611996-07-21 02:48:16 +0000269 3) According to at least one report, the above apply only to
270 SCO 3 -- Python builds out of the box on SCO 5.
271
Guido van Rossum4462e931997-01-22 21:00:32 +0000272SunOS: On SunOS 4.1.x, when using the SunPro C compiler, you may want
273 to use the '-Xa' option instead of '-Xc', to enable some
274 needed non-ANSI Sunisms.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000275
Guido van Rossumcc55c2d1996-10-21 15:14:27 +0000276NeXT: To build fat binaries, use the --with-next-archs switch
277 described below.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000278
Guido van Rossum40d63581997-08-14 19:45:30 +0000279QNX: Edit the top level Makefile to use the following compile options:
280 OPT = -Ox -Q -U_M_IX86 -U__WATCOMC__
281 Edit the Makefile in the Modules directory to read:
282 LDFLAGS = -N 48k
283
Guido van Rossum1bf0bf41997-08-20 23:50:51 +0000284Cray T3E: Konrad Hinsen writes:
285 1) Don't use gcc. It compiles Python/graminit.c into something that
286 the Cray assembler doesn't like. Cray's cc seems to work fine.
287 2) Uncomment modules md5 (won't compile) and audioop (will crash
288 the interpreter during the test suite).
289 If you run the test suite, two tests will fail (rotate and binascii),
290 but these are not the modules you'd expect to need on a Cray.
291
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000292
293Configuring additional built-in modules
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000294---------------------------------------
Guido van Rossum19e0c261995-01-17 16:36:34 +0000295
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000296You can configure the interpreter to contain fewer or more built-in
297modules by editing the file Modules/Setup. This file is initially
298copied (when the toplevel Makefile makes Modules/Makefile for the
299first time) from Setup.in; if it does not exist yet, make a copy
300yourself. Never edit Setup.in -- always edit Setup. Read the
301comments in the file for information on what kind of edits you can
302make. When you have edited Setup, Makefile and config.c in Modules
303will automatically be rebuilt the next time you run make in the
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000304toplevel directory. (When working inside the Modules directory, use
305"make Makefile; make".)
Guido van Rossum627b2d71993-12-24 10:39:16 +0000306
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000307The default collection of modules should build on any Unix system, but
308many optional modules should work on all modern Unices (e.g. try dbm,
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000309nis, termios, timing, syslog, curses, new, soundex, parser). Often
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000310the quickest way to determine whether a particular module works or not
311is to see if it will build: enable it in Setup, then if you get
312compilation or link errors, disable it -- you're missing support.
313
314On SGI IRIX, there are modules that interface to many SGI specific
315system libraries, e.g. the GL library and the audio hardware.
316
317For SunOS and Solaris, enable module "sunaudiodev" to support the
318audio device.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000319
Guido van Rossum4462e931997-01-22 21:00:32 +0000320In addition to the file Setup, you can also edit the file Setup.local.
321(the makesetup script processes both). You may find it more
322convenient to edit Setup.local and leave Setup alone. Then, when
323installing a new Python version, you can copy your old Setup.local
324file.
325
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000326
327Setting the optimization/debugging options
328------------------------------------------
329
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000330If you want or need to change the optimization/debugging options for
331the C compiler, assign to the OPT variable on the toplevel make
332command; e.g. "make OPT=-g" will build a debugging version of Python
333on most platforms. The default is OPT=-O; a value for OPT in the
334environment when the configure script is run overrides this default
335(likewise for CC; and the initial value for LIBS is used as the base
336set of libraries to link with).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000337
338
339Testing
340-------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000341
342To test the interpreter that you have just built, type "make test".
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000343This runs the test set twice (once with no compiled files, once with
344the compiled files left by the previous test run). The test set
345produces some output. You can generally ignore the messages about
346skipped tests due to an optional feature that can't be imported (if
347you want to test those modules, edit Modules/Setup to configure them).
348If a messages is printed about a failed test or a traceback or core
349dump is produced, something's wrong. On some systems, test_strftime
350fails due to a non-standard implementation of strftime() in the C
351library. This can be ignored (or you can complain to your vendor).
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000352
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000353IMPORTANT: If the tests fail and you decide to mail a bug report,
354*don't* include the output of "make test". It is useless. Run the
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000355test that fails manually, as follows:
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000356
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000357 python ../Lib/test/test_whatever.py
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000358
359(substituting the top of the source tree for .. if you built in a
Guido van Rossum6ae5d3d1997-05-14 21:39:05 +0000360different directory). This runs the test in verbose mode.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000361
362
363Installing
364----------
365
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000366Installing Python was never this easy!
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +0000367
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000368To install the Python binary, library modules, shared library modules
369(see below), include files, configuration files, and the manual page,
370just type "make install". This will install all platform-independent
371files in subdirectories the directory given with the --prefix option
372to configure or the 'prefix' Make variable (default /usr/local), and
373all binary and other platform-specific files in subdirectories if the
374directory given by --exec-prefix or the 'exec_prefix' Make variable
375(defaults to the --prefix directory). All subdirectories created will
376have Python's version number in their name, e.g. the library modules
Guido van Rossum33fde571997-05-09 02:40:09 +0000377are installed in "/usr/local/lib/python1.5/" by default. The Python
378binary is installed as "python1.5" and a hard link named "python" is
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000379created. The only file not installed with a version number in its
380name is the manual page, installed as "/usr/local/man/man1/python.1"
381by default.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000382
Guido van Rossum49523691997-08-15 18:30:14 +0000383If you have a previous installation of a pre-1.5 Python that you don't
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000384want to replace yet, use "make altinstall". This installs the same
385set of files as "make install" except it doesn't create the hard link
Guido van Rossum33fde571997-05-09 02:40:09 +0000386to "python1.5" named "python" and it doesn't install the manual page
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000387at all.
388
389The only thing you may have to install manually is the Python mode for
390Emacs. (But then again, more recent versions of Emacs may already
391have it!) This is the file Misc/python-mode.el; follow the
392instructions that came with Emacs for installation of site specific
393files.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000394
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000395
396Configuration options and variables
397-----------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000398
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000399Some special cases are handled by passing options to the configure
400script.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000401
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000402WARNING: if you rerun the configure script with different options, you
403must run "make clean" before rebuilding. Exceptions to this rule:
404after changing --prefix or --exec-prefix, all you need to do is remove
Guido van Rossumb06df271997-08-05 21:50:20 +0000405Modules/getpath.o.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000406
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000407--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
408 it finds it. If you don't want this, or if this compiler is
409 installed but broken on your platform, pass the option
410 --without-gcc. You can also pass "CC=cc" (or whatever the
411 name of the proper C compiler is) in the environment, but the
412 advantage of using --without-gcc is that this option is
413 remembered by the config.status script for its --recheck
414 option.
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000415
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000416--prefix, --exec-prefix: If you want to install the binaries and the
417 Python library somewhere else than in /usr/local/{bin,lib},
418 you can pass the option --prefix=DIRECTORY; the interpreter
419 binary will be installed as DIRECTORY/bin/python and the
420 library files as DIRECTORY/lib/python/*. If you pass
421 --exec-prefix=DIRECTORY (as well) this overrides the
422 installation prefix for architecture-dependent files (like the
423 interpreter binary). Note that --prefix=DIRECTORY also
424 affects the default module search path (sys.path), when
425 Modules/config.c is compiled. Passing make the option
426 prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
427 prefix set at configuration time; this may be more convenient
428 than re-running the configure script if you change your mind
429 about the install prefix...
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000430
Guido van Rossumb06df271997-08-05 21:50:20 +0000431--with-readline: This option is no longer supported. To use GNU
432 readline, enable module "readline" in the Modules/Setup file.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000433
Guido van Rossumfaf681a1996-06-20 14:32:08 +0000434--with-thread: On most Unix systems, you can now use multiple threads.
Guido van Rossum4462e931997-01-22 21:00:32 +0000435 To enable this, pass --with-thread. (--with-threads is an
436 alias.) If the library required for threads lives in a
Guido van Rossum8d90f9d1997-05-22 20:13:25 +0000437 peculiar place, you can use --with-thread=DIRECTORY. NOTE:
438 you must also enable the thread module by uncommenting it in
439 the Modules/Setup file. (Threads aren't enabled automatically
440 because there are run-time penalties when support for them is
441 compiled in even if you don't use them.) IMPORTANT: run "make
442 clean" after changing (either enabling or disabling) this
443 option! Note: for DEC Unix use --with-dec-threads instead.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000444
445--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
446 supported by the "dl" library by Jack Jansen, which is
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000447 ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000448 This is enabled (after you've ftp'ed and compiled the dl
449 library!) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
450 is the absolute pathname of the dl library. (Don't bother on
451 IRIX 5, it already has dynamic linking using SunOS style
452 shared libraries.) Support for this feature is deprecated.
453
454--with-dl-dld: Dynamic loading of modules is rumoured to be supported
455 on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
456 Symmetry (Dynix), and Atari ST. This is done using a
457 combination of the GNU dynamic loading package
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000458 (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000459 emulation of the SGI dl library mentioned above (the emulation
460 can be found at
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000461 ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z). To
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000462 enable this, ftp and compile both libraries, then call the
463 configure passing it the option
464 --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
465 the absolute pathname of the dl emulation library and
466 DLD_DIRECTORY is the absolute pathname of the GNU dld library.
467 (Don't bother on SunOS 4 or 5, they already have dynamic
468 linking using shared libraries.) Support for this feature is
469 deprecated.
470
471--with-libm, --with-libc: It is possible to specify alternative
472 versions for the Math library (default -lm) and the C library
473 (default the empty string) using the options
474 --with-libm=STRING and --with-libc=STRING, respectively. E.g.
475 if your system requires that you pass -lc_s to the C compiler
476 to use the shared C library, you can pass --with-libc=-lc_s.
477 These libraries are passed after all other libraries, the C
478 library last.
Guido van Rossum3ff96dd1996-07-30 18:05:04 +0000479
480--with-next-archs='arch1 arch2': Under NEXTSTEP, this will build
481 all compiled binaries with the architectures listed. Includes
482 correctly setting the target architecture specific resource
Guido van Rossumcc55c2d1996-10-21 15:14:27 +0000483 directory. (This option is not supported on other platforms.)
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000484
Guido van Rossumd02ba451996-07-31 17:36:01 +0000485--with-libs='libs': Add 'libs' to the LIBS that the python
486 linked against.
487
Guido van Rossum76be6ed1995-01-02 18:33:54 +0000488
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000489Building for multiple architectures (using the VPATH feature)
490-------------------------------------------------------------
491
492If your file system is shared between multiple architectures, it
493usually is not necessary to make copies of the sources for each
494architecture you want to support. If the make program supports the
495VPATH feature, you can create an empty build directory for each
496architecture, and in each directory run the configure script (on the
497appropriate machine with the appropriate options). This creates the
498necessary subdirectories and the Makefiles therein. The Makefiles
499contain a line VPATH=... which points to directory containing the
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000500actual sources. (On SGI systems, use "smake -J1" instead of "make" if
501you use VPATH -- don't try gnumake.)
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000502
503For example, the following is all you need to build a minimal Python
504in /usr/tmp/python (assuming ~guido/src/python is the toplevel
505directory and you want to build in /usr/tmp/python):
506
507 $ mkdir /usr/tmp/python
508 $ cd /usr/tmp/python
509 $ ~guido/src/python/configure
510 [...]
511 $ make
512 [...]
513 $
514
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000515Note that Modules/Makefile copies the original Setup file to the build
516directory if it finds no Setup file there. This means that you can
517edit the Setup file for each architecture independently. For this
518reason, subsequent changes to the original Setup file are not tracked
519automatically, as they might overwrite local changes. To force a copy
520of a changed original Setup file, delete the target Setup file. (The
521makesetup script supports multiple input files, so if you want to be
522fancy you can change the rules to create an empty Setup.local if it
523doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
524however this assumes that you only need to add modules.)
525
526
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000527Building on non-UNIX systems
528----------------------------
529
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000530Building Python for a PC is now a piece of cake!
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +0000531
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000532Enter the directory "PC" and read the file "readme.txt". Most popular
533non-Unix PC platforms and compilers are supported (Unix ports to the
534PC such as Linux, FreeBSD or Solaris-x86 of course use the standard
535Unix build instructions).
536
537For the Mac, a separate source distribution will be made available,
538for use with the CodeWarrior compiler. If you are interested in Mac
539development, join the PythonMac Special Interest Group
540(http://www.python.org/sigs/pythonmac-sig/, or send email to
541pythonmac-sig-request@python.org).
542
543Of course, there are also binary distributions available for these
544platforms -- see http://www.python.org/python/.
545
546To port Python to a new non-UNIX system, you will have to fake the
547effect of running the configure script manually (for Mac and PC, this
548has already been done for you). A good start is to copy the file
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000549config.h.in to config.h and edit the latter to reflect the actual
550configuration of your system. Most symbols must simply be defined as
5511 only if the corresponding feature is present and can be left alone
552otherwise; however RETSIGTYPE must always be defined, either as int or
553as void, and the *_t type symbols must be defined as some variant of
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000554int if they need to be defined at all.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000555
556
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000557
558Miscellaneous issues
559====================
560
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000561Documentation
562-------------
563
564All documentation is provided in the subdirectory Doc in the form of
565LaTeX files. In order of importance for new users: Tutorial (tut),
566Library Reference (lib), Language Reference (ref), Extending (ext).
567Especially the Library Reference is of immense value since much of
568Python's power (including the built-in data types and functions!) is
569described here.
570
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000571To print the documentation from the LaTeX files, chdir into the Doc
572subdirectory, type "make" (let's hope you have LaTeX installed!), and
573send the four resulting PostScript files (tut.ps, lib.ps, ref.ps, and
574ext.ps) to the printer. See the README file there. If you don't have
575LaTeX, you can ftp the PostScript files from the ftp archives (see
576below).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000577
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000578All documentation is also available on-line via the Python web site
579(http://www.python.org/, see below). It can also be downloaded
580separately from the ftp archives (see below) in Emacs INFO, HTML or
Guido van Rossum49523691997-08-15 18:30:14 +0000581PostScript form -- see the web site or the FAQ
582(http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
583http://www.python.org/doc/FAQ.html) for more info.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000584
585
586Emacs mode
587----------
588
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000589There's an excellent Emacs editing mode for Python code; see the file
590Misc/python-mode.el. Originally written by Tim Peters, it is now
Guido van Rossum49523691997-08-15 18:30:14 +0000591maintained by Barry Warsaw <bwarsaw@cnri.reston.va.us>. The latest
592version is online at ftp://ftp.python.org/pub/emacs/python-mode.el.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000593
594
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +0000595Web site
596--------
597
598Python's own web site has URL http://www.python.org/. Come visit us!
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000599There are a number of mirrors, listed on the home page -- try a mirror
600that's close you you.
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +0000601
602
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000603Ftp site
604--------
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000605
Guido van Rossum49523691997-08-15 18:30:14 +0000606Python's own ftp site is ftp://ftp.python.org/pub/python. There are
607numerous mirrors; see http://www.python.org/python/Mirrors.html for a
608list of mirror sites.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000609
610
611Newsgroup and mailing list
612--------------------------
613
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000614There are a newsgroup and a mailing list devoted to Python. The
615newsgroup, comp.lang.python, contains exactly the same messages as the
616mailing list (though not always in the same order, due to the
617mysterious nature of the Usenet news distribution algorithm). To
618subscribe to the mailing list, send mail containing your real name and
619e-mail address to "python-list-request@cwi.nl". Use the same address
620if you want to unsibscribed. (A real person reads these messages, so
621no LISTPROC or Majordomo commands, please, and please be patient --
622normal turn-around time is about one working day.)
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000623
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000624The Python web site contains a search form that lets you search the
625newsgroup archives (or the web site itself). Click on the "search"
626link in the banner menu on any page of http://www.python.org/.
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000627
628
629Bug reports
630-----------
631
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000632Bugs are best reported to the comp.lang.python newsgroup or the Python
Guido van Rossumcc55c2d1996-10-21 15:14:27 +0000633mailing list -- see the section "Newsgroup and mailing list" above.
Guido van Rossumdfcf35d1996-08-26 17:52:09 +0000634Before posting, check the newsgroup archives (see above) to see if
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000635your bug has already been reported!
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000636
637
638Questions
639---------
640
Guido van Rossum49523691997-08-15 18:30:14 +0000641For help, if you can't find it in the manuals or on the web site, it's
642best to post to the comp.lang.python or the Python mailing list (see
643above). If you specifically don't want to involve the newsgroup or
644mailing list, send questions to python-help@python.org.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000645
646
647The Tk interface
648----------------
649
650Tk (the user interface component of John Ousterhout's Tcl language) is
651also usable from Python. Since this requires that you first build and
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000652install Tcl/Tk, the Tk interface is not enabled by default. It works
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000653with Tcl 7.5 and Tk 4.1 as well as with Tcl 7.4 and Tk 4.0. I didn't
654have the time to test it with Tcl 7.6 and Tk 4.2 yet, but it might
655well work.
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000656
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000657See http://www.sunlabs.com/research/tcl/ for more info on where to get
Guido van Rossum33fde571997-05-09 02:40:09 +0000658Tcl/Tk. Also http://sunscript.sun.com/.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000659
660To enable the Python/Tk interface, once you've built and installed
661Tcl/Tk, all you need to do is edit two lines in Modules/Setup; search
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000662for the string "_tkinter". Uncomment one (normally the first) of the
663lines beginning with "#_tkinter" and un-comment the line beginning
664with "#TKPATH". If you have installed Tcl/Tk or X11 in unusual
665places, you will have to edit the first line to fix or add -I and -L
666options. See the Build Instructions above for more details.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000667
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000668There is little documentation on how to use Tkinter; however most of
669the Tk manual pages apply quite straightforwardly. Begin with
670fetching the "Tk Lifesaver" document,
671e.g. ftp://ftp.python.org/pub/python/doc/tkinter-doc.tar.gz (a gzipped
672tar file containing a PostScript file) or the on-line version
673http://www.python.org/doc/life-preserver/index.html. Reading the
674Tkinter.py source will reveal most details on how Tkinter calls are
675translated into Tcl code.
676
677There are demos in the Demo/tkinter directory, in the subdirectories
678guido, matt and www (the matt and guido subdirectories have been
679overhauled to use more recent Tkinter coding conventions).
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000680
681Note that there's a Python module called "Tkinter" (capital T) which
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000682lives in Lib/tkinter/Tkinter.py, and a C module called "_tkinter"
683(lower case t and leading underscore) which lives in
684Modules/_tkinter.c. Demos and normal Tk applications only import the
685Python Tkinter module -- only the latter uses the C _tkinter module
686directly. In order to find the C _tkinter module, it must be compiled
687and linked into the Python interpreter -- the _tkinter line in the
688Setup file does this. In order to find the Python Tkinter module,
689sys.path must be set correctly -- the TKPATH assignment in the Setup
690file takes care of this, but only if you install Python properly
691("make install libinstall"). (You can also use dynamic loading for
692the C _tkinter module, in which case you must manually fix up sys.path
693or set $PYTHONPATH for the Python Tkinter module.)
Guido van Rossum84c8c7f1995-08-28 02:44:24 +0000694
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000695
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000696Distribution structure
697----------------------
698
699Most subdirectories have their own README file. Most files have
700comments.
701
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000702BUGS A list of known bugs (not completely up-to-date)
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000703Demo/ Demonstration scripts, modules and programs
704Doc/ Documentation (LaTeX sources)
705Grammar/ Input for the parser generator
706Include/ Public header files
707Lib/ Python library modules
708Makefile.in Source from which config.status creates Makefile
709Misc/ Miscellaneous files
710Modules/ Implementation of most built-in modules
711Objects/ Implementation of most built-in object types
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000712PC/ PC porting files (DOS, Windows, NT, OS/2)
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000713Parser/ The parser and tokenizer and their input handling
714Python/ The "compiler" and interpreter
715README The file you're reading now
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000716TODO A list of things that could be done (not up-to-date)
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000717Tools/ Some useful programs written in Python
718acconfig.h Additional input for the autoheader program
719config.h.in Source from which config.status creates config.h
720configure Configuration shell script (GNU autoconf output)
721configure.in Configuration specification (GNU autoconf input)
722install-sh Shell script used to install files
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000723
724The following files will (may) be created in the toplevel directory by
725the configuration and build processes:
726
Guido van Rossum6d9cc801996-08-01 17:31:22 +0000727Makefile Build rules
728config.cache cache of configuration variables
729config.h Configuration header
730config.log log from last configure run
731config.status status from last run of configure script
732python The executable interpreter
733tags, TAGS Tags files for vi and Emacs
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000734
735
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000736Author's address
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000737================
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000738
739Guido van Rossum
Guido van Rossumfaf681a1996-06-20 14:32:08 +0000740CNRI
7411895 Preston White Drive
Guido van Rossum8d7d4ed1996-07-30 21:41:07 +0000742Reston, VA 20191
Guido van Rossumfaf681a1996-06-20 14:32:08 +0000743USA
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000744
Guido van Rossumd0fe8451996-08-26 03:02:37 +0000745E-mail: guido@cnri.reston.va.us or guido@python.org
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000746
747
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000748
749Copyright notice
750================
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000751
752The Python source is copyrighted, but you can freely use and copy it
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000753as long as you don't change or remove the copyright notice:
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000754
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000755----------------------------------------------------------------------
Guido van Rossumaf5b83e1995-01-04 19:02:35 +0000756Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
757The Netherlands.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000758
759 All Rights Reserved
760
Guido van Rossumc561e5d1994-08-23 13:52:46 +0000761Permission to use, copy, modify, and distribute this software and its
762documentation for any purpose and without fee is hereby granted,
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000763provided that the above copyright notice appear in all copies and that
Guido van Rossumc561e5d1994-08-23 13:52:46 +0000764both that copyright notice and this permission notice appear in
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000765supporting documentation, and that the names of Stichting Mathematisch
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000766Centrum or CWI or Corporation for National Research Initiatives or
767CNRI not be used in advertising or publicity pertaining to
768distribution of the software without specific, written prior
769permission.
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000770
Guido van Rossumf501b4e1996-10-25 14:32:48 +0000771While CWI is the initial source for this software, a modified version
772is made available by the Corporation for National Research Initiatives
773(CNRI) at the Internet address ftp://ftp.python.org.
774
775STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
776REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
777MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
778CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
779DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
780PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
781TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
782PERFORMANCE OF THIS SOFTWARE.
Guido van Rossum91cb9d21995-04-10 11:47:38 +0000783----------------------------------------------------------------------
Guido van Rossum433c8ad1994-08-01 12:07:07 +0000784
785
Guido van Rossumfaf681a1996-06-20 14:32:08 +0000786--Guido van Rossum (home page: http://www.python.org/~guido/)