This is a port of Python 2.2.3 to OS/2 using the EMX development tools
=========================================================================

What's new since the previous release
-------------------------------------

This release of the port incorporates the following changes from the 
Octover 4, 2002 release of the Python 2.2.2 port:

- based on the Python v2.2.3 release source.

I've revised the optimisation settings - see "YOU HAVE BEEN WARNED" 
item 21.
  

Licenses and info about Python and EMX
--------------------------------------

Please read the file README.Python-2.2.3 included in this package for 
information about Python 2.2.3.  This file is the README file from the 
Python 2.2.3 source distribution available via http://www.python.org/ 
and its mirrors.  The file LICENCE.Python-2.2.3 is the text of the Licence 
from the Python 2.2.3 source distribution.

Note that the EMX package that this package depends on is released under 
the GNU General Public Licence.  Please refer to the documentation 
accompanying the EMX Runtime libraries for more information about the 
implications of this.  A copy of version 2 of the GPL is included as the 
file COPYING.gpl2.

Readline and GDBM are covered by the GNU General Public Licence.  I think 
Eberhard Mattes' porting changes to BSD DB v1.85 are also GPL'ed (BSD DB 
itself is BSD Licenced).  ncurses and expat appear to be covered by MIT 
style licences - please refer to the source distributions for more detail.  
zlib is distributable under a very free license.  GNU MP and GNU UFC are 
under the GNU LGPL (see file COPYING.lib).

My patches to the Python-2.x source distributions, and any other packages 
used in this port, are placed in the public domain.

This software is provided 'as-is', without any express or implied warranty.
In no event will the author be held liable for any damages arising from the 
use of the software.

I do hope however that it proves useful to someone.


Other ports
-----------

There have been ports of previous versions of Python to OS/2.

The best known would be that by Jeff Rush, most recently of version 
1.5.2.  Jeff used IBM's Visual Age C++ (v3) for his ports, and his 
patches have been included in the Python 2.2.3 source distribution.

Andrew Zabolotny implemented a port of Python v1.5.2 using the EMX 
development tools.  His patches against the Python v1.5.2 source 
distribution have become the core of this port, and without his efforts 
this port wouldn't exist.  Andrew's port also appears to have been 
compiled with his port of gcc 2.95.2 to EMX, which I have but have 
chosen not to use for the binary distribution of this port (see item 21 
of the "YOU HAVE BEEN WARNED" section below).

Previous Python port releases by me:-
 - v2.0 on March 31, 2001;
 - v2.0 on April 25, 2001 (cleanup release + Stackless variant);
 - v2.1 on June 17, 2001;
 - v2.0 (Stackless re-release) on June 18, 2001;
 - v2.1.1 on August 5, 2001;
 - v2.1.1 on August 12, 2001 (cleanup release);
 - v2.1.1 (updated DLL) on August 14, 2001;
 - v2.2b2 on December 8, 2001 (not uploaded to archive sites);
 - v2.2c1 on December 16, 2001 (not uploaded to archive sites);
 - v2.2 on December 24, 2001;
 - v2.2.1c2 on March 31, 2002 (not uploaded to archive sites);
 - v2.2.1 on April 14, 2002;
 - v2.2.2 on October 24, 2002;
 - v2.3a2 on February 22, 2003 (not uploaded to archive sites);
 - v2.3b1 on April 27, 2003 (not uploaded to archive sites);
 - v2.2.3c1 on May 28, 2003 (not uploaded to archive sites).

It is possible to have these earlier ports still usable after installing 
this port - see the README.os2emx.multiple_versions file, contributed by
Dr David Mertz, for a suggested approach to achieving this.

This release should supercede any previous release in the Python 2.2 
series.


Software requirements
---------------------

This package requires the EMX Runtime package, available from the 
Hobbes (http://hobbes.nmsu.edu/) and LEO (http://archiv.leo.org/) 
archives of OS/2 software.  I have used EMX version 0.9d fix04 in 
developing this port.

My development system is running OS/2 v4 with fixpack 12.

3rd party software which has been linked into dynamically loaded modules:
- ncurses      (see http://dickey.his.com/ for more info, v5.2)
- GNU Readline (Kai Uwe Rommel's port available from Hobbes or LEO, v2.1)
- GNU GDBM     (Kai Uwe Rommel's port available from Hobbes or LEO, v1.7.3)
- zlib         (derived from Hung-Chi Chu's port of 1.1.3, v1.1.4)
- expat        (from ftp://ftp.jclark.com/pub/xml/, v1.2)
- GNU MP       (Peter Meerwald's port available from LEO, v2.0.2)
- GNU UFC      (Kai Uwe Rommel's port available from LEO, v2.0.4)

The zlib module no longer requires the Z.DLL to be installed - it is 
statically linked against a locally built version of zlib 1.1.4.

About this port
---------------

I have attempted to make this port as complete and functional as I can, 
notwithstanding the issues in the "YOU HAVE BEEN WARNED" section below.

Core components:

Python.exe is linked as an a.out executable, ie using EMX method E1 
to compile & link the executable.  This is so that fork() works (see 
"YOU HAVE BEEN WARNED" item 2).

Python22.dll is created as a normal OMF DLL, with an OMF import 
library and module definition file.  There is also an a.out (.a) import 
library to support linking the DLL to a.out executables.

The binary release of this port has been built with multithreading 
support enabled.

Modules:

As far as possible, extension modules have been made dynamically loadable 
when the module is intended to be built this way.  I haven't yet changed 
the building of Python's standard modules over to using the DistUtils.

See "YOU HAVE BEEN WARNED" item 5 for notes about the fcntl module, and 
"YOU HAVE BEEN WARNED" item 14 for notes about the pwd and grp modules.

Support for case sensitive module import semantics has been added to match 
the Windows release.  This can be deactivated by setting the PYTHONCASEOK 
environment variable (the value doesn't matter) - see "YOU HAVE BEEN WARNED" 
item 16.

Optional modules:

Where I've been able to locate the required 3rd party packages already 
ported to OS/2, I've built and included them.

These include ncurses (_curses, _curses_panel), BSD DB (bsddb), 
GNU GDBM (gdbm, dbm), zlib (zlib), GNU Readline (readline), expat 
(pyexpat), GNU MP (mpz) and GNU UFC (crypt).

I have built these modules statically linked against the 3rd party 
libraries.  Unfortunately my attempts to use the dll version of GNU 
readline have been a dismal failure, in that when the dynamically 
linked readline module is active other modules immediately provoke a 
core dump when imported.

Only the BSD DB package (part of the BSD package distributed with EMX) 
needed source modifications to be used for this port, pertaining to use 
of errno with multithreading.

The other packages, except for ncurses, needed Makefile changes for 
multithreading support but no source changes.  The static zlib library 
linked to the zlib library was "ported" by me, based on Hung-Chi Chu's 
DLL port of zlib 1.1.3.

The _curses_panel module is a potential problem - see "YOU HAVE BEEN 
WARNED" item 17.

If you have built other extension modules with the Python 2.2 EMX port,
they should work with this release without needing recompilation (they
may need to be reinstalled).

Upstream source patches:

Eberhard Mattes' EMXFIX04 update to his EMX 0.9d tools suite includes 
bug fixes for the BSD DB library.  The bsddb module included in this 
port incorporates these fixes.

Library and other distributed Python code:

The Python standard library lives in the Lib directory.  All the standard 
library code included with the Python 2.2.3 source distribution is included 
in the binary archive, with the exception of the dos-8x3 and tkinter 
subdirectories which have been omitted to reduce the size of the binary 
archive - the dos-8x3 components are unnecessary duplicates and Tkinter 
is not supported by this port (yet).  All the plat-* subdirectories in the 
source distribution have also been omitted, and a plat-os2emx directory 
included.

The Tools and Demo directories contain a collection of Python scripts.  
To reduce the size of the binary archive, the Demo/sgi, Demo/Tix, 
Demo/tkinter, Tools/audiopy, Tools/IDLE and Tools/pynche subdirectories 
have been omitted as not being supported by this port.  The Misc directory 
has also been omitted.

All subdirectories omitted from the binary archive can be reconstituted 
from the Python 2.2.3 source distribution, if desired.

Support for building Python extensions:

The Config subdirectory contains the files describing the configuration 
of the interpreter and the Makefile, import libraries for the Python DLL, 
and the module definition file used to create the Python DLL.  The 
Include subdirectory contains all the standard Python header files 
needed for building extensions.

As I don't have the Visual Age C++ compiler, I've made no attempt to 
have this port support extensions built with that compiler.


Packaging
---------

This port is packaged into several archives:
- python-2.2.3-os2emx-bin-021024.zip   (binaries, library modules)
- python-2.2.3-os2emx-src-021024.zip   (source patches and makefiles)

Documentation for the Python language, as well as the Python 2.2.3 
source distribution, can be obtained from the Python website 
(http://www.python.org/).


Installation
------------

Obtain and install, as per the included instructions, the EMX runtime 
package.

Unpack this archive, preserving the subdirectories, in the root directory 
of the drive where you want Python to live.

Add the Python directory (eg C:\Python22) to the PATH and LIBPATH 
variables in CONFIG.SYS.

You should then set the PYTHONHOME and PYTHONPATH environment variables 
in CONFIG.SYS.

PYTHONHOME should be set to Python's top level directory.  PYTHONPATH 
should be set to the semicolon separated list of principal Python library 
directories.
I use:
  SET PYTHONHOME=F:/Py/223c1
  SET PYTHONPATH=%PYTHONHOME%/Lib;%PYTHONHOME%/Lib/plat-os2emx;
                 %PYTHONHOME%/Lib/lib-dynload;%PYTHONHOME%/Lib/site-packages

NOTE!:  the PYTHONPATH setting above is linewrapped for this document - it 
should all be on one line in CONFIG.SYS!

If you wish to use the curses module, you should set the TERM and TERMINFO 
environment variables appropriately.

If you don't already have ncurses installed, I have included a copy of the 
EMX subset of the Terminfo database included with the ncurses-5.2 source 
distribution.  This can be used by setting the TERMINFO environment variable 
to the path of the Terminfo subdirectory below the Python home directory.
On my system this looks like:
  SET TERMINFO=%PYTHONHOME%/Terminfo

For the TERM environment variable, I would try one of the following:
  SET TERM=ansi
  SET TERM=os2
  SET TERM=window

You will have to reboot your system for these changes to CONFIG.SYS to take 
effect.

If you wish to compile all the included Python library modules to bytecode, 
you can change into the Python home directory and run the COMPILEALL.CMD 
batch file.

You can execute the regression tests included with the Python 2.2.3 source 
distribution by changing to the Python 2.2.3 home directory and executing the 
REGRTEST.CMD batch file.  The following tests are known to fail at this 
time:
- test_email (one item in the test expects \r\n line endings, but gets
  \n line endings - not sure whether this is a test bug);
- test_mhlib (I don't know of any port of MH to OS/2);
- test_pwd (see "YOU HAVE BEEN WARNED" item 14, probably a bug in my code);
- test_socket (passes as single test, but not as part of full regression 
  test [fork() related resulting from memory allocation in test_longexp]).
- test_socketserver (fork() related, see "YOU HAVE BEEN WARNED" item 2).


YOU HAVE BEEN WARNED!!
----------------------

I know about a number of nasties in this port.

{1.  Issue resolved...}

2.  Eberhard Mattes, author of EMX, writes in his documentation that fork() 
is very inefficient in the OS/2 environment.  It also requires that the 
executable be linked in a.out format rather than OMF.  Use the os.exec 
and/or the os.spawn family of functions where possible.

{3.  Issue resolved...}

4.  In the absence of GNU Readline, terminating the interpreter requires a 
control-Z (^Z) followed by a carriage return.  Jeff Rush documented this 
problem in his Python 1.5.2 port.  With Readline, a control-D (^D) works 
as per the standard Unix environment.

5.  EMX only has a partial implementation of fcntl().  The fcntl module 
in this port supports what EMX supports.  If fcntl is important to you, 
please review the EMX C Library Reference (included in .INF format in the 
EMXVIEW.ZIP archive as part of the complete EMX development tools suite).
Because of other side-effects I have modified the test_fcntl.py test 
script to deactivate the exercising of the missing functionality.

6.  The BSD DB module is linked against DB v1.85.  This version is widely 
known to have bugs, although some patches have become available (and are 
incorporated into the included bsddb module).  Unless you have problems 
with software licenses which would rule out GDBM (and the dbm module 
because it is linked against the GDBM library) or need it for file format 
compatibility, you may be better off deleting it and relying on GDBM.  I 
haven't looked at porting the version of the module supporting the later 
SleepyCat releases of BSD DB, which would also require a port of the 
SleepyCat DB package.

7.  The readline module has been linked against ncurses rather than the 
termcap library supplied with EMX.

{8.  Workaround implemented}

9.  I have configured this port to use "/" as the preferred path separator 
character, rather than "\" ('\\'), in line with the convention supported 
by EMX.  Backslashes are still supported of course, and still appear in 
unexpected places due to outside sources that don't get normalised.

10. While the DistUtils components are now functional, other 
packaging/binary handling tools and utilities such as those included in
the Demo and Tools directories - freeze in particular - are unlikely to 
work.  If you do get them going, I'd like to know about your success.

11. I haven't set out to support the [BEGIN|END]LIBPATH functionality 
supported by one of the earlier ports (Rush's??).  If it works let me know.

{12. as of the 2.2.1c2 release, the zlib module is now statically linked, 
so there are no Z.DLL dependencies.}

14. As a result of the limitations imposed by EMX's library routines, the 
standard extension module pwd only synthesises a simple passwd database, 
and the grp module cannot be supported at all.

I have written substitutes, in Python naturally, which can process real 
passwd and group files for those applications (such as MailMan) that 
require more than EMX emulates.  I have placed pwd.py and grp.py in 
Lib/plat-os2emx, which is usually before Lib/lib-dynload (which contains 
pwd.pyd) in the PYTHONPATH.  If you have become attached to what pwd.pyd 
supports, you can put Lib/lib-dynload before Lib/plat-os2emx in PYTHONPATH 
or delete/rename pwd.py & grp.py.

pwd.py & grp.py support locating their data files by looking in the 
environment for them in the following sequence:
pwd.py:  $ETC_PASSWD             (%ETC_PASSWD%)
         $ETC/passwd             (%ETC%/passwd)
         $PYTHONHOME/Etc/passwd  (%PYTHONHOME%/Etc/passwd)
grp.py:  $ETC_GROUP              (%ETC_GROUP%)
         $ETC/group              (%ETC%/group)
         $PYTHONHOME/Etc/group   (%PYTHONHOME%/Etc/group)

Both modules support using either the ":" character (Unix standard) or 
";" (OS/2, DOS, Windows standard) field separator character, and pwd.py 
implements the following drive letter conversions for the home_directory and 
shell fields (for the ":" separator only):
         $x  ->  x:
         x;  ->  x:

Example versions of passwd and group are in the Etc subdirectory.  Note 
that this code can fail the regression test, depending on the contents of 
the passwd file - specifically if there are entries with duplicate uids.

While this would be uncommon usage for a password file on OS/2, there are 
circumstances where a passwd file copied from a Unix system will contain 
duplicate uid entries, principally for the root account and a root 
"alter-ego" account with a different shell.

As the test passes on a FreeBSD machine with a root "alter-ego" account, 
I will have to pursue why the test fails with this module.

15. As of Python 2.1, termios support has mutated.  There is no longer a 
platform specific TERMIOS.py containing the symbolic constants - these 
now live in the termios module.  EMX's termios routines don't support all 
of the functionality now exposed by the termios module - refer to the EMX 
documentation to find out what is supported.

16. The case sensitive import semantics introduced in Python 2.1 for other 
case insensitive but case preserving file/operating systems (Windows etc), 
have been incorporated into this port, and are active by default.  Setting 
the PYTHONCASEOK environment variable (to any value) reverts to the 
previous (case insensitive) semantics.

17. Because I am statically linking ncurses, the _curses_panel 
module has potential problems arising from separate library data areas.
To avoid this, I have configured the _curses_.pyd (imported as 
"_curses_panel") to import the ncurses symbols it needs from _curses.pyd. 
As a result the _curses module must be imported before the _curses_panel 
module.  As far as I can tell, the modules in the curses package do this. 
If you have problems attempting to use the _curses_panel support please 
let me know, and I'll look into an alternative solution.

18. I tried enabling the Python Object Allocator (PYMALLOC) code.  While 
the port built this way passes the regression test, the Numpy extension 
(I tested v19.0.0) as built with the port's DistUtils code doesn't 
work.  Specifically, attempting to "import Numeric" provokes a core dump.  
Supposedly Numpy v20.1.0 contains a fix for this, but for reason outlined 
in item 1 above, PYMALLOC is not enabled in this release.

19. sys.platform now reports "os2emx" instead of "os2".  os.name still 
reports "os2".  This change was to make it easier to distinguish between 
the VAC++ build (which was being maintained by Michael Muller) and the 
EMX build (this port), principally for DistUtils.

20. it appears that the %W substitution in the EMX strftime() routine has 
an off-by-one bug.  strftime was listed as passing the regression tests 
in previous releases, but this fact appears to have been an oversight in 
the regression test suite.  To fix this really requires a portable 
strftime routine - I'm looking into using one from FreeBSD, but its not 
ready yet.

21. previous releases of my Python ports have used the GCC optimisations 
"-O2 -fomit-frame-pointer", and more recently just "-O2".

The change to -O2 was based on experimentation, however, with different 
hardware I can no longer replicate the results I was originally basing 
this choice on.  In particular, using -DNDEBUG (ie deactivating 
assertions) makes a noticeable difference, as does -fomit-frame-pointer.

With gcc 2.8.1, there is no benefit gained from using -O3, however 
Andrew Zabolotny's (p)gcc 2.95.2 compiler does produce marginally better 
results with -O3 than -O2 (2-3%).

I've not attempted to build this release with Andy's gcc 3.2.1 compiler, 
however I have no reason to expect that it shouldn't work.

[2001/08/12]

22.  As of this release, os.spawnv() and os.spawnve() now expose EMX's 
library routines rather than use the emulation in os.py.

In order to make use of some of the features this makes available in 
the OS/2 environment, you should peruse the relevant EMX documentation 
(EMXLIB.INF in the EMXVIEW.ZIP archive accompanying the EMX archives 
on Hobbes or LEO).  Be aware that I have exposed all the "mode" options 
supported by EMX, but there are combinations that either cannot be 
practically used by/in Python or have the potential to compromise your 
system's stability.

23.  pythonpm.exe in previous releases was just python.exe with the 
WINDOWAPI linker option set in the pythonpm.def file.  In practice, 
this turns out to do nothing useful.

I have written a replacement which wraps the Python DLL in a genuine 
Presentation Manager application.  This version actually runs the 
Python interpreter in a separate thread from the PM shell, in order 
that PythonPM has a functioning message queue as good PM apps should.
In its current state, PythonPM's window is hidden.  It can be displayed, 
although it will have no content as nothing is ever written to the 
window.  Only the "hide" button is available.  Although the code 
has support for shutting PythonPM down when the Python interpreter is 
still busy (via the "control" menu), this is not well tested and given 
comments I've come across in EMX documentation suggesting that the 
thread killing operation has problems I would suggest caution in 
relying on this capability.

PythonPM processes commandline parameters normally.  The standard input, 
output and error streams are only useful if redirected, as PythonPM's 
window is not a console in any form and so cannot accept or display 
anything.  This means that the -i option is ineffective.

Because the Python thread doesn't create its own message queue, creating 
PM Windows and performing most PM operations is not possible from within 
this thread.  How this will affect supporting PM extensions (such as 
Tkinter using a PM port of Tcl/Tk, or wxPython using the PM port of 
WxWindows) is still being researched.

Note that os.fork() _DOES_NOT_WORK_ in PythonPM - SYS3175s are the result 
of trying.  os.spawnv() _does_ work.  PythonPM passes all regression tests 
that the standard Python interpreter (python.exe) passes, with the exception 
of test_fork1 and test_socket which both attempt to use os.fork().

I very much want feedback on the performance, behaviour and utility of 
PythonPM.  I would like to add a PM console capability to it, but that 
will be a non-trivial effort.  I may be able to leverage the code in 
Illya Vaes' Tcl/Tk port, which would make it easier.

[2001/08/14]

24.  os.chdir() now uses EMX's _chdir2(), which supports changing 
both drive and directory at once.  Similarly, os.getcwd() now uses 
EMX's _getcwd() which returns drive as well as path.

[2001/12/08] - 2.2 Beta 2

25.  pyconfig.h (previously known as config.h) is now located in the 
Include subdirectory with all other include files.

[2001/12/16] - 2.2 Release Candidate 1

[2001/12/08] - 2.2 Final

[2002/03/31] - 2.2.1 Release Candidate 2

[2002/04/14] - 2.2.1 Final

[2002/10/24] - 2.2.2 Final

26.  while item 1 has been resolved, the EMX malloc() issues are still 
of concern.  PyMalloc helps noticeably, and will be enabled by default 
in Python 2.3.  In the mean time, users of this port should be aware 
that applications creating very large numbers of objects could still run 
into unexpected out-of-memory conditions.

[2003/5/28] - 2.2.3c1

[2003/6/01] - 2.2.3

27.  os.tmpfile() didn't exist, even though EMX includes tmpfile() - fixed.

28.  while an mmap() emulation library is available (freeware without 
source :-(), and the mmap module compiles without warnings with this 
library, the resulting module fails catastrophically on import.  I believe 
this is as a result of the library requiring extra calls to keep track 
of multiple threads, which are not part of the common Unix mmap API.  
These calls appear to need extensive changes to code outside the mmap 
module.  I would like to add support for mmap, but its going to take time.

29.  the _symtable module was not being built - fixed.

... probably other issues that I've not encountered, or don't remember :-(

If you encounter other difficulties with this port, which can be 
characterised as peculiar to this port rather than to the Python release,
I would like to hear about them.  However I cannot promise to be able to do 
anything to resolve such problems.  See the Contact section below...


To do...
--------

In no particular order of apparent importance or likelihood...

- support Tkinter and/or alternative GUI (wxWindows??)


Credits
-------

In addition to people identified above, I'd like to thank:
- the BDFL, Guido van Rossum, and crew for Python;
- Dr David Mertz, for trying out a pre-release of this port, 
  and letting me know about things I've missed;
- the Python-list/comp.lang.python community;
- John Poltorak, for input about pwd/grp;
- Stefan Schwarzer, for building a WarpIN package of 2.2.

Contact
-------

Constructive feedback, negative or positive, about this port is welcome 
and should be addressed to me at the e-mail addresses below.

I intend creating a private mailing list for announcements of fixes & 
updates to this port.  If you wish to receive such e-mail announcments, 
please send me an e-mail requesting that you be added to this list.

Andrew MacIntyre
E-mail: andymac@bullseye.apana.org.au, or andymac@pcug.org.au
Web:    http://www.andymac.org/

1 June, 2003.
