$Id: README,v 1.14 2002/06/25 17:53:47 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.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)
    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-20001125-1  (_tkinter)
    zlib-1.1.3-6      (zlib)

Install:

Cygwin Python does not require any special installation procedures.
However, to use the _tkinter module you must define the following
environment variables:

    $ export TCL_LIBRARY=$(cygpath -w /usr/share/tcl8.0)
    $ export TK_LIBRARY=$(cygpath -w /usr/share/tk8.0)

since tcltk-20001125-1 is a native Win32 (i.e., not Cygwin) application.

Source:

At the time of this writing, 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, the Python source has been patched to
workaround this problem.  See the issues section for more details.

Additionally, the test_mmap regression test has been patched because
a recent change made it fail under Cygwin.  See the following for more
details:

    http://sourceforge.net/tracker/?func=detail&atid=305470&aid=544733&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-2.2.1.tar.bz2: pre-generated Python HTML documentation
        since Cygwin cannot currently self-generate the documentation

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.  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-20001125-1 source archive have been copied to
/usr/include:

    $ mkdir -p /usr/include/X11
    $ tar -xzf tcltk-20001125-1-src.tar.gz
    $ cp tcltk-20001125-1/tk/xlib/X11/*.h /usr/include/X11

3. Due to issues with Cygwin's fork() and DLL base address conflicts,
the _socket module should be built statically instead of shared as is
the default.  Otherwise, Python scripts that import the _socket module
and call fork() will fail.  This problem should be corrected for all
Cygwin apps (including Python) when a DLL rebasing tool is integrated
into the standard Cygwin distribution.  See the following for details:

    http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html

4. Due to a recent change, the test_commands regression test will fail if
the user and/or group names of the root directory (i.e., "/") contain spaces.

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>