symbian-qemu-0.9.1-12/python-2.6.1/PC/os2emx/README.os2emx
changeset 1 2fb8b9db1c86
equal deleted inserted replaced
0:ffa851df0825 1:2fb8b9db1c86
       
     1 This is a port of Python 2.6 to OS/2 using the EMX development tools
       
     2 =========================================================================
       
     3 
       
     4 What's new since the previous release
       
     5 -------------------------------------
       
     6 
       
     7 Another day, another version...
       
     8 
       
     9 
       
    10 Licenses and info about Python and EMX
       
    11 --------------------------------------
       
    12 
       
    13 Please read the file README.Python-2.6 included in this package for 
       
    14 information about Python 2.6.  This file is the README file from the 
       
    15 Python 2.6 source distribution available via http://www.python.org/ 
       
    16 and its mirrors.  The file LICENCE.Python-2.6 is the text of the Licence 
       
    17 from the Python 2.6 source distribution.
       
    18 
       
    19 Note that the EMX package that this package depends on is released under 
       
    20 the GNU General Public Licence.  Please refer to the documentation 
       
    21 accompanying the EMX Runtime libraries for more information about the 
       
    22 implications of this.  A copy of version 2 of the GPL is included as the 
       
    23 file COPYING.gpl2.
       
    24 
       
    25 Readline and GDBM are covered by the GNU General Public Licence.  I think 
       
    26 Eberhard Mattes' porting changes to BSD DB v1.85 are also GPL'ed (BSD DB 
       
    27 itself is BSD Licenced).  ncurses and expat appear to be covered by MIT 
       
    28 style licences - please refer to the source distributions for more detail.  
       
    29 zlib is distributable under a very free license.  GNU UFC is under the 
       
    30 GNU LGPL (see file COPYING.lib).
       
    31 
       
    32 My patches to the Python-2.x source distributions, and any other packages 
       
    33 used in this port, are placed in the public domain.
       
    34 
       
    35 This software is provided 'as-is', without any express or implied warranty.
       
    36 In no event will the author be held liable for any damages arising from the 
       
    37 use of the software.
       
    38 
       
    39 I do hope however that it proves useful to someone.
       
    40 
       
    41 
       
    42 Other ports
       
    43 -----------
       
    44 
       
    45 There have been ports of previous versions of Python to OS/2.
       
    46 
       
    47 The best known would be that by Jeff Rush, most recently of version 
       
    48 1.5.2.  Jeff used IBM's Visual Age C++ (v3) for his ports, and his 
       
    49 patches have been included in the Python 2.6 source distribution.
       
    50 
       
    51 Andy Zabolotny implemented a port of Python v1.5.2 using the EMX 
       
    52 development tools.  His patches against the Python v1.5.2 source 
       
    53 distribution have become the core of this port, and without his efforts 
       
    54 this port wouldn't exist.  Andy's port also appears to have been 
       
    55 compiled with his port of gcc 2.95.2 to EMX, which I have but have 
       
    56 chosen not to use for the binary distribution of this port (see item 16 
       
    57 of the "YOU HAVE BEEN WARNED" section below).
       
    58 
       
    59 It is possible to have these earlier ports still usable after installing 
       
    60 this port - see the README.os2emx.multiple_versions file, contributed by
       
    61 Dr David Mertz, for a suggested approach to achieving this.
       
    62 
       
    63 
       
    64 Software requirements
       
    65 ---------------------
       
    66 
       
    67 This package requires the EMX Runtime package, available from the 
       
    68 Hobbes (http://hobbes.nmsu.edu/) and LEO (http://archiv.leo.org/) 
       
    69 archives of OS/2 software.  I have used EMX version 0.9d fix04 in 
       
    70 developing this port.
       
    71 
       
    72 My development system is running OS/2 v4 with fixpack 12.
       
    73 
       
    74 3rd party software which has been linked into dynamically loaded modules:
       
    75 - ncurses      (see http://dickey.his.com/ for more info, v5.2)
       
    76 - GNU Readline (Kai Uwe Rommel's port available from Hobbes or LEO, v2.1)
       
    77 - GNU GDBM     (Kai Uwe Rommel's port available from Hobbes or LEO, v1.7.3)
       
    78 - zlib         (derived from Hung-Chi Chu's port of v1.1.3, v1.1.4)
       
    79 - expat        (distributed with Python, v1.95.6)
       
    80 - GNU UFC      (Kai Uwe Rommel's port available from LEO, v2.0.4)
       
    81 
       
    82 
       
    83 About this port
       
    84 ---------------
       
    85 
       
    86 I have attempted to make this port as complete and functional as I can, 
       
    87 notwithstanding the issues in the "YOU HAVE BEEN WARNED" section below.
       
    88 
       
    89 Core components:
       
    90 
       
    91 Python.exe is linked as an a.out executable, ie using EMX method E1 
       
    92 to compile & link the executable.  This is so that fork() works (see 
       
    93 "YOU HAVE BEEN WARNED" item 1).
       
    94 
       
    95 Python26.dll is created as a normal OMF DLL, with an OMF import 
       
    96 library and module definition file.  There is also an a.out (.a) import 
       
    97 library to support linking the DLL to a.out executables.  The DLL 
       
    98 requires the EMX runtime DLLs.
       
    99 
       
   100 This port has been built with complete support for multithreading.
       
   101 
       
   102 Modules:
       
   103 
       
   104 With the exception of modules that have a significant code size, or are 
       
   105 not recommended or desired for normal use, the standard modules are now 
       
   106 built into the core DLL rather than configured as dynamically loadable 
       
   107 modules.  This is for both reasons of performance (startup time) and 
       
   108 memory use (lots of small DLLs fragment the address space).
       
   109 
       
   110 I haven't yet changed the building of Python's dynamically loadable 
       
   111 modules over to using the DistUtils.
       
   112 
       
   113 See "YOU HAVE BEEN WARNED" item 3 for notes about the fcntl module, and 
       
   114 "YOU HAVE BEEN WARNED" item 10 for notes about the pwd and grp modules.
       
   115 
       
   116 This port supports case sensitive module import semantics, matching 
       
   117 the Windows release.  This can be deactivated by setting the PYTHONCASEOK 
       
   118 environment variable (the value doesn't matter) - see "YOU HAVE BEEN WARNED" 
       
   119 item 12.
       
   120 
       
   121 Optional modules:
       
   122 
       
   123 Where I've been able to locate the required 3rd party packages already 
       
   124 ported to OS/2, I've built and included them.
       
   125 
       
   126 These include ncurses (_curses, _curses_panel), BSD DB (bsddb185), 
       
   127 GNU GDBM (gdbm, dbm), zlib (zlib), GNU Readline (readline), and GNU UFC 
       
   128 (crypt).
       
   129 
       
   130 Expat is now included in the Python release sourceball, and the pyexpat 
       
   131 module is always built.
       
   132 
       
   133 I have built these modules statically linked against the 3rd party 
       
   134 libraries.  Unfortunately my attempts to use the dll version of GNU 
       
   135 readline have been a dismal failure, in that when the dynamically 
       
   136 linked readline module is active other modules immediately provoke a 
       
   137 core dump when imported.
       
   138 
       
   139 Only the BSD DB package (part of the BSD package distributed with EMX) 
       
   140 needs source modifications to be used for this port, pertaining to use 
       
   141 of errno with multithreading.
       
   142 
       
   143 The other packages, except for ncurses and zlib, needed Makefile changes 
       
   144 for multithreading support but no source changes.
       
   145 
       
   146 The _curses_panel module is a potential problem - see "YOU HAVE BEEN 
       
   147 WARNED" item 13.
       
   148 
       
   149 Upstream source patches:
       
   150 
       
   151 No updates to the Python 2.6 release have become available.
       
   152 
       
   153 Eberhard Mattes' EMXFIX04 update to his EMX 0.9d tools suite includes 
       
   154 bug fixes for the BSD DB library.  The bsddb module included in this 
       
   155 port incorporates these fixes.
       
   156 
       
   157 Library and other distributed Python code:
       
   158 
       
   159 The Python standard library lives in the Lib directory.  All the standard 
       
   160 library code included with the Python 2.6 source distribution is included 
       
   161 in the binary archive, with the exception of the dos-8x3 and tkinter 
       
   162 subdirectories which have been omitted to reduce the size of the binary 
       
   163 archive - the dos-8x3 components are unnecessary duplicates and Tkinter 
       
   164 is not supported by this port (yet).  All the plat-* subdirectories in the 
       
   165 source distribution have also been omitted, except for the plat-os2emx 
       
   166 subdirectory.
       
   167 
       
   168 The Tools and Demo directories contain a collection of Python scripts.  
       
   169 To reduce the size of the binary archive, the Demo/sgi, Demo/Tix, 
       
   170 Demo/tkinter, Tools/audiopy and Tools/IDLE subdirectories have been 
       
   171 omitted as not being supported by this port.  The Misc directory has 
       
   172 also been omitted.
       
   173 
       
   174 All subdirectories omitted from the binary archive can be reconstituted 
       
   175 from the Python 2.6 source distribution, if desired.
       
   176 
       
   177 Support for building Python extensions:
       
   178 
       
   179 The Config subdirectory contains the files describing the configuration 
       
   180 of the interpreter and the Makefile, import libraries for the Python DLL, 
       
   181 and the module definition file used to create the Python DLL.  The 
       
   182 Include subdirectory contains all the standard Python header files 
       
   183 needed for building extensions.
       
   184 
       
   185 As I don't have the Visual Age C++ compiler, I've made no attempt to 
       
   186 have this port support extensions built with that compiler.
       
   187 
       
   188 
       
   189 Packaging
       
   190 ---------
       
   191 
       
   192 This port is packaged as follows:
       
   193 - python-2.6-os2emx-bin-03????.zip  (binaries, library modules)
       
   194 - python-2.6-os2emx-src-03????      (patches+makefiles for non-Python code)
       
   195 
       
   196 As all the Python specific patches for the port are now part of the 
       
   197 Python release tarball, only the patches and makefiles involved in 
       
   198 building external libraries for optional extensions are included in 
       
   199 the source archive.
       
   200 
       
   201 Documentation for the Python language, as well as the Python 2.6 
       
   202 source distibution, can be obtained from the Python website 
       
   203 (http://www.python.org/) or the Python project pages at Sourceforge 
       
   204 (http://sf.net/projects/python/).
       
   205 
       
   206 
       
   207 Installation
       
   208 ------------
       
   209 
       
   210 Obtain and install, as per the included instructions, the EMX runtime 
       
   211 package.
       
   212 
       
   213 Unpack this archive, preserving the subdirectories, in the root directory 
       
   214 of the drive where you want Python to live.
       
   215 
       
   216 Add the Python directory (eg C:\Python26) to the PATH and LIBPATH 
       
   217 variables in CONFIG.SYS.
       
   218 
       
   219 You should then set the PYTHONHOME and PYTHONPATH environment variables 
       
   220 in CONFIG.SYS.
       
   221 
       
   222 PYTHONHOME should be set to Python's top level directory.  PYTHONPATH 
       
   223 should be set to the semicolon separated list of principal Python library 
       
   224 directories.
       
   225 I use:
       
   226   SET PYTHONHOME=F:/Python26
       
   227   SET PYTHONPATH=F:/Python26/Lib;F:/Python26/Lib/plat-os2emx;
       
   228                  F:/Python26/Lib/lib-dynload;F:/Python26/Lib/site-packages
       
   229 
       
   230 NOTE!:  the PYTHONPATH setting above is linewrapped for this document - it 
       
   231 should all be on one line in CONFIG.SYS!
       
   232 
       
   233 If you wish to use the curses module, you should set the TERM and TERMINFO 
       
   234 environment variables appropriately.
       
   235 
       
   236 If you don't already have ncurses installed, I have included a copy of the 
       
   237 EMX subset of the Terminfo database included with the ncurses-5.2 source 
       
   238 distribution.  This can be used by setting the TERMINFO environment variable 
       
   239 to the path of the Terminfo subdirectory below the Python home directory.
       
   240 On my system this looks like:
       
   241   SET TERMINFO=F:/Python26/Terminfo
       
   242 
       
   243 For the TERM environment variable, I would try one of the following:
       
   244   SET TERM=ansi
       
   245   SET TERM=os2
       
   246   SET TERM=window
       
   247 
       
   248 You will have to reboot your system for these changes to CONFIG.SYS to take 
       
   249 effect.
       
   250 
       
   251 If you wish to compile all the included Python library modules to bytecode, 
       
   252 you can change into the Python home directory and run the COMPILEALL.CMD 
       
   253 batch file.
       
   254 
       
   255 You can execute the regression tests included with the Python 2.6 source 
       
   256 distribution by changing to the Python 2.6 home directory and executing the 
       
   257 REGRTEST.CMD batch file.  The following tests are known to fail at this 
       
   258 time:
       
   259 - test_mhlib (I don't know of any port of MH to OS/2);
       
   260 - test_strptime (see "YOU HAVE BEEN WARNED" item 22);
       
   261 - test_time (see "YOU HAVE BEEN WARNED" item 22);
       
   262 - test_posixpath (see "YOU HAVE BEEN WARNED" item 23).
       
   263 
       
   264 Note that some of the network related tests expect the loopback interface
       
   265 (interface "lo", with IP address 127.0.0.1) to be enabled, which from my
       
   266 experience is not the default configuration.  Additionally, test_popen2
       
   267 expects the "cat" utility (such as found in ports of the GNU tools) to
       
   268 be installed.
       
   269 
       
   270 
       
   271 Building from source
       
   272 --------------------
       
   273 
       
   274 With the EMX port now checked into Python's CVS repository, the build 
       
   275 infrastructure is part of the Python release sourceball.
       
   276 
       
   277 Prerequisites
       
   278 
       
   279 First and foremost, you need an operational EMX development installation - 
       
   280 EMX v0.9d with fix04 (the latest at time of writing) & the gcc 2.8.1 
       
   281 compiler released by Eberhard Mattes is the recommended setup.
       
   282 
       
   283 If you have a different version of gcc installed, see "YOU HAVE BEEN 
       
   284 WARNED" item 16.
       
   285 
       
   286 Other items of software required:-
       
   287 
       
   288 - GNU make (I'm using v3.76.1)
       
   289 - rm, cp, mkdir from the GNU file utilities package
       
   290 - GNU find
       
   291 - GNU sed
       
   292 
       
   293 Procedure
       
   294 
       
   295 0. all changes mentioned apply to files in the PC/os2emx subdirectory 
       
   296    of the Python release source tree.  make is also executed from this 
       
   297    directory, so change into this directory before proceeding.
       
   298 
       
   299 1. decide if you need to change the location of the Python installation.
       
   300    If you wish to do this, set the value of the Makefile variable LIB_DIR 
       
   301    to the directory you wish to use for PYTHONHOME 
       
   302    (eg /usr/local/lib/python2.6).
       
   303 
       
   304    If you want Python to find its library without the PYTHONHOME 
       
   305    environment variable set, set the value of the Makefile variable 
       
   306    FIXED_PYHOME to "yes" (uncomment the appropriate line).
       
   307 
       
   308 2. If you wish the Python executables (python.exe, pythonpm.exe & pgen.exe) 
       
   309    to be installed in a directory other than the PYTHONHOME directory, set 
       
   310    the value of the Makefile variable EXE_DIR to the appropriate directory.
       
   311 
       
   312 3. If you wish the Python core DLL (python26.dll) to be installed in a 
       
   313    directory other than the directory in which the Python executables are 
       
   314    installed (by default, the PYTHONHOME directory), set the value of the 
       
   315    Makefile variable DLL_DIR to the appropriate directory.  This DLL must 
       
   316    be placed in a directory on the system's LIBPATH, or that gets set 
       
   317    with BEGINLIBPATH or ENDLIBPATH.
       
   318 
       
   319 4. If you have installed any of the libraries that can be used to build 
       
   320    optional Python modules, set the value of the relevant HAVE_<package> 
       
   321    Makefile variable to "yes".  The Makefile currently supports:
       
   322 
       
   323    library               Makefile variable
       
   324    ........................................
       
   325    zlib (1.1.4)          HAVE_ZLIB
       
   326    GNU UltraFast Crypt   HAVE_UFC
       
   327    Tcl/Tk                HAVE_TCLTK (not known to work)
       
   328    GNU Readline          HAVE_GREADLINE
       
   329    BSD DB (v1.85)        HAVE_BSDDB
       
   330    ncurses               HAVE_NCURSES
       
   331    GNU gdbm              HAVE_GDBM
       
   332    libbz2                HAVE_BZ2
       
   333    OpenSSL               HAVE_OPENSSL
       
   334 
       
   335    Please note that you need to check that what you have installed 
       
   336    is compatible with Python's build options.  In particular, the 
       
   337    BSD DB v1.85 library needs to be rebuilt with a source patch for 
       
   338    multithread support (doesn't change the library's reentrant status 
       
   339    but allows it to be linked to Python which is multithreaded).  
       
   340    Widely available binary packages of other librarys & DLLs are 
       
   341    not built/linked with multithread support.  Beware!
       
   342 
       
   343    Also note that the Makefile currently expects any libraries to be 
       
   344    found with the default library search path.  You may need to add 
       
   345    -L switches to the LDFLAGS Makefile variable if you have installed 
       
   346    libraries in directories not in the default search path (which can 
       
   347    be controlled by the LIBRARY_PATH environment variable used by EMX).
       
   348 
       
   349 5. make
       
   350 
       
   351    It is usually a good idea to redirect the stdout and stderr streams 
       
   352    of the make process to log files, so that you can review any messages. 
       
   353 
       
   354 6. make test
       
   355 
       
   356    This runs the Python regression tests, and completion is a sign of 
       
   357    a usable build.  You should check the list of skipped modules to 
       
   358    ensure that any optional modules you selected have been built; 
       
   359    checking the list of failures against the list of known failures 
       
   360    elsewhere in this document is also prudent.
       
   361 
       
   362 7. make install
       
   363    >>>>>> NOT YET COMPLETE <<<<<< 
       
   364 
       
   365 8. change to a directory outside the Python source tree and start Python. 
       
   366    Check the version and build date to confirm satisfactory installation.
       
   367 
       
   368 
       
   369 YOU HAVE BEEN WARNED!!
       
   370 ----------------------
       
   371 
       
   372 I know about a number of nasties in this port.
       
   373 
       
   374 1.  Eberhard Mattes, author of EMX, writes in his documentation that fork() 
       
   375 is very inefficient in the OS/2 environment.  It also requires that the 
       
   376 executable be linked in a.out format rather than OMF.  Use the os.exec 
       
   377 and/or the os.spawn family of functions where possible.
       
   378 
       
   379 2.  In the absence of GNU Readline, terminating the interpreter requires a 
       
   380 control-Z (^Z) followed by a carriage return.  Jeff Rush documented this 
       
   381 problem in his Python 1.5.2 port.  With Readline, a control-D (^D) works 
       
   382 as per the standard Unix environment.
       
   383 
       
   384 3.  EMX only has a partial implementation of fcntl().  The fcntl module 
       
   385 in this port supports what EMX supports.  If fcntl is important to you, 
       
   386 please review the EMX C Library Reference (included in .INF format in the 
       
   387 EMXVIEW.ZIP archive as part of the complete EMX development tools suite).
       
   388 Because of other side-effects I have modified the test_fcntl.py test 
       
   389 script to deactivate the exercising of the missing functionality.
       
   390 
       
   391 4.  the PyBSDDB3 module has been imported into the Python standard
       
   392 library, with the intent of superceding the BSDDB 1.85 module (bsddb).
       
   393 As I don't yet have a satisfactory port of Sleepcat's more recent DB
       
   394 library (3.3.x/4.0.x/4.1.x), I haven't included a binary of this
       
   395 module.  I have left the Python part of the PyBSDDB package in this
       
   396 distribution for completeness.
       
   397 
       
   398 5.  As a consequence of the PyBSDDB3 module being imported, the former 
       
   399 BSD DB (bsddb) module, linked against the DB v1.85 library from EMX, 
       
   400 has been renamed bsddb185.  The bsddb185 module will not be built by 
       
   401 default on most platforms, but in the absence of a PyBSDDB3 module I 
       
   402 have retained it in the EMX port.
       
   403 
       
   404 Version 1.85 of the DB library is widely known to have bugs, although 
       
   405 some patches have become available (and are incorporated into the 
       
   406 included bsddb185 module).  Unless you have problems with software 
       
   407 licenses which would rule out GDBM (and the dbm module because it is 
       
   408 linked against the GDBM library) or need it for file format compatibility, 
       
   409 you may be better off deleting it and relying on GDBM.
       
   410 
       
   411 Any code you have which uses the v1.85 bsddb module can be modified to 
       
   412 use the renamed module by changing
       
   413 
       
   414   import bsddb
       
   415 
       
   416 to
       
   417 
       
   418   import bsddb185 as bsddb
       
   419 
       
   420 6.  The readline module has been linked against ncurses rather than the 
       
   421 termcap library supplied with EMX.
       
   422 
       
   423 7.  I have configured this port to use "/" as the preferred path separator 
       
   424 character, rather than "\" ('\\'), in line with the convention supported 
       
   425 by EMX.  Backslashes are still supported of course, and still appear in 
       
   426 unexpected places due to outside sources that don't get normalised.
       
   427 
       
   428 8.  While the DistUtils components are now functional, other 
       
   429 packaging/binary handling tools and utilities such as those included in
       
   430 the Demo and Tools directories - freeze in particular - are unlikely to 
       
   431 work.  If you do get them going, I'd like to know about your success.
       
   432 
       
   433 9.  I haven't set out to support the [BEGIN|END]LIBPATH functionality 
       
   434 supported by one of the earlier ports (Rush's??).  If it works let me know.
       
   435 
       
   436 10. As a result of the limitations imposed by EMX's library routines, the 
       
   437 standard extension module pwd only synthesises a simple passwd database, 
       
   438 and the grp module cannot be supported at all.
       
   439 
       
   440 I have written pure Python substitutes for pwd and grp, which can process 
       
   441 real passwd and group files for those applications (such as MailMan) that 
       
   442 require more than EMX emulates.  I have placed pwd.py and grp.py in 
       
   443 Lib/plat-os2emx, which is usually before Lib/lib-dynload (which contains 
       
   444 pwd.pyd) in the PYTHONPATH.  If you have become attached to what pwd.pyd 
       
   445 supports, you can put Lib/lib-dynload before Lib/plat-os2emx in PYTHONPATH 
       
   446 or delete/rename pwd.py & grp.py.
       
   447 
       
   448 pwd.py & grp.py support locating their data files by looking in the 
       
   449 environment for them in the following sequence:
       
   450 pwd.py:  $ETC_PASSWD             (%ETC_PASSWD%)
       
   451          $ETC/passwd             (%ETC%/passwd)
       
   452          $PYTHONHOME/Etc/passwd  (%PYTHONHOME%/Etc/passwd)
       
   453 grp.py:  $ETC_GROUP              (%ETC_GROUP%)
       
   454          $ETC/group              (%ETC%/group)
       
   455          $PYTHONHOME/Etc/group   (%PYTHONHOME%/Etc/group)
       
   456 
       
   457 The ETC_PASSWD and ETC_GROUP environment variables are intended to allow 
       
   458 support for multiple passwd/grp files, where other applications may not 
       
   459 support as wide a variety of input variations (drive remappings, 
       
   460 separators etc).
       
   461 
       
   462 Both modules support using either the ":" character (Unix standard) or 
       
   463 ";" (OS/2, DOS, Windows standard) field separator character, and pwd.py 
       
   464 implements the following drive letter conversions for the home_directory and 
       
   465 shell fields (for the ":" separator only):
       
   466          $x  ->  x:
       
   467          x;  ->  x:
       
   468 
       
   469 Example versions of passwd and group are in the Etc subdirectory.  The 
       
   470 regression tests (test_pwd and test_grp) will fail if valid password and 
       
   471 group files cannot be found, but should pass otherwise.
       
   472 
       
   473 Be aware that Python's pwd & group modules are for reading password and 
       
   474 group information only.
       
   475 
       
   476 11. EMX's termios routines don't support all of the functionality now 
       
   477 exposed by the termios module - refer to the EMX documentation to find 
       
   478 out what is supported.
       
   479 
       
   480 12. The case sensitive import semantics introduced in Python 2.1 for other 
       
   481 case insensitive but case preserving file/operating systems (Windows etc), 
       
   482 have been incorporated into this port, and are active by default.  Setting 
       
   483 the PYTHONCASEOK environment variable (to any value) reverts to the 
       
   484 previous (case insensitive) semantics.  This can be an issue with some 
       
   485 file management utilities that do not preserve the case of file and
       
   486 directory names.
       
   487 
       
   488 13. Because I am statically linking ncurses, the _curses_panel 
       
   489 module has potential problems arising from separate library data areas.
       
   490 To avoid this, I have configured the _curses_.pyd (imported as 
       
   491 "_curses_panel") to import the ncurses symbols it needs from _curses.dll 
       
   492 (which is the curses module, but with a .dll extension rather than .pyd 
       
   493 so that the dynamic loader can actually import the symbols from it as a 
       
   494 DLL).
       
   495 
       
   496 The site module (Lib/site.py) has code added to tweak BEGINLIBPATH so
       
   497 that _curses.dll is found when _curses_panel is imported.  If you have
       
   498 problems attempting to use the _curses_panel support please let me know,
       
   499 and I'll have another look at this.
       
   500 
       
   501 14. sys.platform reports "os2emx" instead of "os2".  os.name still 
       
   502 reports "os2".  This change was to make it easier to distinguish between 
       
   503 the VAC++ build (formerly maintained by Michael Muller) and the EMX build 
       
   504 (this port), principally for DistUtils.
       
   505 
       
   506 15. it appears that the %W substitution in the EMX strftime() routine has 
       
   507 an off-by-one bug.  strftime was listed as passing the regression tests 
       
   508 in previous releases, but this fact appears to have been an oversight in 
       
   509 the regression test suite.  To fix this really requires a portable 
       
   510 strftime routine - I'm looking into using one from FreeBSD, but its not 
       
   511 ready yet.
       
   512 
       
   513 16. I have successfully built this port with Andy Zabolotny's ports of 
       
   514 pgcc 2.95 and gcc 3.2.1, in addition to EM's gcc 2.8.1.  To use the 
       
   515 bsddb185 module with the gcc 3.2.1 build, I had to recompile the DB library 
       
   516 with gcc 3.2.1 - I don't know why, but trying to import the module built 
       
   517 against a DB library compiled with gcc 2.8.1 would result in a SYS3175 
       
   518 error.
       
   519 
       
   520 I have not attempted to compile Python with any version of gcc prior to 
       
   521 v2.8.1.
       
   522 
       
   523 This release sees the default optimisation change to 
       
   524 "-O3 -fomit-frame-pointer -mprobe".  This works fine too for pgcc 2.95 
       
   525 but not for gcc 3.2.1.
       
   526 
       
   527 With gcc 3.2.1, -O3 causes 2 unexpected test failures: test_format and 
       
   528 test_unicode.  Both these tests pass if -O2 is instead of -O3 with this 
       
   529 compiler, and the performance difference is negligible (in contrast to 
       
   530 gcc 2.8.1 and pgcc 2.95, where the performance difference between the 
       
   531 2 optimisation settings approaches 10%).
       
   532 
       
   533 17.  os.spawnv() and os.spawnve() expose EMX's library routines rather 
       
   534 than use the emulation in os.py.
       
   535 
       
   536 In order to make use of some of the features this makes available in 
       
   537 the OS/2 environment, you should peruse the relevant EMX documentation 
       
   538 (EMXLIB.INF in the EMXVIEW.ZIP archive accompanying the EMX archives 
       
   539 on Hobbes or LEO).  Be aware that I have exposed all the "mode" options 
       
   540 supported by EMX, but there are combinations that either cannot be 
       
   541 practically used by/in Python or have the potential to compromise your 
       
   542 system's stability.
       
   543 
       
   544 18.  pythonpm.exe used to be just python.exe with the WINDOWAPI linker 
       
   545 option set in the pythonpm.def file.  In practice, this turns out to do 
       
   546 nothing useful.
       
   547 
       
   548 I have written a replacement which wraps the Python DLL in a genuine 
       
   549 Presentation Manager application.  This version actually runs the 
       
   550 Python interpreter in a separate thread from the PM shell, in order 
       
   551 that PythonPM has a functioning message queue as good PM apps should.
       
   552 In its current state, PythonPM's window is hidden.  It can be displayed, 
       
   553 although it will have no content as nothing is ever written to the 
       
   554 window.  Only the "hide" button is available.  Although the code 
       
   555 has support for shutting PythonPM down when the Python interpreter is 
       
   556 still busy (via the "control" menu), this is not well tested and given 
       
   557 comments I've come across in EMX documentation suggesting that the 
       
   558 thread killing operation has problems I would suggest caution in 
       
   559 relying on this capability.
       
   560 
       
   561 PythonPM processes commandline parameters normally.  The standard input, 
       
   562 output and error streams are only useful if redirected, as PythonPM's 
       
   563 window is not a console in any form and so cannot accept or display 
       
   564 anything.  This means that the -i option is ineffective.
       
   565 
       
   566 Because the Python thread doesn't create its own message queue, creating 
       
   567 PM Windows and performing most PM operations is not possible from within 
       
   568 this thread.  How this will affect supporting PM extensions (such as 
       
   569 Tkinter using a PM port of Tcl/Tk, or wxPython using the PM port of 
       
   570 WxWindows) is still being researched.
       
   571 
       
   572 Note that os.fork() _DOES_NOT_WORK_ in PythonPM - SYS3175s are the result 
       
   573 of trying.  os.spawnv() _does_ work.  PythonPM passes all regression tests 
       
   574 that the standard Python interpreter (python.exe) passes, with the exception 
       
   575 of test_fork1 and test_socket which both attempt to use os.fork().
       
   576 
       
   577 I very much want feedback on the performance, behaviour and utility of 
       
   578 PythonPM.  I would like to add a PM console capability to it, but that 
       
   579 will be a non-trivial effort.  I may be able to leverage the code in 
       
   580 Illya Vaes' Tcl/Tk port, which would make it easier.
       
   581 
       
   582 19.  os.chdir() uses EMX's _chdir2(), which supports changing both drive 
       
   583 and directory at once.  Similarly, os.getcwd() uses EMX's _getcwd() 
       
   584 which returns drive as well as path.
       
   585 
       
   586 20.  pyconfig.h is installed in the Include subdirectory with all 
       
   587 other include files.
       
   588 
       
   589 21.  the default build explicitly sets the number of file handles 
       
   590 available to a Python process to 250.  EMX default is 40, which is 
       
   591 insufficient for the tempfile regression test (test_tempfile) which 
       
   592 tries to create 100 temporary files.
       
   593 
       
   594 This setting can be overridden via the EMXOPT environment variable:
       
   595   set EMXOPT=-h250
       
   596 is equivalent to the setting currently used.  The emxbind utility (if you 
       
   597 have it installed) can also be used to permanently change the setting in 
       
   598 python.exe - please refer to the EMX documentation for more information.
       
   599 
       
   600 22.  a pure python strptime module is now part of the Python standard
       
   601 library, superceding a platform specific extension module. This module
       
   602 leverages the strftime module, and as a result test_strptime fails
       
   603 due to the EMX strftime bug in item 20 above.
       
   604 
       
   605 23.  test_posixpath attempts to exercise various Posix path related
       
   606 functionality.  Most of the sub-tests pass, but the "ismount" and
       
   607 "samestat" subtests fail:
       
   608 - EMX provides not satisfactory mount point emulation, so "ismount"
       
   609   cannot succeed;
       
   610 - EMX documents that successive stat() calls will produce different
       
   611   results, so "samestat" cannot succeed.
       
   612 
       
   613 test_posixpath should skip these tests on EMX.
       
   614 
       
   615 24.  I have reports of BitTorrent not working.  It appears that the
       
   616 EMX select() emulation, possibly in concert with bugs in the TCP/IP
       
   617 stack, runs into problems under the stress imposed by this application.
       
   618 I think it suffices to say that BitTorrent is a fair stress test of a
       
   619 system's networking capability.
       
   620 
       
   621 25.  In the absence of an EMX implementation of the link() function, I've 
       
   622 implemented a crude Python emulation, in the file 
       
   623 Lib/plat-os2emx/_emx_link.py.  This is imported into the os module, and 
       
   624 becomes available as os.link() in the normal way.
       
   625 
       
   626 The emulation copies the source file in binary mode, and will fail if 
       
   627 disk space is exhausted. The call fails if the target already exists. 
       
   628 There are no guarantees to thread safety with this emulation - beware!
       
   629 
       
   630 The emulation was written to support a link() based file locking system 
       
   631 used in GNU Mailman.
       
   632 
       
   633 26.  AF_UNIX sockets, otherwise known as Unix domain sockets, are now
       
   634 supported.  Unfortunately, there are some traps arising from the
       
   635 implementation in IBM's TCP/IP stack:-
       
   636 - the path name must start with '\\socket\\' ('/socket/' won't work!),
       
   637   with the length of the full path name less than 108 characters;
       
   638 - unlike Unix, the socket endpoints don't exist in the filesystem;
       
   639 - by default, sockets are in binary mode.
       
   640 
       
   641 27.  As of Python 2.4, the mpz, rotor and xreadlines modules have been 
       
   642 dropped from the Python source tree.
       
   643 
       
   644 28.  The subprocess module was added to the standard library relatively
       
   645 late in the 2.4 development cycle.  Unfortunately I haven't had the
       
   646 round tuits to adapt the module to the EMX environment yet, and
       
   647 test_subprocess has a number of failures as a result.
       
   648 
       
   649 29.  The default stack size for threads has been 64k.  This is proving
       
   650 insufficient for some codebases, such as Zope.  The thread stack size
       
   651 still defaults to 64k, but this can now be increased via the stack_size()
       
   652 function exposed by the threading & thread modules as well as by defining
       
   653 THREAD_STACK_SIZE to an appropriate value in the Makefile (which contains
       
   654 a commented out definition for 128kB thread stacks).  I have seen
       
   655 references to heavy Zope/Plone usage requiring 1MB thread stacks on
       
   656 FreeBSD and Linux, but doubt that for most likely usage on OS/2 that
       
   657 more than 256kB is necessary.  The size of the required stacks (main 
       
   658 and thread) can vary significantly depending on which version of gcc
       
   659 is used along with the compiler optimisations selected.  Note that the
       
   660 main thread stack size is set during linking and is currently 2MB.
       
   661 
       
   662 ... probably other issues that I've not encountered, or don't remember :-(
       
   663 
       
   664 If you encounter other difficulties with this port, which can be 
       
   665 characterised as peculiar to this port rather than to the Python release,
       
   666 I would like to hear about them.  However I cannot promise to be able to do 
       
   667 anything to resolve such problems.  See the Contact section below...
       
   668 
       
   669 
       
   670 To do...
       
   671 --------
       
   672 
       
   673 In no particular order of apparent importance or likelihood...
       
   674 
       
   675 - support Tkinter and/or alternative GUI (wxWindows??)
       
   676 
       
   677 
       
   678 Credits
       
   679 -------
       
   680 
       
   681 In addition to people identified above, I'd like to thank:
       
   682 - the BDFL, Guido van Rossum, and crew for Python;
       
   683 - Dr David Mertz, for trying out a pre-release of this port;
       
   684 - the Python-list/comp.lang.python community;
       
   685 - John Poltorak, for input about pwd/grp.
       
   686 
       
   687 Contact
       
   688 -------
       
   689 
       
   690 Constructive feedback, negative or positive, about this port is welcome 
       
   691 and should be addressed to me at the e-mail addresses below.
       
   692 
       
   693 I have a private mailing list for announcements of fixes & updates to 
       
   694 this port.  If you wish to receive such e-mail announcments, please send 
       
   695 me an e-mail requesting that you be added to this list.
       
   696 
       
   697 Andrew MacIntyre
       
   698 E-mail: andymac@bullseye.apana.org.au, or andymac@pcug.org.au
       
   699 Web:    http://www.andymac.org/
       
   700 
       
   701 28 January, 2008.