Update usage synopsis; fix miscellaneous typos

[p5sagit/p5-mst-13.2.git] / os2 / README

Current state of the patches here is with respect to perl5.002b1d ;-).

========================================================

The OS/2 patchkit was submitted by ilya@math.ohio-state.edu.  I have
applied some parts that I suspect won't cause any problems.
Others do things that I haven't had time to fully consider.

Still other patches included here should perhaps be integrated with the
metaconfig package that generates Configure.

	Andy Dougherty		<doughera@lafcol.lafayette.edu>

========================================================

Notes on the patch:
~~~~~~~~~~~~~~~~~~~
patches should be applied as
	patch -p0 <.....
All the diff.* files and POSIX.mkfifo should be applied.

Additional files are available on
	ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2
including patched pdksh and gnumake, needed for build.


Target:
~~~~~~~

This is not supposed to make a perfect Perl on OS/2. This patch is
concerned only with perfect _build_ of Perl on OS/2. A lot of good
features from Andreas Kaiser port missed this patch.

Annotations of changes: (part of what is below is already included by Andy,
~~~~~~~~~~~~~~~~~~~~~~~ thus there are skips below)
1) C files
2) Configure
3) MakeMaker
4) Build tools

1) C files
	a) mkfifo macro added to Posix.c
	b) Copyright notice for OS/2 port changed
	c) MYMALLOC section in perl.h moved (why?)
	d) setgrent grent and getgrent wrapped in ifdef
	e) declarations for #if defined(MYMALLOC) && defined(HIDEMYMALLOC)
		added
	f) some diagnostics added to tests

2) Configure 
	b) Support for extraction from NE style libraries.
	c) a lot of 
			cc -o whatever
		lines did not have $ldopts.
	d) The above variables are used throughout the file for checks

3) Build tools and libraries

	
	a) ln changed to $ln in some places
	b) Makefiles and related scripts made to use $(O), $(A), $(AR)
		using the vars found by Configure or defaulted to
		some reasonable value.
	c) $firstmakefile is the file make looks onto before Makefile
	d) $plibext is the extension for the perl library
	e) $archobjs is the list of additional object files needed for
		local build.
	l) Makefile.SH : added sh in front of some commands           
	   if $d_shrplib is 'custom', looks into                      
	        $osname/Makefile.$osname.SH to construct the section  
	        on shared Perl library.            
		!!!!!!	Also: installperl installman makedepend
		!!!!!!		added as dependencies to the corresponding 
		!!!!!!		targets.
	m) clean target extended to delete some intermediate files    

Notes on build on OS/2:
~~~~~~~~~~~~~~~~~~~~~~~
The change of C code in this patch is based on the ak port of 5.001+.

a) Make sure your sort is not the broken OS/2 one, and that you have /tmp
on the build partition.

b) when extraction perl5.*.tar.gz you need to extract perl5.*/Configure
separately, since by default perl5.001m/configure may overwrite it;
	like this:
		tar vzxf perl5.004.tar.gz --case-sensitive perl5.004/Configure

c) Necessary manual intervention when compiling on OS/2:

	Need to put perl.dll on LIBPATH after it is created.

d) Compile summary:

# Look for hints/os2.sh and correct what is different on your system
# I have rather spartan configuration.

	# Prefix means where to install:
sh Configure -des -D prefix=f:/perl5.005
make
	# Will probably die after build of miniperl (unless you have DLL
	# from previous compile). Need to move DLL where it belongs
	#
	# Somehow with 5.002b3 I needed to type another make after pod2man
make
	# some warnings in POSIX.c
make test
	# some tests fail, 9 or 10 on my system (see the list at end).
	#
	# before this you should create subdirs bin and lib in the 
	# prefix directory (f:/perl5.005 above):
make install

e) At the end of August GNU make and pdksh were too buggy for compile.
Both maintainers have patches that make it possible to compile perl.
The binaries are included in
	ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2
patches are available too.
Note that the pdksh5.2.4 broke builds with -Zexe option because of a
changed order of executable extensions. A patch is sent to maintainer.

!!!!!!!!!!!!!!!!!
If you see that some '/' became '\' in pdksh 5.2.3, you did not apply
my patches!
Same with segfaults in Make 3.74.
!!!!!!!!!!!!!!!!!

Problems reported: 

a) one of the latest tr is broken, get an old one :-(
	1.11 works. (On compuserver?)
b) You need a perlglob.exe and link386.
c) Get rid of invalid perl.dll on your LIBPATH.


Send comments to ilya@math.ohio-state.edu.

======================================================
Requires 0.9b (well, provision are made to make it build under 0.9a6,
but they are not tested, please inform me on success).
(earlier than 0.9b ttyname was not present, it is hard to maintain this
difference automatically, though I try).
======================================================

You may try building with a.out style by using `-D emxaout' on the Configure
line (dynamic extensions should not use CRT (and/or any perl API) in this
case, which prohibits most buildin extensions). Probably no extension is
possible, since boot code should return the amount on stack.

The reason why compiling with a.out style executables leads to problems
with dynamic extensions is:
	a) OS/2 does not export symbols from executables;
	b) Thus if extension needs to import symbols from an application
		the symbols for the application should reside in a .dll.
	c) You cannot export data from a .dll compiled with a.out style.
On the other hand, aout-style compiled extension enjoys all the 
(dis)advantages of fork().

======================================================
Tests which fail with OMF compile:

io/fs.t: 2-5, 7-11, 18  as they should.
io/pipe: all, since open("|-") is not working (even with fork, so far).
lib/"all the dbm".t: 1 test should fail (file permission).
op/fork all fail, as they should
op/stat 3 20 35 as they should, 39 (-t on /dev/null) ???? Sometimes 4 ????

Segfault in socket ????, only if run with Testing tools.

A lot of `bad free'... in databases, bug in DB confirmed on other
platforms.

Fail: Total 30 subtests (if stat:4 fails) in 10 scripts (one of 10
is socket, which runs OK standalone).

=======================================================

Changes to calls to external programs:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Due to a popular demand the perl external program calling has been changed.
_If_ perl needs to call an external program via shell, the sh.exe will be
called. The name of the shell is not overridable.

Thus means that you need to pickup some copy of a sh.exe as well (I use one
from pdksh).

Reasons: a consensus on perl5-porters was that perl should use one 
non-overridable shell per platform. The obvious choices for OS/2 are cmd.exe
and sh.exe. Having perl build itself would be impossible with cmd.exe as
a shell, thus I picked up sh.exe. Thus assures almost 100% compatibility
with the scripts coming from *nix.

Disadvantages: sh.exe calls external programs via fork/exec, and there is
_no_ functioning exec on OS/2. exec is emulated by EMX by asyncroneous call
while the caller waits for child completion (to pretend that pid did
not change). This means that 1 _extra_ copy of sh.exe is made active via
fork/exec, which may lead to some resources taken from the system.

The long-term solution proposed on p5-p is to have a directive
	use OS2::Cmd;
which will override system(), exec(), ``, and open(,'   |'). With current
perl you may override only system(), readpipe() - the explicit version
of ``, and maybe exec(). The code will substitute a one-argument system
by CORE::system('cmd.exe', '/c', shift).

If you have some working code for OS2::Cmd.pm, please send it to me,
I will include it into distribution. I have no need for such a module, so
cannot test it.

===================================================

OS/2 extensions
~~~~~~~~~~~~~~~
I include 3 extensions by Andread Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 
into my ftp directory, mirrored on CPAN. I made
some minor changes needed to compile them by standard tools. I cannot 
test UPM and FTP, so I will appreciate your feedback.

The -R switch of older perl is deprecated. If you need to call a REXX code
which needs access to variables, include the call into a REXX compartment
created by 
	REXX_call {...block...};

Two new functions are supported by REXX code, 
	REXX_eval 'string';
	REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;

If you have some other extensions you want to share, send the code to me.
Two jump to mind: tied access to EA's, and tied access to system databases.