X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.os2;h=409c7745914dada6652f436cb0dcc0b7d5280a17;hb=fcbfa962e80dc16f8db1afaeb5287e8a393d3942;hp=f5bf87db0669729f4f8f958b302c288d285332ea;hpb=a56dbb1cc827eb9e58050762493df3b5c0354065;p=p5sagit%2Fp5-mst-13.2.git diff --git a/README.os2 b/README.os2 index f5bf87d..409c774 100644 --- a/README.os2 +++ b/README.os2 @@ -4,7 +4,7 @@ specially designed to be readable as is. =head1 NAME -perlos2 - Perl under OS/2, Win0.31, Win0.95 and WinNT. +perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. =head1 SYNOPSIS @@ -18,28 +18,49 @@ One can read this document in the following formats: to list some (not all may be available simultaneously), or it may be read I: either as F, or F. +To read the F<.INF> version of documentation (B recommended) +outside of OS/2, one needs an IBM's reader (may be available on IBM +ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's +Visual Age C++ 3.5. + +A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package + + ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip + +in F. This gives one an access to EMX's +F<.INF> docs as well (text form is available in F in +EMX's distribution). + +Note that if you have F installed, you can follow WWW links +from this document in F<.INF> format. If you have EMX docs installed +correctly, you can follow library links (you need to have C +working by setting C environment variable as it is described +in EMX docs). + =cut Contents - perlos2 - Perl under OS/2 + perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. - NAME - SYNOPSIS - DESCRIPTION + NAME + SYNOPSIS + DESCRIPTION - Target - Other OSes - Prerequisites - - Starting Perl programs under OS/2 - - Starting OS/2 programs under Perl - Frequently asked questions - - I cannot run extenal programs - - I cannot embed perl into my program, or use perl.dll from my program. - INSTALLATION + - Starting Perl programs under OS/2 (and DOS and...) + - Starting OS/2 (and DOS) programs under Perl + Frequently asked questions + - I cannot run external programs + - I cannot embed perl into my program, or use perl.dll from my program. + - `` and pipe-open do not work under DOS. + - Cannot start find.exe "pattern" file + INSTALLATION - Automatic binary installation - Manual binary installation - Warning - Accessing documentation + Accessing documentation - OS/2 .INF file - Plain text - Manpages @@ -47,7 +68,7 @@ Contents - GNU info files - .PDF files - LaTeX docs - BUILD + BUILD - Prerequisites - Getting perl source - Application of the patches @@ -56,20 +77,22 @@ Contents - Testing - Installing the built perl - a.out-style build - Build FAQ + Build FAQ - Some / became \ in pdksh. - 'errno' - unresolved external - Problems with tr - Some problem (forget which ;-) - Library ... not found - - Segfault in make - Specific (mis)features of OS/2 port + - Segfault in make + Specific (mis)features of EMX port - setpriority, getpriority - system() + - extproc on the first line - Additional modules: - Prebuilt methods: - Misfeatures - Perl flavors + - Modifications + Perl flavors - perl.exe - perl_.exe - perl__.exe @@ -77,27 +100,30 @@ Contents - Why strange names? - Why dynamic linking? - Why chimera build? - ENVIRONMENT + ENVIRONMENT - PERLLIB_PREFIX - PERL_BADLANG - PERL_BADFREE - PERL_SH_DIR - TMP or TEMP - Evolution + Evolution - Priorities - - DLL name mungling + - DLL name mangling - Threading - Calls to external programs - AUTHOR - SEE ALSO - + - Memory allocation + - Threads + AUTHOR + SEE ALSO + =head1 DESCRIPTION =head2 Target The target is to make OS/2 the best supported platform for -using/building/developping Perl and I, as well as -make Perl the best language to use under OS/2. +using/building/developing Perl and I, as well as +make Perl the best language to use under OS/2. The secondary target is +to try to make this work under DOS and Win* as well (but not B hard). The current state is quite close to this target. Known limitations: @@ -115,10 +141,10 @@ to use PM code in your application (like the forthcoming Perl/Tk). =item * -There is no simple way to access B objects. The only way I know +There is no simple way to access WPS objects. The only way I know is via C extension (see L), and we do not have access to -convinience methods of B. (Is it possible at all? I know -of no B API.) +convenience methods of Object-REXX. (Is it possible at all? I know +of no Object-REXX API.) =back @@ -126,15 +152,15 @@ Please keep this list up-to-date by informing me about other items. =head2 Other OSes -Since OS/2 port of perl uses a remarkable B environment, it can +Since OS/2 port of perl uses a remarkable EMX environment, it can run (and build extensions, and - possibly - be build itself) under any environment which can run EMX. The current list is DOS, -DOS-inside-OS/2, Win0.31, Win0.95 and WinNT. Out of many perl flavors, +DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, only one works, see L<"perl_.exe">. Note that not all features of Perl are available under these environments. This depends on the features the I - most -probably C - decided to implement. +probably RSX - decided to implement. Cf. L. @@ -142,46 +168,83 @@ Cf. L. =over 6 -=item B +=item EMX -B runtime is required. Note that it is possible to make F -to run under DOS without any external support by binding F to -it, see L. +EMX runtime is required (may be substituted by RSX). Note that +it is possible to make F to run under DOS without any +external support by binding F/F to it, see L. Note +that under DOS for best results one should use RSX runtime, which +has much more functions working (like C, C and so on). In +fact RSX is required if there is no VCPI present. Note the +RSX requires DPMI. -Only the latest runtime is supported, currently C<0.9c>. +Only the latest runtime is supported, currently C<0.9c>. Perl may run +under earlier versions of EMX, but this is not tested. -One can get different parts of B from, say +One can get different parts of EMX from, say - ftp://ftp.cdrom.com/pub/os2/emx0.9c/ - ftp://hobbes.nmsu.edu/os2/unix/gnu/ + ftp://ftp.cdrom.com/pub/os2/emx09c/ + ftp://hobbes.nmsu.edu/os2/unix/emx09c/ The runtime component should have the name F. -=item B +B. It is enough to have F/F on your path. One +does not need to specify them explicitly (though this -To run Perl on C platforms one needs B runtime. This is -needed under DOS-inside-OS/2, Win0.31, Win0.95 and WinNT (see -L<"Other OSes">). + emx perl_.exe -de 0 -One can get B from, say +will work as well.) - ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib +=item RSX + +To run Perl on DPMI platforms one needs RSX runtime. This is +needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see +L<"Other OSes">). RSX would not work with VCPI +only, as EMX would, it requires DMPI. + +Having RSX and the latest F one gets a fully functional +B<*nix>-ish environment under DOS, say, C, C<``> and +pipe-C work. In fact, MakeMaker works (for static build), so one +can have Perl development environment under DOS. + +One can get RSX from, say + + ftp://ftp.cdrom.com/pub/os2/emx09c/contrib ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc + ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib Contact the author on C. -=item B +The latest F with DOS hooks is available at + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip + +=item HPFS Perl does not care about file systems, but to install the whole perl library intact one needs a file system which supports long file names. Note that if you do not plan to build the perl itself, it may be -possible to fool B to truncate file names. This is not supported, -read B docs to see how to do it. +possible to fool EMX to truncate file names. This is not supported, +read EMX docs to see how to do it. + +=item pdksh + +To start external programs with complicated command lines (like with +pipes in between, and/or quoting of arguments), Perl uses an external +shell. With EMX port such shell should be named , and located +either in the wired-in-during-compile locations (usually F), +or in configurable location (see L<"PERL_SH_DIR">). + +For best results use EMX pdksh. The soon-to-be-available standard +binary (5.2.12?) runs under DOS (with L) as well, meanwhile use +the binary from + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip =back -=head2 Starting Perl programs under OS/2 +=head2 Starting Perl programs under OS/2 (and DOS and...) Start your Perl program F with arguments C the same way as on any other platform, by @@ -193,33 +256,28 @@ opposed to to your program), use perl -my_opts foo.pl arg1 arg2 arg3 -Alternately, if you use OS/2-ish shell, like C or C<4os2>, put +Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the following at the start of your perl script: - extproc perl -x -S - #!/usr/bin/perl -my_opts + extproc perl -S -my_opts rename your program to F, and start it by typing foo arg1 arg2 arg3 -(Note that having *nixish full path to perl F is not -necessary, F would be enough, but having full path would make it -easier to use your script under *nix.) - Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use C, thus you are forced to use C<-S> perl switch, and your script should be on path. As a plus side, if you know a full path to your script, you may still start it with - perl -x ../../blah/foo.cmd arg1 arg2 arg3 + perl ../../blah/foo.cmd arg1 arg2 arg3 -(note that the argument C<-my_opts> is taken care of by the C<#!> line -in your script). +(note that the argument C<-my_opts> is taken care of by the C line +in your script, see L on the first line>). To understand what the above I does, read perl docs about C<-S> -and C<-x> switches - see L, and cmdref about C: +switch - see L, and cmdref about C: view perl perlrun man perlrun @@ -228,12 +286,15 @@ and C<-x> switches - see L, and cmdref about C: or whatever method you prefer. -There are also endless possibilites to use I of -B<4OS2>, I of B and so on... However, if you use +There are also endless possibilities to use I of +4os2, I of WPS and so on... However, if you use *nixish shell (like F supplied in the binary distribution), -you need follow the syntax specified in L. +you need to follow the syntax specified in L. + +Note that B<-S> switch enables a search with additional extensions +F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well. -=head2 Starting OS/2 programs under Perl +=head2 Starting OS/2 (and DOS) programs under Perl This is what system() (see L), C<``> (see L), and I (see L) @@ -241,50 +302,166 @@ are for. (Avoid exec() (see L) unless you know what you do). Note however that to use some of these operators you need to have a -C-syntax shell installed (see L<"Pdksh">, +sh-syntax shell installed (see L<"Pdksh">, L<"Frequently asked questions">), and perl should be able to find it (see L<"PERL_SH_DIR">). -The only cases when the shell is not used is the multi-argument -system() (see L)/exec() (see L), and -one-argument version thereof without redirection and shell -meta-characters. +The cases when the shell is used are: + +=over + +=item 1 + +One-argument system() (see L), exec() (see L) +with redirection or shell meta-characters; + +=item 2 + +Pipe-open (see L) with the command which contains redirection +or shell meta-characters; + +=item 3 + +Backticks C<``> (see L) with the command which contains +redirection or shell meta-characters; + +=item 4 + +If the executable called by system()/exec()/pipe-open()/C<``> is a script +with the "magic" C<#!> line or C line which specifies shell; + +=item 5 + +If the executable called by system()/exec()/pipe-open()/C<``> is a script +without "magic" line, and C<$ENV{EXECSHELL}> is set to shell; + +=item 6 + +If the executable called by system()/exec()/pipe-open()/C<``> is not +found; + +=item 7 + +For globbing (see L, L). + +=back + +For the sake of speed for a common case, in the above algorithms +backslashes in the command name are not considered as shell metacharacters. + +Perl starts scripts which begin with cookies +C or C<#!> directly, without an intervention of shell. Perl uses the +same algorithm to find the executable as F: if the path +on C<#!> line does not work, and contains C, then the executable +is searched in F<.> and on C. To find arguments for these scripts +Perl uses a different algorithm than F: up to 3 arguments are +recognized, and trailing whitespace is stripped. + +If a script +does not contain such a cooky, then to avoid calling F, Perl uses +the same algorithm as F: if C<$ENV{EXECSHELL}> is set, the +script is given as the first argument to this command, if not set, then +C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is +not set). + +If starting scripts directly, Perl will use exactly the same algorithm as for +the search of script given by B<-S> command-line option: it will look in +the current directory, then on components of C<$ENV{PATH}> using the +following order of appended extensions: no extension, F<.cmd>, F<.btm>, +F<.bat>, F<.pl>. + +Note that Perl will start to look for scripts only if OS/2 cannot start the +specified application, thus C will not look for a script if +there is an executable file F I on C. + +Note also that executable files on OS/2 can have an arbitrary extension, +but F<.exe> will be automatically appended if no dot is present in the name. +The workaround as as simple as that: since F and F denote the +same file, to start an executable residing in file F (no +extension) give an argument C to system(). + +The last note is that currently it is not straightforward to start PM +programs from VIO (=text-mode) Perl process and visa versa. Either ensure +that shell will be used, as in C, or start it using +optional arguments to system() documented in C module. This +is considered a bug and should be fixed soon. + =head1 Frequently asked questions -=head2 I cannot run extenal programs +=head2 I cannot run external programs + +=over 4 + +=item Did you run your programs with C<-w> switch? See -L. +L. + +=item + +Do you try to run I shell commands, like C<`copy a b`> +(internal for F), or C<`glob a*b`> (internal for ksh)? You +need to specify your shell explicitly, like C<`cmd /c copy a b`>, +since Perl cannot deduce which commands are internal to your shell. + +=back =head2 I cannot embed perl into my program, or use F from my program. =over 4 -=item Is your program B-compiled with C<-Zmt -Zcrtdll>? +=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>? If not, you need to build a stand-alone DLL for perl. Contact me, I did it once. Sockets would not work, as a lot of other stuff. -=item Did you use C? +=item Did you use L? I had reports it does not work. Somebody would need to fix it. =back +=head2 C<``> and pipe-C do not work under DOS. + +This may a variant of just L<"I cannot run external programs">, or a +deeper problem. Basically: you I RSX (see L<"Prerequisites">) +for these commands to work, and you may need a port of F which +understands command arguments. One of such ports is listed in +L<"Prerequisites"> under RSX. Do not forget to set variable +C> as well. + +DPMI is required for RSX. + +=head2 Cannot start C + +Use one of + + system 'cmd', '/c', 'find "pattern" file'; + `cmd /c 'find "pattern" file'` + +This would start F via F via C via +C, but this is a price to pay if you want to use +non-conforming program. In fact F cannot be started at all +using C library API only. Otherwise the following command-lines were +equivalent: + + find "pattern" file + find pattern file + =head1 INSTALLATION =head2 Automatic binary installation -The most convinient way of installing perl is via perl installer +The most convenient way of installing perl is via perl installer F. Just follow the instructions, and 99% of the installation blues would go away. Note however, that you need to have F on your path, and -B environment I. The latter means that if you just -installed B, and made all the needed changes to F, -you may need to reboot in between. Check B runtime by running +EMX environment I. The latter means that if you just +installed EMX, and made all the needed changes to F, +you may need to reboot in between. Check EMX runtime by running emxrev @@ -298,7 +475,7 @@ B =item C may be needed if you change your codepage I perl installation, -and the new value is not supported by B. See L<"PERL_BADLANG">. +and the new value is not supported by EMX. See L<"PERL_BADLANG">. =item C @@ -317,18 +494,24 @@ data, please keep me informed if you find one. =back +B. Because of a typo the binary installer of 5.00305 +would install a variable C into F. Please +remove this variable and put C> instead. + =head2 Manual binary installation -As of version 5.00305, OS/2 perl binary distribution comes splitted +As of version 5.00305, OS/2 perl binary distribution comes split into 11 components. Unfortunately, to enable configurable binary -installation, the file paths in the C files are not absolute, but +installation, the file paths in the zip files are not absolute, but relative to some directory. Note that the extraction with the stored paths is still necessary -(default with C, specify C<-d> to C). However, you +(default with unzip, specify C<-d> to pkunzip). However, you need to know where to extract the files. You need also to manually change entries in F to reflect where did you put the -files. +files. Note that if you have some primitive unzipper (like +pkunzip), you may get a lot of warnings/errors during +unzipping. Upgrade to C<(w)unzip>. Below is the sample of what to do to reproduce the configuration on my machine: @@ -340,20 +523,20 @@ machine: unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin unzip perl_exc.zip *.dll -d f:/emx.add/dll -(have the directories with C<*.exe> on C, and C<*.dll> on -C); +(have the directories with C<*.exe> on PATH, and C<*.dll> on +LIBPATH); =item Perl_ VIO executable (statically linked) unzip perl_aou.zip -d f:/emx.add/bin -(have the directory on C); +(have the directory on PATH); =item Executables for Perl utilities unzip perl_utl.zip -d f:/emx.add/bin -(have the directory on C); +(have the directory on PATH); =item Main Perl library @@ -385,25 +568,25 @@ C in F, see L<"PERLLIB_PREFIX">. unzip perl_man.zip -d f:/perllib/man This directory should better be on C. You need to have a -working C to access these files. +working man to access these files. =item Manpages for Perl modules unzip perl_mam.zip -d f:/perllib/man This directory should better be on C. You need to have a -working C to access these files. +working man to access these files. =item Source for Perl documentation unzip perl_pod.zip -d f:/perllib/lib This is used by by C program (see L), and may be used to -generate B documentation usable by WWW browsers, and +generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: C, C, C, C and so on. -=item Perl manual in .INF format +=item Perl manual in F<.INF> format unzip perl_inf.zip -d d:/os2/book @@ -413,14 +596,14 @@ This directory should better be on C. unzip perl_sh.zip -d f:/bin -This is used by perl to run external commands which explicitely +This is used by perl to run external commands which explicitly require shell, like the commands using I and I. It is also used instead of explicit F. Set C (see L<"PERL_SH_DIR">) if you move F from the above location. -B It may be possible to use some other C-compatible shell +B It may be possible to use some other sh-compatible shell (I). =back @@ -449,7 +632,7 @@ identical) Perl documentation in the following formats: =head2 OS/2 F<.INF> file -Most probably the most convinient form. View it as +Most probably the most convenient form. Under OS/2 view it as view perl view perl perlfunc @@ -457,7 +640,7 @@ Most probably the most convinient form. View it as view perl ExtUtils::MakeMaker (currently the last two may hit a wrong location, but this may improve -soon). +soon). Under Win* see L<"SYNOPSIS">. If you want to build the docs yourself, and have I, run @@ -473,20 +656,20 @@ BOOKSHELF path. =head2 Plain text If you have perl documentation in the source form, perl utilities -installed, and B C installed, you may use +installed, and GNU groff installed, you may use perldoc perlfunc perldoc less perldoc ExtUtils::MakeMaker -to access the perl documention in the text form (note that you may get +to access the perl documentation in the text form (note that you may get better results using perl manpages). Alternately, try running pod2text on F<.pod> files. =head2 Manpages -If you have C installed on your system, and you installed perl +If you have man installed on your system, and you installed perl manpages, use something like this: man perlfunc @@ -506,11 +689,11 @@ on our C, like this set MANPATH=c:/man;f:/perllib/man -=head2 B +=head2 HTML If you have some WWW browser available, installed the Perl documentation in the source form, and Perl utilities, you can build -B docs. Cd to directory with F<.pod> files, and do like this +HTML docs. Cd to directory with F<.pod> files, and do like this cd f:/perllib/lib/pod pod2html @@ -520,11 +703,11 @@ directory, and go ahead with reading docs, like this: explore file:///f:/perllib/lib/pod/perl.html -Alternatively you may be able to get these docs prebuild from C. +Alternatively you may be able to get these docs prebuilt from CPAN. -=head2 B C files +=head2 GNU C files -Users of C would appreciate it very much, especially with +Users of Emacs would appreciate it very much, especially with C mode loaded. You need to get latest C from C, or, alternately, prebuilt info pages. @@ -544,8 +727,8 @@ Here we discuss how to build Perl under OS/2. There is an alternative =head2 Prerequisites -You need to have the latest B development environment, the full -B tool suite (C renamed to C, and B F +You need to have the latest EMX development environment, the full +GNU tool suite (gawk renamed to awk, and GNU F earlier on path than the OS/2 F, same with F, to check use @@ -554,13 +737,22 @@ check use ). You need the latest version of F installed as F. +Check that you have B libraries and headers installed, and - +optionally - Berkeley DB headers and libraries, and crypt. + Possible locations to get this from are - ftp://hobbes.nmsu.edu/os2/unix/gnu/ + ftp://hobbes.nmsu.edu/os2/unix/ ftp://ftp.cdrom.com/pub/os2/unix/ ftp://ftp.cdrom.com/pub/os2/dev32/ - ftp://ftp.cdrom.com/pub/os2/emx0.9c/ + ftp://ftp.cdrom.com/pub/os2/emx09c/ + +It is reported that the following archives contain enough utils to +build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip, +gnupatch.zip, gnuawk.zip, gnumake.zip and ksh527rt.zip. Note that +all these utilities are known to be available from LEO: + ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu Make sure that no copies or perl are currently running. Later steps of the build may fail since an older version of perl.dll loaded into @@ -574,21 +766,21 @@ latter condition by if you use something like F or latest versions of F<4os2.exe>. -Make sure your C is good for C<-Zomf> linking: run C +Make sure your gcc is good for C<-Zomf> linking: run C script in F directory. -Check that you have C installed. It comes standard with OS/2, +Check that you have link386 installed. It comes standard with OS/2, but may be not installed due to customization. If typing link386 shows you do not have it, do I, and choose C in I. If you get into -C, press C. +object modules> in I. If you get into +link386, press C. =head2 Getting perl source -You need to fetch the latest perl source (including developpers +You need to fetch the latest perl source (including developers releases). With some probability it is located in http://www.perl.com/CPAN/src/5.0 @@ -597,7 +789,7 @@ releases). With some probability it is located in If not, you may need to dig in the indices to find it in the directory of the current maintainer. -Quick cycle of developpers release may break the OS/2 build time to +Quick cycle of developers release may break the OS/2 build time to time, looking into http://www.perl.com/CPAN/ports/os2/ilyaz/ @@ -613,10 +805,6 @@ Extract it like this You may see a message about errors while extracting F. This is because there is a conflict with a similarly-named file F. -Rename F to F. Extract F like this - - tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure - Change to the directory of extraction. =head2 Application of the patches @@ -625,18 +813,34 @@ You need to apply the patches in F<./os2/diff.*> and F<./os2/POSIX.mkfifo> like this: gnupatch -p0 < os2\POSIX.mkfifo - gnupatch -p0 < os2\os2\diff.configure + gnupatch -p0 < os2\diff.configure You may also need to apply the patches supplied with the binary distribution of perl. -Note also that the F and F from the B distribution +Note also that the F and F from the EMX distribution are not suitable for multi-threaded compile (note that currently perl -is not multithreaded, but is compiled as multithreaded for -compatibility with B-OS/2). Get a corrected one from +is not multithread-safe, but is compiled as multithreaded for +compatibility with XFree86-OS/2). Get a corrected one from ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip +To make C<-p> filetest work, one may also need to apply the following patch +to EMX headers: + + --- /emx/include/sys/stat.h.orig Thu May 23 13:48:16 1996 + +++ /emx/include/sys/stat.h Sun Jul 12 14:11:32 1998 + @@ -53,7 +53,7 @@ struct stat + #endif + + #if !defined (S_IFMT) + -#define S_IFMT 0160000 /* Mask for file type */ + +#define S_IFMT 0170000 /* Mask for file type */ + #define S_IFIFO 0010000 /* Pipe */ + #define S_IFCHR 0020000 /* Character device */ + #define S_IFDIR 0040000 /* Directory */ + + =head2 Hand-editing You may look into the file F<./hints/os2.sh> and correct anything @@ -646,12 +850,12 @@ wrong you find there. I do not expect it is needed anywhere. sh Configure -des -D prefix=f:/perllib -Prefix means where to install the resulting perl library. Giving +C means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify C, see L<"PERLLIB_PREFIX">. I, and about C<-c> option to -C>. In fact if you can trace where the latter spurious warning +tr>. In fact if you can trace where the latter spurious warning comes from, please inform me. Now @@ -661,56 +865,84 @@ Now At some moment the built may die, reporting a I or I>. This means that most of the build has been finished, and it is the time to move the constructed F to -some I location in C. After this done the build -should finish without a lot of fuss. I on C.> +some I location in LIBPATH. After this is done the build +should finish without a lot of fuss. I on LIBPATH, but +probably this is not needed anymore, since F is linked +statically now.> Warnings which are safe to ignore: I inside F. =head2 Testing +If you haven't yet moved perl.dll onto LIBPATH, do it now (alternatively, if +you have a previous perl installation you'd rather not disrupt until this one +is installed, copy perl.dll to the t directory). + Now run make test -Some tests (4..6) should fail. Some perl invocations should end in a -segfault (system error C). To get finer error reports, +All tests should succeed (with some of them skipped). Note that on one +of the systems I see intermittent failures of F subtest 9. +Any help to track what happens with this test is appreciated. - cd t - perl -I ../lib harness +Some tests may generate extra messages similar to -The report you get may look like +=over 4 - Failed Test Status Wstat Total Fail Failed List of failed - --------------------------------------------------------------- - io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25 - lib/io_pipe.t 3 768 6 ?? % ?? - lib/io_sock.t 3 768 5 ?? % ?? - op/stat.t 56 5 8.93% 3-4, 20, 35, 39 - Failed 4/118 test scripts, 96.61% okay. 27/2445 subtests failed, 98.90% okay. +=item A lot of C -Note that using `make test' target two more tests may fail: C -because of (mis)feature of C, and C, which checks -that the buffers are not flushed on C<_exit>. +in database tests related to Berkeley DB. This is a confirmed bug of +DB. You may disable this warnings, see L<"PERL_BADFREE">. -The reasons for failed tests are: +There is not much we can do with it (but apparently it does not cause +any real error with data). -=over 8 +=item Process terminated by SIGTERM/SIGINT + +This is a standard message issued by OS/2 applications. *nix +applications die in silence. It is considered a feature. One can +easily disable this by appropriate sighandlers. + +However the test engine bleeds these message to screen in unexpected +moments. Two messages of this kind I be present during +testing. -=item F +=back -Checks I operations. Tests: +Two F tests may generate popups (system error C), +but should succeed anyway. This is due to a bug of EMX related to +fork()ing with dynamically loaded libraries. -=over 10 +I submitted a patch to EMX which makes it possible to fork() with EMX +dynamic libraries loaded, which makes F tests pass without +skipping offended tests. This means that soon the number of skipped tests +may decrease yet more. -=item 2-5, 7-11 +To get finer test reports, call -Check C and C - nonesuch under OS/2. + perl t/harness + +The report with F failing may look like this: + + Failed Test Status Wstat Total Fail Failed List of failed + ------------------------------------------------------------ + io/pipe.t 12 1 8.33% 9 + 7 tests skipped, plus 56 subtests skipped. + Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay. + +The reasons for most important skipped tests are: + +=over 8 + +=item F =item 18 -Checks C and C of C - I could not understand this test. +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). =item 25 @@ -721,12 +953,12 @@ know why this should or should not work. =item F -Checks C module. Some feature of B - test fork()s with +Checks C module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F -Checks C module. Some feature of B - test fork()s +Checks C module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F @@ -735,78 +967,38 @@ Checks C. Tests: =over 4 -=item 3 - -Checks C - nonesuch under OS/2. - =item 4 -Checks C and C of C - I could not understand this test. - -=item 20 - -Checks C<-x> - determined by the file extension only under OS/2. - -=item 35 - -Needs F. - -=item 39 - -Checks C<-t> of F. Should not fail! - -=back +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). =back -In addition to errors, you should get a lot of warnings. - -=over 4 - -=item A lot of `bad free' - -in databases related to Berkeley DB. This is a confirmed bug of -DB. You may disable this warnings, see L<"PERL_BADFREE">. - -=item Process terminated by SIGTERM/SIGINT - -This is a standard message issued by OS/2 applications. *nix -applications die in silence. It is considered a feature. One can -easily disable this by appropriate sighandlers. - -However the test engine bleeds these message to screen in unexpected -moments. Two messages of this kind I be present during -testing. - -=item F<*/sh.exe>: ln: not found - -=item C: /dev: No such file or directory +=item F -The last two should be self-explanatory. The test suite discovers that -the system it runs on is not I *nixish. +It never terminates, apparently some bug in storing the last socket from +which we obtained a message. =back -A lot of `bad free'... in databases, bug in DB confirmed on other -platforms. You may disable it by setting PERL_BADFREE environment variable -to 1. - =head2 Installing the built perl +If you haven't yet moved perl.dll onto LIBPATH, do it now. + Run make install It would put the generated files into needed locations. Manually put F, F and F to a location on your -C, F to a location on your C. +PATH, F to a location on your LIBPATH. Run make cmdscripts INSTALLCMDDIR=d:/ir/on/path to convert perl utilities to F<.cmd> files and put them on -C. You need to put F<.EXE>-utilities on path manually. They are +PATH. You need to put F<.EXE>-utilities on path manually. They are installed in C<$prefix/bin>, here C<$prefix> is what you gave to F, see L. @@ -821,10 +1013,10 @@ test and install by make aout_test make aout_install -Manually put F to a location on your C. +Manually put F to a location on your PATH. Since C has the extensions prebuilt, it does not suffer from -the I syndrom, thus the failing tests +the I syndrome, thus the failing tests look like Failed Test Status Wstat Total Fail Failed List of failed @@ -851,13 +1043,13 @@ You have a very old pdksh. See L. You do not have MT-safe F. See L. -=head2 Problems with C +=head2 Problems with tr or sed -reported with very old version of C. +reported with very old version of tr and sed. =head2 Some problem (forget which ;-) -You have an older version of F on your C, which +You have an older version of F on your LIBPATH, which broke the build of extensions. =head2 Library ... not found @@ -866,7 +1058,7 @@ You did not run C. See L. =head2 Segfault in make -You use an old version of C make. See L. +You use an old version of GNU make. See L. =head1 Specific (mis)features of OS/2 port @@ -874,7 +1066,7 @@ You use an old version of C make. See L. Note that these functions are compatible with *nix, not with the older ports of '94 - 95. The priorities are absolute, go from 32 to -95, -lower is quickier. 0 is the default priority. +lower is quicker. 0 is the default priority. =head2 C @@ -882,14 +1074,21 @@ Multi-argument form of C allows an additional numeric argument. The meaning of this argument is described in L. +=head2 C on the first line + +If the first chars of a script are C<"extproc ">, this line is treated +as C<#!>-line, thus all the switches on this line are processed (twice +if script was started via cmd.exe). + =head2 Additional modules: -L, L, L, L. This -modules provide access to additional numeric argument for C, +L, L, L, L. These +modules provide access to additional numeric argument for C +and to the list of the running processes, to DLLs having functions with REXX signature and to REXX runtime, to OS/2 databases in the F<.INI> format, and to Extended Attributes. -Two additional extensions by Andread Kaiser, C, and +Two additional extensions by Andreas Kaiser, C, and C, are included into my ftp directory, mirrored on CPAN. =head2 Prebuilt methods: @@ -898,11 +1097,11 @@ C, are included into my ftp directory, mirrored on CPAN. =item C -used by C, see L. +used by C, see L. =item C -used by C for DLL name mungling. +used by C for DLL name mangling. =item C @@ -929,7 +1128,7 @@ means changes with current dir. =item C -Interface to cwd from B. Used by C. +Interface to cwd from EMX. Used by C. =item C @@ -961,23 +1160,96 @@ eventually). =item -Since is present in B, but is not functional, the same is -true for perl. +Since L is present in EMX, but is not functional, it is +emulated by perl. To disable the emulations, set environment variable +C. =item -Since F is used for globbing (see L), the bugs +Here is the list of things which may be "broken" on +EMX (from EMX docs): + +=over + +=item * + +The functions L, L, and L are not +implemented. + +=item * + +L is not required and not implemented. + +=item * + +L is not yet implemented (dummy function). (Perl has a workaround.) + +=item * + +L: Special treatment of PID=0, PID=1 and PID=-1 is not implemented. + +=item * + +L: + + WUNTRACED + Not implemented. + waitpid() is not implemented for negative values of PID. + +=back + +Note that C does not work with the current version of EMX. + +=item + +Since F is used for globing (see L), the bugs of F plague perl as well. In particular, uppercase letters do not work in C<[...]>-patterns with -the current C. +the current pdksh. + +=back + +=head2 Modifications + +Perl modifies some standard C library calls in the following ways: + +=over 9 + +=item C + +C uses F if shell is required, cf. L<"PERL_SH_DIR">. + +=item C + +is created using C or C environment variable, via +C. + +=item C + +If the current directory is not writable, file is created using modified +C, so there may be a race condition. + +=item C + +a dummy implementation. + +=item C + +C special-cases F and F. + +=item C + +Since L is present in EMX, but is not functional, it is +emulated by perl. To disable the emulations, set environment variable +C. =back =head1 Perl flavors -Because of ideosyncrasies of OS/2 one cannot have all the eggs in the -same basket (though C environment tries hard to overcome this +Because of idiosyncrasies of OS/2 one cannot have all the eggs in the +same basket (though EMX environment tries hard to overcome this limitations, so the situation may somehow improve). There are 4 executables for Perl provided by the distribution: @@ -985,11 +1257,12 @@ executables for Perl provided by the distribution: The main workhorse. This is a chimera executable: it is compiled as an C-style executable, but is linked with C-style dynamic -library F, and with dynamic B DLL. This executable is a -C application. +library F, and with dynamic CRT DLL. This executable is a +VIO application. It can load perl dynamic extensions, and it can fork(). Unfortunately, -currently it cannot fork() with dynamic extensions loaded. +with the current version of EMX it cannot fork() with dynamic +extensions loaded (may be fixed by patches to EMX). B Keep in mind that fork() is needed to open a pipe to yourself. @@ -999,44 +1272,44 @@ This is a statically linked C-style executable. It can fork(), but cannot load dynamic Perl extensions. The supplied executable has a lot of extensions prebuilt, thus there are situations when it can perform tasks not possible using F, like fork()ing when -having some standard extension loaded. This executable is a C +having some standard extension loaded. This executable is a VIO application. B A better behaviour could be obtained from C if it were statically linked with standard I, but -dynamically linked with the I and C DLL. Then it would +dynamically linked with the I and CRT DLL. Then it would be able to fork() with standard extensions, I would be able to dynamically load arbitrary extensions. Some changes to Makefiles and hint files should be necessary to achieve this. I The friends locked into C world would appreciate the fact that this -executable runs under DOS, Win0.31, Win0.95 and WinNT with an +executable runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate extender. See L<"Other OSes">. =head2 F -This is the same executable as , but it is a C +This is the same executable as F, but it is a PM application. -B Usually C, C, and C of a C +B Usually STDIN, STDERR, and STDOUT of a PM application are redirected to C. However, it is possible to see them if you start C from a PM program which emulates a -console window, like I of C or C. Thus it I of Emacs or EPM. Thus it I to use Perl debugger (see L) to debug your PM application. -This flavor is required if you load extensions which use C, like +This flavor is required if you load extensions which use PM, like the forthcoming C. =head2 F This is an C-style executable which is dynamically linked to -F and C DLL. I know no advantages of this executable +F and CRT DLL. I know no advantages of this executable over C, but it cannot fork() at all. Well, one advantage is that the build process is not so convoluted as with C. -It is a C application. +It is a VIO application. =head2 Why strange names? @@ -1046,7 +1319,7 @@ L, L), it should know when a program I. There is some naming convention which allows Perl to distinguish correct lines from wrong ones. The above names are -almost the only names allowed by this convension which do not contain +almost the only names allowed by this convention which do not contain digits (which have absolutely different semantics). =head2 Why dynamic linking? @@ -1056,14 +1329,14 @@ library has its advantages, but this would not substantiate the additional work to make it compile. The reason is stupid-but-quick "hard" dynamic linking used by OS/2. -The address tables of DLLs are patches only once, when they are -loaded. The addresses of entry points into DLLs are guarantied to be +The address tables of DLLs are patched only once, when they are +loaded. The addresses of entry points into DLLs are guaranteed to be the same for all programs which use the same DLL, which reduces the amount of runtime patching - once DLL is loaded, its code is read-only. While this allows some performance advantages, this makes life -terrible for developpers, since the above scheme makes it impossible +terrible for developers, since the above scheme makes it impossible for a DLL to be resolved to a symbol in the .EXE file, since this would need a DLL to have different relocations tables for the executables which use it. @@ -1074,18 +1347,18 @@ internal evaluation stack. The solution is that the main code of interpreter should be contained in a DLL, and the F<.EXE> file just loads this DLL into memory and supplies command-arguments. -This I increases the load time for the application (as well as +This I increases the load time for the application (as well as the number of problems during compilation). Since interpreter is in a DLL, -the C is basically forced to reside in a DLL as well (otherwise -extensions would not be able to use C). +the CRT is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). =head2 Why chimera build? -Current C environment does not allow DLLs compiled using Unixish +Current EMX environment does not allow DLLs compiled using Unixish C format to export symbols for data. This forces C-style compile of F. -Current C environment does not allow F<.EXE> files compiled in +Current EMX environment does not allow F<.EXE> files compiled in C format to fork(). fork() is needed for exactly three Perl operations: @@ -1110,12 +1383,12 @@ F. =head1 ENVIRONMENT -Here we list environment variables with are either OS/2-specific, or -are more important under OS/2 than under other OSes. +Here we list environment variables with are either OS/2- and DOS- and +Win*-specific, or are more important under OS/2 than under other OSes. =head2 C -Specific for OS/2. Should have the form +Specific for EMX port. Should have the form path1;path2 @@ -1128,7 +1401,11 @@ substituted with F. Should be used if the perl library is moved from the default location in preference to C, since this would not leave wrong -entries in <@INC>. +entries in @INC. Say, if the compiled version of perl looks for @INC +in F, and you want to install the library in +F, do + + set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu =head2 C @@ -1143,12 +1420,18 @@ memory handling code is buggy. =head2 C -Specific for OS/2. Gives the directory part of the location for +Specific for EMX port. Gives the directory part of the location for F. +=head2 C + +Specific for EMX port. Since L is present in EMX, but is not +functional, it is emulated by perl. To disable the emulations, set +environment variable C. + =head2 C or C -Specific for OS/2. Used as storage place for temporary files, most +Specific for EMX port. Used as storage place for temporary files, most notably C<-e> scripts. =head1 Evolution @@ -1160,7 +1443,7 @@ Here we list major changes which could make you by surprise. C and C are not compatible with earlier ports by Andreas Kaiser. See C<"setpriority, getpriority">. -=head2 DLL name mungling +=head2 DLL name mangling With the release 5.003_01 the dynamically loadable libraries should be rebuilt. In particular, DLLs are now created with the names @@ -1169,22 +1452,22 @@ caching DLLs. =head2 Threading -As of release 5.003_01 perl is linked to multithreaded C -DLL. Perl itself is not multithread-safe, as is not perl +As of release 5.003_01 perl is linked to multithreaded CRT +DLL. If perl itself is not compiled multithread-enabled, so will not be perl malloc(). However, extensions may use multiple thread on their own risk. -Needed to compile C for C out-of-the-box. +Needed to compile C for XFree86-OS/2 out-of-the-box. =head2 Calls to external programs Due to a popular demand the perl external program calling has been -changed wrt Andread Kaiser's port. I perl needs to call an +changed wrt Andreas Kaiser's port. I perl needs to call an external program I, the F will be called, or whatever is the override, see L<"PERL_SH_DIR">. Thus means that you need to get some copy of a F as well (I -use one from pdksh). The drive F: above is set up automatically during +use one from pdksh). The drive F above is set up automatically during the build to a correct value on the builder machine, but is overridable at runtime, @@ -1192,21 +1475,26 @@ B a consensus on C was that perl should use one non-overridable shell per platform. The obvious choices for OS/2 are F and F. Having perl build itself would be impossible with F as a shell, thus I picked up C. Thus assures almost -100% compatibility with the scripts coming from *nix. +100% compatibility with the scripts coming from *nix. As an added benefit +this works as well under DOS if you use DOS-enabled port of pdksh +(see L<"Prerequisites">). -B currently F of C calls external programs +B currently F of pdksh calls external programs via fork()/exec(), and there is I functioning exec() on OS/2. exec() is emulated by EMX by asyncroneous call while the caller -waits for child completion (to pretend that the pid did not change). This +waits for child completion (to pretend that the C did not change). This means that 1 I copy of F is made active via fork()/exec(), which may lead to some resources taken from the system (even if we do not count extra work needed for fork()ing). -One can always start F explicitely via +Note that this a lesser issue now when we do not spawn F +unless needed (metachars found). + +One can always start F explicitly via system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ... -If you need to use F, and do not want to hand-edit thousends of your +If you need to use F, and do not want to hand-edit thousands of your scripts, the long-term solution proposed on p5-p is to have a directive use OS2::Cmd; @@ -1221,11 +1509,63 @@ If you have some working code for C, please send it to me, I will include it into distribution. I have no need for such a module, so cannot test it. +For the details of the current situation with calling external programs, +see L. + +=over + +=item + +External scripts may be called by name. Perl will try the same extensions +as when processing B<-S> command-line switch. + +=back + +=head2 Memory allocation + +Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound +for speed, but perl is not, since its malloc is lightning-fast. +Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quickier +than EMX one. I do not have convincing data about memory footpring, but +a (pretty random) benchmark showed that Perl one is 5% better. + +Combination of perl's malloc() and rigid DLL name resolution creates +a special problem with library functions which expect their return value to +be free()d by system's free(). To facilitate extensions which need to call +such functions, system memory-allocation functions are still available with +the prefix C added. (Currently only DLL perl has this, it should +propagate to F shortly.) + +=head2 Threads + +One can build perl with thread support enabled by providing C<-D usethreads> +option to F. Currently OS/2 support of threads is very +preliminary. + +Most notable problems: + +=over + +=item C + +may have a race condition. Needs a reimplementation (in terms of chaining +waiting threads, with linker list stored in per-thread structure?). + +=item F + +has a couple of static variables used in OS/2-specific functions. (Need to be +moved to per-thread structure, or serialized?) + +=back + +Note that these problems should not discourage experimenting, since they +have a low probability of affecting small programs. + =cut OS/2 extensions ~~~~~~~~~~~~~~~ -I include 3 extensions by Andread Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, +I include 3 extensions by Andreas 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. Other extensions @@ -1233,7 +1573,8 @@ there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI files - and maybe some other extensions at the time you read it. Note that OS2 perl defines 2 pseudo-extension functions -OS2::Copy::copy and DynaLoader::mod2fname. +OS2::Copy::copy and DynaLoader::mod2fname (many more now, see +L). 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