$Id: README,v 1.22 2003/03/09 13:17:43 jt Exp $

Abstract:

This is the README for the Cygwin Python distribution.

Python is an interpreted, interactive, object-oriented programming
language often compared to Tcl, Perl, Scheme or Java. Python includes
modules, classes, exceptions, very high level dynamic data types and
dynamic typing. Python supports interfaces to many system calls and
libraries, as well as to various windowing systems (X11, Motif, Tk,
Mac and MFC).

As of Cygwin Python 2.2.2-3, it is assumed that your Cygwin system has
been rebased in order to prevent fork() failures due to DLL base address
conflicts.  Previous versions worked around this issue by building the
_socket module statically.  This hack no longer works with current
Cygwin versions.  See the issues section for more details.

As of Cygwin Python 2.2.1-1, the port supports threading.  Many thanks
to Rob Collins (and others) who enhanced Cygwin's pthreads support to
the level needed by Python.

Additionally, the package now includes the HTML version of the full Python
documentation.

As of Cygwin Python 2.1.1-2, the port is essentially complete (at least
for Windows NT 4.0 and 2000).  The most notable changes are the addition
of the _tkinter module and the elimination of the test_poll hang.

As of Cygwin Python 2.1, the port is built with a DLL core very similar
to how the Win32 port is built.  This enables Cygwin Python to support
building shared extensions with the traditional Misc/Makefile.pre.in
and the newer distutils methods.

Requirements:

The following packages or later are required to build and/or execute
Cygwin Python:

    Cygwin 1.3.11-3
    binutils-20011002-1
    gcc 2.95.3-5

The following packages or later are required to build and/or execute
some of the standard Cygwin Python extension modules:

    gdbm-1.8.0-3         (gdbm)
    libdb-3.1.17-2       (bsddb)
    libdb-devel-3.1.17-2 (bsddb)
    libncurses6-5.2-8    (_curses and _curses_panel)
    ncurses-5.2-8        (_curses and _curses_panel)
    openssl-0.9.6b-2     (_socket)
    readline-4.2-3       (readline)
    tcltk-20021218-3     (_tkinter)
    zlib-1.1.3-6         (zlib)

Install:

Cygwin Python does not require any special installation procedures.
However, _tkinter users should see the issues section.

Source:

The Python source does not quite build OOTB under Cygwin due to issues
with Cygwin's fork() and DLL base address conflicts.  Because of this,
I back ported the following patch to workaround this problem:

    http://sourceforge.net/tracker/?func=detail&atid=305470&aid=491107&group_id=5470

I also added the following files to the source archive:

    CYGWIN-PATCHES/README: (this) README file
    CYGWIN-PATCHES/build.sh: build script
    CYGWIN-PATCHES/python.patch: diff between the original and Cygwin sources
    CYGWIN-PATCHES/html-$version.tar.bz2: pre-generated Python HTML
        documentation since Cygwin cannot currently self-generate it

and renamed the original source archive to match Cygwin's setup.exe
naming conventions.

To restore the Python source to its original state, perform the following:

    $ cd python-$version-$package
    $ patch -R -p1 <CYGWIN-PATCHES/python.patch
    $ rm -fr CYGWIN-PATCHES

where $version is the Python version (e.g., 2.2.1) and $package is the
Cygwin package number.

Build:

This distribution has been configured as follows:

    configure --prefix=/usr

See CYGWIN-PATCHES/build.sh in the source archive for my exact build
recipe for configuring, making, and packaging this distribution.

Test:

On NT/2000, Cygwin Python passes all tests except for test_commands.
Use the following to run the regression test:

    $ make test

On XP, I assume that Cygwin Python should behave the same as on NT/2000.
However I do not have access to XP, so I cannot verify this behavior
myself.

On 9X/Me, Cygwin Python hangs in test_select and test_socket fails.
Use the following to run the regression test:

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

Note that the above 9X/Me regression test results have been reported
to me.  Since I do not have access to 9X/Me, I cannot verify this
behavior myself.

Issues:

The following are the known Cygwin Python issues:

1. On 9X/ME, the regression test test_select hangs and test_socket fail.

2. The _tkinter extension module will only be built if the X11 header
files from the tcltk-20021218-3 source archive have been copied to
/usr/include:

    $ mkdir -p /usr/include/X11
    $ tar -xjf tcltk-20021218-3-src.tar.bz2
    $ cp tcltk-20021218-3/tk/xlib/X11/*.h /usr/include/X11

3. Due to issues with Cygwin's fork() and DLL base address conflicts,
one should rebase their Cygwin system to prevent fork() failures.  Use
the following procedure to rebase your system:

    a. install the Cygwin rebase package (if necessary)
    b. shutdown all Cygwin processes
    c. start bash (do not use rxvt)
    d. execute rebaseall (in the bash window)

4. Due to a recent Python change, the test_commands regression test will
fail if the user and/or group names of the root directory (i.e., "/")
contain spaces.  Due to a recent Cygwin change, the test_commands
regression test will fail if the root directory (i.e., "/") has certain
ACLs applied.  Both of these issues have been corrected in Python CVS.

5. This README has *not* been updated for XP Professional and Home.

6. _tkinter users should note that Cygwin tcltk is really a Win32
package and hence, does *not* understand Cygwin style paths.  To use the
_tkinter module you must define the following environment variables:

    $ export TCL_LIBRARY=$(cygpath -w /usr/share/tcl$version)
    $ export TK_LIBRARY=$(cygpath -w /usr/share/tk$version)

where $version is the TCL/TK version (e.g., 8.4).

For another example of some cygpath coddling, see the following:

    http://cygwin.com/ml/cygwin/2002-10/msg00425.html

Homepage:

The primary Python web site is:

    http://www.python.org/

Download:

The primary Python ftp site is:

    ftp://ftp.python.org/pub/python/

Mailing Lists:

Please report problems, suggestions, etc. dependent on their nature to
one of the following:

    python-list@python.org
    cygwin@cygwin.com

Maintainer:

    Jason Tishler <jason@tishler.net>