X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.os2;h=fbc2731a48befde02fd25d90322fc575d3e5f9f1;hb=8dbfbba0c55b52c9acc258d9a3522ce8b76c3497;hp=3af22d14dabf2a7028a938ed0b3ff9df39bdfe71;hpb=bb14ff96c54db23fbbf7447aceb0dda1ce2c24f9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/README.os2 b/README.os2 index 3af22d1..fbc2731 100644 --- a/README.os2 +++ b/README.os2 @@ -1,832 +1,1942 @@ -Contents: - Notes on the patch - IMPORTANT NOTE - Target - Binary Install - Reading the docs - Quieting warnings - Notes on build on OS/2 - Compile summary - Tests which fail - Calls to external programs - OS/2 extensions - Report from the battlefield on 5.002_01 - -Notes on the patch: -~~~~~~~~~~~~~~~~~~~ -patches in ./os2 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. - - <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< -IMPORTANT NOTE <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< - <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< - -Note with the release 5.003_01 the dynamically loadable libraries -should be rebuilt. In particular, DLLs are now created with the names -which contain a checksum, thus allowing workaround for OS/2 scheme of -caching DLLs. +If you read this file _as_is_, just ignore the funny characters you +see. It is written in the POD format (see perlpod manpage) which is +specially designed to be readable as is. + +=head1 NAME + +perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. + +=head1 SYNOPSIS + +One can read this document in the following formats: + + man perlos2 + view perl perlos2 + explorer perlos2.html + info perlos2 + +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, DOS, Win0.3*, Win0.95 and WinNT. + + NAME + SYNOPSIS + DESCRIPTION + - Target + - Other OSes + - Prerequisites + - 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 + - OS/2 .INF file + - Plain text + - Manpages + - HTML + - GNU info files + - .PDF files + - LaTeX docs + BUILD + - Prerequisites + - Getting perl source + - Application of the patches + - Hand-editing + - Making + - Testing + - Installing the built perl + - a.out-style build + 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 EMX port + - setpriority, getpriority + - system() + - extproc on the first line + - Additional modules: + - Prebuilt methods: + - Misfeatures + - Modifications + Perl flavors + - perl.exe + - perl_.exe + - perl__.exe + - perl___.exe + - Why strange names? + - Why dynamic linking? + - Why chimera build? + ENVIRONMENT + - PERLLIB_PREFIX + - PERL_BADLANG + - PERL_BADFREE + - PERL_SH_DIR + - TMP or TEMP + Evolution + - Priorities + - DLL name mangling + - Threading + - Calls to external programs + - Memory allocation + - Threads + AUTHOR + SEE ALSO + +=head1 DESCRIPTION + +=head2 Target + +The target is to make OS/2 the best supported platform for +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: + +=over 5 + +=item * + +Some *nix programs use fork() a lot; with the mostly useful flavors of perl +for OS/2 (there are several built simultaneously) this is supported; +some flavors do not. Using fork() after Iing dynamically loading +extensions would not work with very old versions of EMX. + +=item * + +You need a separate perl executable F (see L) +if you want to use PM code in your application (as Perl/Tk or OpenGL +Perl modules do) without having a text-mode window present. + +While using the standard F from a text-mode window is possible +too, I have seen cases when this causes degradation of the system stability. +Using F avoids such a degradation. + +=item * + +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 +convenience methods of Object-REXX. (Is it possible at all? I know +of no Object-REXX API.) The C extension (currently in alpha-text) +may eventually remove this shortcoming. + +=back + +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 EMX environment, it can +run (and build extensions, and - possibly - be built itself) under any +environment which can run EMX. The current list is DOS, +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 RSX - decided to implement. + +Cf. L. + +=head2 Prerequisites + +=over 6 + +=item EMX + +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.9d fix 03>. Perl may run +under earlier versions of EMX, but this is not tested. + +One can get different parts of EMX from, say + + http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/ + http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development] + http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/ + +The runtime component should have the name F. + +B. It is enough to have F/F on your path. One +does not need to specify them explicitly (though this + + emx perl_.exe -de 0 + +will work as well.) + +=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. + +The latest F with DOS hooks is available in + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/ + +as F or under similar names starting with C, C etc. + +=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 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 F, 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 standard binary (5.2.14 or later) runs +under DOS (with L) as well, see + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/ + +=back + +=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 + + perl foo.pl arg1 arg2 arg3 + +If you want to specify perl options C<-my_opts> to the perl itself (as +opposed to to your program), use + + perl -my_opts foo.pl arg1 arg2 arg3 + +Alternately, if you use OS/2-ish shell, like CMD or 4os2, put +the following at the start of your perl script: + + extproc perl -S -my_opts + +rename your program to F, and start it by typing + + foo arg1 arg2 arg3 + +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 the C. As a plus +side, if you know a full path to your script, you may still start it +with + + 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, see L on the first line>). + +To understand what the above I does, read perl docs about C<-S> +switch - see L, and cmdref about C: + + view perl perlrun + man perlrun + view cmdref extproc + help extproc + +or whatever method you prefer. + +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 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 (and DOS) programs under Perl + +This is what system() (see L), C<``> (see +L), and I (see L) +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 +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 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 (dot appended) to system(). + +Perl will correctly start PM programs from VIO (=text-mode) Perl process; +the opposite is not true: when you start a non-PM program from a PM +Perl process, it would not run it in a separate session. If a separate +session is desired, 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 to be a feature. + +=head1 Frequently asked questions + +=head2 "It does not work" + +Perl binary distributions come with a F script which tries +to detect common problems with misconfigured installations. There is a +pretty large chance it will discover which step of the installation you +managed to goof. C<;-)> + +=head2 I cannot run external programs + +=over 4 + +=item * + +Did you run your programs with C<-w> switch? See +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 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 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 would be +equivalent: + + find "pattern" file + find pattern file + +=head1 INSTALLATION + +=head2 Automatic binary installation + +The most convenient way of installing a binary distribution of 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 +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 + +A folder is created on your desktop which contains some useful +objects. + +B + +=over 15 + +=item C + +may be needed if you change your codepage I perl installation, +and the new value is not supported by EMX. See L<"PERL_BADLANG">. + +=item C + +see L<"PERL_BADFREE">. + +=item F + +This file resides somewhere deep in the location you installed your +perl library, find it out by + + perl -MConfig -le "print $INC{'Config.pm'}" + +While most important values in this file I updated by the binary +installer, some of them may need to be hand-edited. I know no such +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 split +into 11 components. Unfortunately, to enable configurable binary +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 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. 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: + +=over 3 + +=item Perl VIO and PM executables (dynamically linked) + + 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 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 PATH); + +=item Executables for Perl utilities + + unzip perl_utl.zip -d f:/emx.add/bin + +(have the directory on PATH); + +=item Main Perl library + + unzip perl_mlb.zip -d f:/perllib/lib + +If this directory is exactly the same as the prefix which was compiled +into F, you do not need to change +anything. However, for perl to find the library if you use a different +path, you need to +C in F, see L<"PERLLIB_PREFIX">. + +=item Additional Perl modules + + unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.3/ + +Same remark as above applies. Additionally, if this directory is not +one of directories on @INC (and @INC is influenced by C), you +need to put this +directory and subdirectory F<./os2> in C or C +variable. Do not use C unless you have it set already. See +L. + +=item Tools to compile Perl modules + + unzip perl_blb.zip -d f:/perllib/lib + +Same remark as for F. + +=item Manpages for Perl and utilities + + unzip perl_man.zip -d f:/perllib/man + +This directory should better be on C. You need to have a +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 man to access these files. + +=item Source for Perl documentation + + unzip perl_pod.zip -d f:/perllib/lib + +This is used by the C program (see L), and may be used to +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 F<.INF> format + + unzip perl_inf.zip -d d:/os2/book + +This directory should better be on C. + +=item Pdksh + + unzip perl_sh.zip -d f:/bin + +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 sh-compatible shell +(file globbing - if done via shell - may break). + +=back + +After you installed the components you needed and updated the +F correspondingly, you need to hand-edit +F. This file resides somewhere deep in the location you +installed your perl library, find it out by + + perl -MConfig -le "print $INC{'Config.pm'}" + +You need to correct all the entries which look like file paths (they +currently start with C). + +=head2 B + +The automatic and manual perl installation leave precompiled paths +inside perl executables. While these paths are overwriteable (see +L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by +binary editing of paths inside the executables/DLLs. + +=head1 Accessing documentation + +Depending on how you built/installed perl you may have (otherwise +identical) Perl documentation in the following formats: + +=head2 OS/2 F<.INF> file + +Most probably the most convenient form. Under OS/2 view it as + + view perl + view perl perlfunc + view perl less + view perl ExtUtils::MakeMaker + +(currently the last two may hit a wrong location, but this may improve +soon). Under Win* see L<"SYNOPSIS">. + +If you want to build the docs yourself, and have I, run + + pod2ipf > perl.ipf + +in F directory, then + + ipfc /inf perl.ipf + +(Expect a lot of errors during the both steps.) Now move it on your +BOOKSHELF path. + +=head2 Plain text + +If you have perl documentation in the source form, perl utilities +installed, and GNU groff installed, you may use + + perldoc perlfunc + perldoc less + perldoc ExtUtils::MakeMaker + +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 man installed on your system, and you installed perl +manpages, use something like this: -In particular, it is VERY IMPORTANT to have a correct perl.dll on -LIBPATH during build, otherwise DLLs with wrong names will be -created. Either have a perl.dll with the same naming convention for DLLs -(hopefully, it should not change any time soon), or remove it from -LIBPATH, add . to LIBPATH, wait until the build of DynaLoader fails, -and then move the built DLL into LIBPATH. - -I also used this possibility to change perl linking type to -Zmt. It -means that Perl now uses multithreaded CRTDLL, so your extensions can -be multithreaded (note that the perl core is not thread-safe so far, -so make sure you access Perl from one thread only). In particular, it -is no longer needed to statically link X11_s.lib if you compile -Perl/Tk/XFree. - -Note however, that current Perl malloc is NOT MT-safe, and your extension -will use Perl malloc if perl does (as the default built does). - -This newer port includes - . numeric first argument to system(), see OS2::Process docs; - . modules OS2::Process, OS2::REXX, OS2::PrfDB, OS2::ExtAttrib. - . {get,set,end}*ent may work now (not checked) -(most of this merged from ak's port). - -Note that static build of OS2::ExtAttrib fails some tests! - -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. Some good -features from Andreas Kaiser port may have missed this port. However, most of -the features are available (possibly in different form). - -!!! Note that [gs]etpriority functions in this port are compatible -!!! with *nix, not with ak's port!!! - -The priorities are absolute, go from 32 to -95, lower is quickier. 0 -is default, - -Binary Install: -~~~~~~~~~~~~~~ -This version of perl allows binary installation on another site. There -are two possibilities: - a) sh.exe is in the directory with the same name as on machine -where perl was compiled (f:/bin here), and perl library is installed -into the same directory as the built target (f:/perllib); - b) One of the above conditions is not true. Perl may be -informed about location of sh.exe via PERL_SH_DRIVE or PERL_SH_DIR -(see below). To relocate the perl library, one can - b1) either use the usual PERLLIB environment variable - but -you should deduce yourself which components should be put there, say, -by doing - perl -de 0 - x \@INC - q -in the directory of the perl library. Another problem with this is -that a module is missing, then perl will try to scan the builtin -directories nevertheless. If perl was intended to be installed on -f:/perllib, but your f: is a CDROM, then you may have some trouble. - b2) Best: binary edit perl.dll and perl_.exe (using perl -itself as a binary editor) to fix the paths. Note that for best results ;-) -the new paths should be no longer than the old. - b3) More convinient: set PERLLIB_PREFIX environment -variable. It should contain two components, separated by whitespace -and/or semicolon `;'. The first component is translated to the second -one if it is - a prefix of - a component of - Perl library lookup path. -Say, if you install perllibrary into c:/lib/perl/ instead of -f:/perllib/, set it to - set PERLLIB_PREFIX=f:/perllib/;c:/lib/perl/ - -!!!! Note that if you have bin/sh.exe or Perl library in non-standard -!!!! location, you need to hand-edit Config.pm. The last time I -!!!! checked one should have scaned this file for `f:' and/or `F:' to find -!!!! all the entries to fix. - -!!!!!!!!!!!!! Somebody should write an install script which would auto-edit -!!!!!!!!!!!!! Config.pm. - -Reading the docs: -~~~~~~~~~~~~~~~~ -If your `man' is correctly installed, you should just add -x:/perllib/man directory to the end of MANPATH like this: - set MANPATH=c:/man;f:/perllib/man -After this you can access the docs like this: man perlfunc man 3 less man ExtUtils.MakeMaker -Note that dot is used as package separator for package documentation, -and as usual, sometimes you need to give the section - 3 above - to -avoid shadowing by the less(1) manpage. -Alternatively, you can build HTML docs by running +to access documentation for different components of Perl. Start with + + man perl + +Note that dot (F<.>) is used as a package separator for documentation +for packages, and as usual, sometimes you need to give the section - C<3> +above - to avoid shadowing by the I. + +Make sure that the directory B the directory with manpages is +on our C, like this + + set MANPATH=c:/man;f:/perllib/man + +for Perl manpages in C etc. + +=head2 HTML + +If you have some WWW browser available, installed the Perl +documentation in the source form, and Perl utilities, you can build +HTML docs. Cd to directory with F<.pod> files, and do like this + + cd f:/perllib/lib/pod pod2html -in x:/perllib/lib/pod directory. -Alternatively, you can build IPF source by running - pod2ipf > perl.ipf -in x:/perllib/lib/pod directory, and build (excellent! - best of perl -docs available!) .INF documentation by running - ipfc /inf perl.ipf -Move it on your BOOKSHELF path, and now you may inspect docs by - view perl -or - view perl keyword_to_see +After this you can direct your browser the file F in this +directory, and go ahead with reading docs, like this: -Alternatively you may pick up precompiled HTML and .INF docs from the -net, as usual, .INF is available on CPAN/.../os2/ilyaz. + explore file:///f:/perllib/lib/pod/perl.html -There are also _very_ good docs in TexInfo and Adobe PDF format. +Alternatively you may be able to get these docs prebuilt from CPAN. -Quieting warnings: -~~~~~~~~~~~~~~~~~ -Set environment variables PERL_BADFREE and/or PERL_BADLANG to 0 to -quiet the corresponding warnings. +=head2 GNU C files -Notes on build on OS/2: -~~~~~~~~~~~~~~~~~~~~~~~ -a) Make sure your sort is not the broken OS/2 one, and that you have /tmp -on the build partition. Make sure that your pdksh.exe, make.exe and -db.lib are OK (look elsewhere in this file). +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. -b) when extracting 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 -or - tar --case-sensitive -vzxf perl5.004.tar.gz perl5.004/Configure - -c) Necessary manual intervention when compiling on OS/2: - - Need to put perl.dll on LIBPATH after it is created. - I also have seen errors building ext/OS2/*/, during - generation of manpages, if there is a conflict of perl.exe - and perl.dll. It is safe to ignore these errors. - -d) Compile summary: - ~~~~~~~~~~~~~~~ -!!! At the end of this README is independent description of the build -!!! process by Rocco Caputo. - -# 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 - # Note that you need to have /tmp/ ready. - # - # Ignore the message about missing `ln', and about `c' option - # to tr. -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): - # - # To run finer tests, cd t && perl harness -make install - -e) At the end of August 1996 GNU make 3.74 is OK. - Note that the pdksh5.2.7 or later is required. - -!!!!!!!!!!!!!!!!! -If you see that some '/' became '\' in pdksh, you use an old pdksh! -Same with segfaults in Make 3.7? - use my patched verions. -!!!!!!!!!!!!!!!!! - -f) As distributed the DB library db.a-db.lib is not suitable for -linking with -Zmt. A recompiled version must be available from my FTP -site in os2/db_mt.zip. - -!!!!!!!!!!!!!!!! -If you see: - 'errno' - unresolved external -it means you use a wrong db.lib. -!!!!!!!!!!!!!!!! - -g) Make sure your gcc is good for -Zomf linking: run `omflibs' script in -/emx/lib directory. - -Problems reported: - -a) one of the latest tr is broken, get an old one :-( - 1.11 works. (On compuserver?) -b) You need 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). -====================================================== - -Building with a.out style is supported by the `perl_' target of make. -Dynamic extensions are not possible with perl_.exe, since boot code -should return the retvalue on the Perl stack, the address of which is -not known to the extension. Moreover: The build process for `perl_' -DOES NOT KNOW about dependencies, so you should make sure that -anything is up-to-date, say, by doing - make perl.dll -first. +=head2 F<.PDF> files -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(). - -====================================================== - -If you need to run PM code from perl, you may use PM mode executable -perl__.exe. It is subject to restrictions specific to PM programs: it -will close the VIO window the moment any PM call is performed. - -It is needed to run Perl/Tk (currently 7/96 - pre-alpha). - -====================================================== - -The reason why the executables are named perl_.exe and perl__.exe is -the following: Perl may parse #! lines in perl scripts to find out the -additional switches to enable. Thus there is a convention `What is a -perl executable - judging by name', and the above names conform to -this convention. - -====================================================== -Tests which fail -~~~~~~~~~~~~~~~~ -with OMF compile (fork works - and all the related -test - with A.OUT compile): - -io/fs.t: 2-5, 7-11, 18 as they should. -io/pipe: all, since open("|-") is not working (works with perl_.exe). -lib/"all the dbm".t: 1 test should fail (file permission). -lib/io_pipe io_sock, as they should: use fork. -op/fork all fail, as they should (except with perl_.exe) -op/stat 3 20 35 as they should, 39 (-t on /dev/null) ???? Sometimes 4 -- timing problem ???? - -Sometimes I have seen segfault in socket ????, only if run with Testing tools. - -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 0. - -Here is my result with OMF: - -Test Status Wstat Total Fail Success List of failed ------------------------------------------------------------------------------- -io/fs.t 22 10 45.45% 2-5, 7-11, 18 -io/pipe.t 1 256 8 ?? % ?? -lib/anydbm.t 12 1 8.33% 2 -lib/db-btree.t 86 1 1.16% 20 -lib/db-hash.t 43 1 2.33% 16 -lib/db-recno.t 35 1 2.86% 18 -lib/io_pipe.t 2 512 6 ?? % ?? -lib/io_sock.t 255 65280 5 ?? % ?? -lib/sdbm.t 12 1 8.33% 2 -op/exec.t 8 1 12.50% 5 -op/fork.t 255 65280 2 ?? % ?? -op/stat.t 56 4 7.14% 3, 20, 35, 39 -Failed 12/104 test scripts, 88.46% okay. 41/2224 subtests failed, 98.16% okay. - -and with A.OUT: - -Test Status Wstat Total Fail Failed List of failed ------------------------------------------------------------------------------- -io/fs.t 22 10 45.45% 2-5, 7-11, 18 -lib/anydbm.t 12 1 8.33% 2 -lib/db-btree.t 86 1 1.16% 20 -lib/db-hash.t 43 1 2.33% 16 -lib/db-recno.t 35 1 2.86% 18 -lib/sdbm.t 12 1 8.33% 2 -op/exec.t 8 1 12.50% 5 -op/stat.t 56 4 7.14% 3, 20, 35, 39 -Failed 8/104 test scripts, 92.31% okay. 20/2224 subtests failed, 99.10% okay. - -Note that op/exec.5 fail because I do not have /bin/sh on this drive. - -With newer configs I could not reproduce most the crashes. However, -after fixpak17 REXX variables acquire a trailing '\0' at end when go -through the variable pool (even if they had one), thus making some -REXX tests fail. - -======================================================= - -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 -X:/bin/sh.exe will be called. The name of the shell is -overridable, as described below. - -Thus means that you need to pickup some copy of a sh.exe as well (I use one -from pdksh). The drive X: above is set up automatically during the -build, is settable in runtime from $ENV{PERL_SH_DRIVE}. Another way to -change it is to set $ENV{PERL_SH_DIR} to be the directory in which -sh.exe resides. - -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. +for C are available on CPAN (for slightly old version of +perl). -=================================================== +=head2 C docs -OS/2 extensions -~~~~~~~~~~~~~~~ -Since binaries cannot go into perl distribution, no extensions are -included. They are available in .../os2/ilyaz directory of CPAN, as -well as in my directory - ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2 +can be constructed using C. -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. Other extensions -there are OS2::ExtAttribs, OS2::PrfDB for tied access to EAs and .INI -files - and maybe some other extensions at the time you read it. +=head1 BUILD -Note that OS2 perl defines 2 pseudo-extension functions -OS2::Copy::copy and DynaLoader::mod2fname. +Here we discuss how to build Perl under OS/2. There is an alternative +(but maybe older) view on http://www.shadow.net/~troc/os2perl.html -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...}; +=head2 The short story -Two new functions are supported by REXX code, - REXX_eval 'string'; - REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference; +Assume that you are a seasoned porter, so are sure that all the necessary +tools are already present on your system, and you know how to get the Perl +source distribution. Untar it, change to the extract directory, and -If you have some other extensions you want to share, send the code to -me. At least two are available: tied access to EA's, and tied access -to system databases. + gnupatch -p0 < os2\diff.configure + sh Configure -des -D prefix=f:/perllib + make + make test + make install + make aout_test + make aout_install + +This puts the executables in f:/perllib/bin. Manually move them to the +C, manually move the built F to C (here F<*> is +a not-very-meaningful hex checksum), and run + + make installcmd INSTALLCMDDIR=d:/ir/on/path + +What follows is a detailed guide through these steps. + +=head2 Prerequisites + +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 + + find --version + sort --version + +). 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/ + ftp://ftp.cdrom.com/pub/os2/unix/ + ftp://ftp.cdrom.com/pub/os2/dev32/ + ftp://ftp.cdrom.com/pub/os2/emx09c/ + +It is reported that the following archives contain enough utils to +build perl: F, F, F, F, +F, F, F, F and +F (or a later version). Note that all these utilities are +known to be available from LEO: + + ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu + +If you have I installed already, +make sure that no copies or perl are currently running. Later steps +of the build may fail since an older version of F loaded into +memory may be found. + +Also make sure that you have F directory on the current drive, +and F<.> directory in your C. One may try to correct the +latter condition by + + set BEGINLIBPATH . + +if you use something like F or latest versions of F<4os2.exe>. + +Make sure your gcc is good for C<-Zomf> linking: run C +script in F directory. + +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 +link386 prompts, press C to exit. + +=head2 Getting perl source + +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 + http://www.perl.com/CPAN/src/5.0/unsupported + +If not, you may need to dig in the indices to find it in the directory +of the current maintainer. + +Quick cycle of developers release may break the OS/2 build time to +time, looking into + + http://www.perl.com/CPAN/ports/os2/ilyaz/ + +may indicate the latest release which was publicly released by the +maintainer. Note that the release may include some additional patches +to apply to the current source of perl. + +Extract it like this + + tar vzxf perl5.00409.tar.gz + +You may see a message about errors while extracting F. This is +because there is a conflict with a similarly-named file F. + +Change to the directory of extraction. + +=head2 Application of the patches + +You need to apply the patches in F<./os2/diff.*> like this: + + 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 EMX distribution +are not suitable for multi-threaded compile (even single-threaded +flavor of Perl uses multi-threaded C RTL, for +compatibility with XFree86-OS/2). Get a corrected one from + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip + +=head2 Hand-editing -================================================================== -== == -== User report [my comments in brackets, IZ] == -== == -== A web page: http://www.shadow.net/~troc/os2perl.html == -== == -================================================================== - -Starting in x:/usr/src, using 4OS2/32 2.5 as the command interpreter on -OS/2 2.30 with FixPak-17. DAX is installed, but this shouldn't be a -factor. Drive X is a TVFS virtual drive pointing to several physical -HPFS drives. - ->>> Make sure that no copies or perl are currently running. Miniperl - may fail during the build because it will find an older version - of perl.dll loaded in memory. - - Close any running perl scripts. - Shut down anything that might run perl scripts, like cron. - `emxload -l` to check for loaded versions of perl. - `emxload -u perl.exe` to unload them. - ->>> Pre-load some common utilities: - - emxload -e sh.exe make.exe ls.exe tr.exe id.exe sed.exe - SET GCCLOAD=30 (number of minutes to hold the compiler) -[grep egrep fgrep cat rm uniq basename uniq sort - are not bad too.] - The theory is that it's faster to demand-load the development tools - from virtual memory than it is to re-load and re-link them all the - time. This is definitely true with my system because swapfile.dat - is on a faster drive than my development environment. - - ls, tr, and id represent the GNU file, text, and shell utilities. - These may not be needed, but it makes sure that their respective - DLLs are in memory. - ->>> Unpack the perl 5_002_01 archive onto an HPFS partition. - - tar vxzf perl5_002_01.tar-gz - cd perl5.002_01 - -[Do not forget to extract Configure as described above.] - ->>> Read the README, keeping a copy open in another session for reference. - - start /c /fg less os2/README - ->>> Apply the OS/2 patches included with 5.002_01, as per the README. - - for %m in (os2\diff.*) patch -p0 < %m - patch -p0 < os2\POSIX.mkfifo - -[The patch below is already applied.] - ->>> You may need to apply this patch if you plan to run a non-standard - Configure (that is, if you defy the README). This patch will ensure - that Makefile inherits the libraries specified during Configure. - People running standard perl builds can probably ignore this patch. - -*** os2\Makefile.SHs Mon Mar 25 02:05:00 1996 ---- os2\Makefile.SHs.new Fri May 24 10:37:10 1996 -*************** -*** 9,15 **** - emximp -o perl.imp perl5.def - - perl.dll: $(obj) perl5.def perl$(OBJ_EXT) -! $(LD) $(LDDLFLAGS) -o $@ perl$(OBJ_EXT) $(obj) -lsocket perl5.def - - perl5.def: perl.linkexp - echo "LIBRARY 'Perl' INITINSTANCE TERMINSTANCE" > $@ ---- 9,15 ---- - emximp -o perl.imp perl5.def - - perl.dll: $(obj) perl5.def perl$(OBJ_EXT) -! $(LD) $(LDDLFLAGS) -o $@ perl$(OBJ_EXT) $(obj) $(libs) perl5.def - - perl5.def: perl.linkexp - echo "LIBRARY 'Perl' INITINSTANCE TERMINSTANCE" > $@ -*************** -*** 49,55 **** - cat perl.exports perl.map | sort | uniq -d | sed -e 's/\w\+/ "\0"/' > perl.linkexp - - perl.map: $(obj) perl$(OBJ_EXT) miniperlmain$(OBJ_EXT) -! $(CC) $(LARGE) $(CLDFLAGS) $(CCDLFLAGS) -o dummy.exe miniperlmain$(OBJ_EXT) perl$(OBJ_EXT) $(obj) -lsocket -lm -Zmap -Zlinker /map - awk '{if ($$3 == "") print $$2}' perl.map - rm dummy.exe dummy.map - ---- 49,55 ---- - cat perl.exports perl.map | sort | uniq -d | sed -e 's/\w\+/ "\0"/' > perl.linkexp - - perl.map: $(obj) perl$(OBJ_EXT) miniperlmain$(OBJ_EXT) -! $(CC) $(LARGE) $(CLDFLAGS) $(CCDLFLAGS) -o dummy.exe miniperlmain$(OBJ_EXT) perl$(OBJ_EXT) $(obj) $(libs) -Zmap -Zlinker /map - awk '{if ($$3 == "") print $$2}' perl.map - rm dummy.exe dummy.map - ->>> Apply the patches from Ilya's perl5.002_01 binary distribution: - - touch os2/dlfcn.h os2/dl_os2.c - patch -p1 < f:\perllib\README.fix1 - ->>> Run Configure. Most people can run it by following the README: - - sh Configure -des -D prefix=f:/usr/local - - Advanced perl users (experienced C programmers, recommended) can run - the interactive Configure and answer the questions. When in doubt - about an answer, check the EMX headers and documentation. Pick the - default answer if that doesn't help: - - sh Configure - -[Yet more advanced users just specify the answers on the command line -of Configure, like I did with prefix.] - - Note: You may need to wrap an answer in quotes if it contains - spaces. For example, "-lsocket -lm". - - Note: If you want to add some options to a long default, you can - use $* to include the default in your answer: "$* -DDEBUGGING". - - Configure warnings and errors, and possible work-arounds: - - I don't know where 'ln' is.... - (ignored; OS/2 doesn't have a ln command) - - nm didn't seem to work right. Trying emxomfar instead... - (nothing to worry about) - - The recommended value for $d_shrplib on this machine was "define"! - (kept the recommended value: y) - - Directory f:/usr/lib/perl5/os2/5.00201/CORE doesn't exist. - (created the directory from another window with - \usr\bin\mkdir -p f:/usr/lib/perl5/os2/5.00201/CORE - and then answered: y. Your directory may look different.) - -[Ignore this as well, install script will create it for you.] - - The recommended value for $i_dlfcn on this machine was "define"! - (kept the recommended value: y) - - The recommended value for $d_fork on this machine was "undef"! - (kept the recommended value: y) - - Figuring out the flag used by open() for non-blocking I/O... - Seems like we can use O_NONBLOCK. - This seems to be used for informative purposes only. - The errors that follow this (including a SIGPIPE) don't seem - to affect perl at all. These were safely ignored. - - What pager is used on your system? [/usr/ucb/more] - Had to answer "/usr/bin/less.exe" because Configure wants a - leading / (unix full path). Need to edit config.sh later with - the real full path to the pager, including the drive letter. - -[Apparently this setting is never used, so it is safe to ignore it.] - - Hmm... F:/USR/BIN/sed: Unterminated `s' command - Perl built fine even with this error, so it seems safe to - ignore. - - Things I did different from the defaults. Most (if not all) of these - are optional changes. They're listed here to show how good Configure - is at detecting the system setup. - -[I add the options to put it on command line of Configure, see below.] - - Selected 'none' for the man1 location. - (I prefer the pod2html version.) -[-D man1dir=none] - Selected 'none' for the man3 location. - (I prefer the pod2html version.) -[-D man3dir=none] - Changed the hostname and domain. - (I wanted to override a dynamic PPP address. This only - matters if other people will be using your perl build.) -[-D myhostname=my_host_name -D mydomain=.foo.org] - Fixed the e-mail address. - (Put in a known working e-mail address. This only matters - if other people will be using your perl build.) -[-D cf_email=root@myhostname.uucp] - Added some directories to the library search path. -[-D "libpth=f:/emx/lib/st f:/emx/lib"] - Added -g to the optimizer/debugger flags. -[-D optimize=-g] - Added "-lgdbm -ldb -lcrypt -lbsd" to the additional libraries. -[ -D "libs=-lsocket -lcrypt -lgdbm" - the rest of libraries will not be used] +You may look into the file F<./hints/os2.sh> and correct anything +wrong you find there. I do not expect it is needed anywhere. ->>> Advanced users may want to edit config.sh when prompted by Configure. - Most (all?) of these changes aren't really necessary: +=head2 Making - d_getprior='define' - d_setprior='define' - (getpriority and setpriority are included in os2.c, but - Configure doesn't know to look there.) -[fixed already] - pager='f:/usr/bin/less.exe' - (Correcting Configure's insistence on a leading slash.) - bin_sh='f:/usr/bin/sh.exe' - (If Configure detects sh.exe somewhere else first. Example: - it saw sh.exe at /bin/sh.exe on my TVFS drive, but I want - perl to look for it on the physical F drive.) - aout_ccflags='... existing flags... -DDEBUGGING' - aout_cppflags='... existing flags... -DDEBUGGING' - (If you want to include DEBUGGING for the aout version.) -[Do not do it, -D optimize=-g will automatically add these flags.] + sh Configure -des -D prefix=f:/perllib ->>> Allow Configure to make the build scripts. +C means: where to install the resulting perl library. Giving +correct prefix you may avoid the need to specify C, +see L<"PERLLIB_PREFIX">. ->>> Allow Configure to run `make depend`. Ignore the following warning: +I, and about C<-c> option to +tr>. The latter is most probably already fixed, if you see it and can trace +where the latter spurious warning comes from, please inform me. - perl.h:861: warning: `DEBUGGING_MSTATS' redefined -[corrected now] - ->>> Rename any existing perl.dll, preventing anything from loading it and - saving a known working copy in case something goes wrong: - - mv /usr/lib/perl.dll /usr/lib/ilya-perl.dll +Now ->>> Run `make`, and ignore the following warnings: - - perl.h:861: warning: `DEBUGGING_MSTATS' redefined -[corrected now] - invalid preprocessing directive name - emxomf warning: Cycle detected by make_type - LINK386 : warning L4071: application type not specified; assuming WINDOWCOMPAT - Warning (will try anyway): No library found for -lposix - Warning (will try anyway): No library found for -lcposix - POSIX.c:203: warning: `mkfifo' redefined - POSIX.c:4603: warning: assignment makes pointer from integer without a cast - ->>> If `make` dies while "Making DynaLoader (static)", you'll need to - put miniperl in the OS/2 paths. This step is only necessary if `make` - can't find miniperl: -[I would be interested if somebody confirmes this.] - - cp perl.dll /usr/lib (where /usr/lib is in your LIBPATH) - cp miniperl.exe /usr/bin (where /usr/bin is in your PATH) - make (ignore the errors in the previous step) - - This should run to completion. - ->>> Test the build: - - make test - - These tests fail: + make - io/fs..........FAILED on test 2 - - "OS/2 is not unix". Test 2 checks the link() command, which - is not supported by OS/2. - - io/pipe........f:/usr/bin/sh.exe: -c requires an argument - f:/usr/bin/sh.exe: -c requires an argument - The Unsupported function fork function is unimplemented at - io/pipe.t line 26. - FAILED on test 1 - - More "OS/2 is not unix" errors. Read ahead to find out - why fork() fails. - - op/exec........FAILED on test 4 - - if (system "true") {print "not ok 4\n";} else \ - {print "ok 4\n";} - - This fails for me, but changing it to read like this works: - - if (system '\usr\bin\true.cmd') {print "not ok 4\n";} \ - else {print "ok 4\n";} - - So you can count this as another "OS/2 is not unix". +At some moment the built may die, reporting a I or +I>. This means that you do not have F<.> in +your LIBPATH, so F cannot find the needed F (treat +these hex digits as line noise). After this is fixed the build +should finish without a lot of fuss. - op/fork........The Unsupported function fork function is \ - unimplemented at op/fork.t line 8. - FAILED on test 1 +=head2 Testing - The dynamically-loaded version of perl currently doesn't - support fork(). This is a known behavior of EMX. +Now run - op/magic....... - Process terminated by SIGINT - ok + make test - The test passed even with the SIGINT message. I don't - know why, but I won't argue. +All tests should succeed (with some of them skipped). - op/stat........ls: /dev: No such file or directory - f:/usr/bin/sh.exe: ln: not found - ls: perl: No such file or directory - FAILED on test 3 +Some tests may generate extra messages similar to - "OS/2 is not unix". We don't have the ln command. +=over 4 - lib/anydbm.....Bad free() ignored at lib/anydbm.t line 51. - Bad free() ignored at lib/anydbm.t line 51. - Bad free() ignored at lib/anydbm.t line 51. - Bad free() ignored during global destruction. - Bad free() ignored during global destruction. - Bad free() ignored during global destruction. - FAILED on test 2 +=item A lot of C - Test 2 looks at the file permissions for a database. "OS/2 - is not unix" so the permissions aren't exactly what this test - expects. +in database tests related to Berkeley DB. I +If it persists, you may disable this warnings, see L<"PERL_BADFREE">. - lib/db-btree...Bad free() ignored at lib/db-btree.t line 109. - Bad free() ignored at lib/db-btree.t line 221. - Bad free() ignored at lib/db-btree.t line 337. - Bad free() ignored at lib/db-btree.t line 349. - Bad free() ignored at lib/db-btree.t line 349. - Bad free() ignored at lib/db-btree.t line 399. - Bad free() ignored at lib/db-btree.t line 400. - Bad free() ignored at lib/db-btree.t line 401. - FAILED on test 20 +=item Process terminated by SIGTERM/SIGINT - Another file permissions test fails. +This is a standard message issued by OS/2 applications. *nix +applications die in silence. It is considered to be a feature. One can +easily disable this by appropriate sighandlers. - lib/db-hash....Bad free() ignored at lib/db-hash.t line 101. - Bad free() ignored at lib/db-hash.t line 101. - Bad free() ignored at lib/db-hash.t line 101. - Bad free() ignored at lib/db-hash.t line 239. - Bad free() ignored at lib/db-hash.t line 239. - Bad free() ignored at lib/db-hash.t line 239. - Bad free() ignored at lib/db-hash.t line 253. - Bad free() ignored at lib/db-hash.t line 253. - Bad free() ignored at lib/db-hash.t line 253. - FAILED on test 16 +However the test engine bleeds these message to screen in unexpected +moments. Two messages of this kind I be present during +testing. - Another file permissions test fails. +=back - lib/db-recno...Bad free() ignored at lib/db-recno.t line 138. - Bad free() ignored at lib/db-recno.t line 138. - FAILED on test 18 +To get finer test reports, call - Another file permissions test fails. + perl t/harness - lib/gdbm.......FAILED on test 2 +The report with F failing may look like this: - Another file permissions test fails. + 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. - lib/sdbm.......FAILED on test 2 +The reasons for most important skipped tests are: - Another file permissions test fails. +=over 8 - Failed 11/94 tests, 88.30% okay. +=item F - All of which are known differences with unix or documented - behaviors in EMX. I re-run the test with Ilya's version, - and the same tests fail. This new build is a success. -[Note that bad free() mentioned above are bugs in the Berkeley -DB. They just are more visible under OS/2 with perl free(), because of -"rigid" function name resolution. You may disable it by setting -PERL_BADFREE environment variable to 0. - To get finer tests, cd to ./t and run - perl harness -] +=over 4 - (Actually, Ilya's perl release fails an extra test because I don't - have sed in f:\emx.add. This shows how important it is to configure - and build perl yourself instead of grabbing pre-built binaries.) -[Hmm, should not happen... There is no mentions of full_sed under ./t -directory...] +=item 18 ->>> Cross your fingers and install it: +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). - make install +=item 25 - Warnings encountered and workarounds presented.: +Checks C on a filehandle just opened for write - I do not +know why this should or should not work. - WARNING: You've never run 'make test'!!! (Installing anyway.) - (Lies! All lies! At least it still installs.) +=back - WARNING: Can't find libperl*.dll* to install into \ - f:/usr/lib/perl5/os2/5.00201/CORE. (Installing other things anyway.) - (Safe to ignore. The important one, libperl.lib, gets copied.) +=item F - Couldn't copy f:/usr/bin/perl5.00201.exe to f:/usr/bin/perl.exe: \ - No such file or directory - cp /usr/bin/perl5.00201.exe /usr/bin/perl.exe +Checks C. Tests: - Couldn't copy f:/usr/bin/perl.exe to /usr/bin/perl.exe: No such \ - file or directory - (I think this one is safe to ignore since the two directories - point to the same place.) +=over 4 ->>> Laugh maniacally because you just built and installed your own copy - of perl, with all the paths set "just so" and with whatever little - psychotic modifications you've always wanted but were afraid to add. +=item 4 ------------------------------------------------------------------------------ +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). -Development tools and versions: +=back - EMX 0.9b with emxfix04 applied. +=back - `ls --version` reports: 'GNU file utilities 3.12' - `tr --version` reports: 'tr - GNU textutils 1.14' - `id --version` reports: 'id - GNU sh-utils 1.12' +=head2 Installing the built perl - `sed --version` reports: 'GNU sed version 2.05' - `awk --version` reports: 'Gnu Awk (gawk) 2.15, patchlevel 6' - `grep --version` reports an illegal option and: 'GNU grep version 2.0' - (this includes egrep) +If you haven't yet moved perl.dll onto LIBPATH, do it now. - `sort --version` reports: 'sort - GNU textutils 1.14' - `uniq --version` reports: 'uniq - GNU textutils 1.14' - `find --version` reports: 'GNU find version 4.1' +Run + + make install + +It would put the generated files into needed locations. Manually put +F, F and F to a location on your +PATH, F to a location on your LIBPATH. + +Run + + make installcmd INSTALLCMDDIR=d:/ir/on/path + +to convert perl utilities to F<.cmd> files and put them on +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. + +=head2 C-style build + +Proceed as above, but make F (see L<"perl_.exe">) by + + make perl_ + +test and install by + + make aout_test + make aout_install + +Manually put F to a location on your PATH. + +B The build process for C I about all the +dependencies, so you should make sure that anything is up-to-date, +say, by doing + + make perl_dll + +first. + +=head1 Build FAQ + +=head2 Some C became C<\> in pdksh. + +You have a very old pdksh. See L. + +=head2 C<'errno'> - unresolved external + +You do not have MT-safe F. See L. + +=head2 Problems with tr or sed + +reported with very old version of tr and sed. + +=head2 Some problem (forget which ;-) + +You have an older version of F on your LIBPATH, which +broke the build of extensions. + +=head2 Library ... not found + +You did not run C. See L. + +=head2 Segfault in make + +You use an old version of GNU make. See L. + +=head2 op/sprintf test failure + +This can result from a bug in emx sprintf which was fixed in 0.9d fix 03. + +=head1 Specific (mis)features of OS/2 port + +=head2 C, C + +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 quicker. 0 is the default priority. + +B. Calling C on a non-existing process can lock the +system before Warp3 fixpak22. + +=head2 C + +Multi-argument form of C allows an additional numeric +argument. The meaning of this argument is described in +L. + +When finding a program to run, Perl first asks the OS to look for executables +on C. If not found, it looks for a script with possible extensions +added in this order: no extension, F<.cmd>, F<.btm>, +F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic +strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the +first line as the beginning of the command line to run this script. The +only mangling done to the first line is extraction of arguments (currently +up to 3), and ignoring of the path-part of the "interpreter" name if it can't +be found using the full path. + +E.g., C may lead Perl to finding +F with the first line being + + extproc /bin/bash -x -c + +If F is not found, and appending of executable extensions to +F does not help either, then Perl looks for an executable F on +C. If found in F, then the above system() is +translated to + + system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz) + +One additional translation is performed: instead of F Perl uses +the hardwired-or-customized shell (see C>). + +The above search for "interpreter" is recursive: if F executable is not +found, but F is found, Perl will investigate its first line etc. +The only hardwired limit on the recursion depth is implicit: there is a limit +4 on the number of additional arguments inserted before the actual arguments +given to system(). In particular, if no additional arguments are specified +on the "magic" first lines, then the limit on the depth is 4. + +If Perl finds that the found executable is of different type than the +current session, it will start the new process in a separate session of +necessary type. Call via C to disable this magic. + +=head2 C on the first line + +If the first chars of a Perl 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). See L. + +=head2 Additional modules: + +L, L, L, L, L. These +modules provide access to additional numeric argument for C +and to the information about the running process, +to DLLs having functions with REXX signature and to the REXX runtime, to +OS/2 databases in the F<.INI> format, and to Extended Attributes. + +Two additional extensions by Andreas Kaiser, C, and +C, are included into C directory, mirrored on CPAN. + +=head2 Prebuilt methods: + +=over 4 + +=item C + +used by C, see L. + +=item C + +used by C for DLL name mangling. + +=item C + +Self explanatory. + +=item C + +leaves drive as it is. + +=item C + +chanes the "current" drive. + +=item C + +means has drive letter and is_rooted. + +=item C + +means has leading C<[/\\]> (maybe after a drive-letter:). + +=item C + +means changes with current dir. + +=item C + +Interface to cwd from EMX. Used by C. + +=item C + +Really really odious function to implement. Returns absolute name of +file which would have C if CWD were C. C defaults to the +current dir. + +=item C + +Get current value of extended library search path. If C is +present and I, works with END_LIBPATH, otherwise with +C. + +=item C + +Set current value of extended library search path. If C is +present and I, works with END_LIBPATH, otherwise with +C. + +=item C + +Returns C if it was not called yet, otherwise bit 1 is +set if on the previous call do_harderror was enabled, bit +2 is set if if on previous call do_exception was enabled. + +This function enables/disables error popups associated with +hardware errors (Disk not ready etc.) and software exceptions. + +I know of no way to find out the state of popups I the first call +to this function. + +=item C + +Returns C if it was not called yet, otherwise return false if errors +were not requested to be written to a hard drive, or the drive letter if +this was requested. + +This function may redirect error popups associated with hardware errors +(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at +the root directory of the specified drive. Overrides OS2::Error() specified +by individual programs. Given argument undef will disable redirection. + +Has global effect, persists after the application exits. + +I know of no way to find out the state of redirection of popups to the disk +I the first call to this function. + +=item OS2::SysInfo() + +Returns a hash with system information. The keys of the hash are + + MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS, + MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION, + MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE, + VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION, + MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM, + TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL, + MAX_COMP_LENGTH, FOREGROUND_FS_SESSION, + FOREGROUND_PROCESS + +=item OS2::BootDrive() + +Returns a letter without colon. + +=item C, C + +Transforms the current application into a PM application and back. +The argument true means that a real message loop is going to be served. +OS2::MorphPM() returns the PM message queue handle as an integer. + +See L<"Centralized management of resources"> for additional details. + +=item C + +Fake on-demand retrieval of outstanding PM messages. If C is false, +will not dispatch messages if a real message loop is known to +be present. Returns number of messages retrieved. + +Dies with "QUITing..." if WM_QUIT message is obtained. + +=item C + +Retrieval of PM messages until window creation/destruction. +If C is false, will not dispatch messages if a real message loop +is known to be present. + +Returns change in number of windows. If C is given, +it is incremented by the number of messages retrieved. + +Dies with "QUITing..." if WM_QUIT message is obtained. + +=item C + +the same as L<_control87(3)> of EMX. Takes integers as arguments, returns +the previous coprocessor control word as an integer. Only bits in C which +are present in C are changed in the control word. + +=item OS2::get_control87() + +gets the coprocessor control word as an integer. + +=item C + +The variant of OS2::_control87() with default values good for +handling exception mask: if no C, uses exception mask part of C +only. If no C, disables all the floating point exceptions. + +See L<"Misfeatures"> for details. + +=back + +(Note that some of these may be moved to different libraries - +eventually). + + +=head2 Prebuilt variables: + +=over 4 + +=item $OS2::emx_rev + +same as _emx_rev of EMX, a string similar to C<0.9c>. + +=item $OS2::emx_env + +same as _emx_env of EMX, a number similar to 0x8001. + +=item $OS2::os_ver + +a number C. + +=back + +=head2 Misfeatures + +=over 4 + +=item * + +Since L is present in EMX, but is not functional, it is +emulated by perl. To disable the emulations, set environment variable +C. + +=item * + +Here is the list of things which may be "broken" on +EMX (from EMX docs): + +=over 4 + +=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 pdksh. + +=item * + +Unix-domain sockets on OS/2 live in a pseudo-file-system C. +To avoid a failure to create a socket with a name of a different form, +C<"/socket/"> is prepended to the socket name (unless it starts with this +already). + +This may lead to problems later in case the socket is accessed via the +"usual" file-system calls using the "initial" name. + +=item * + +Apparently, IBM used a compiler (for some period of time around '95?) which +changes FP mask right and left. This is not I bad for IBM's +programs, but the same compiler was used for DLLs which are used with +general-purpose applications. When these DLLs are used, the state of +floating-point flags in the application is not predictable. + +What is much worse, some DLLs change the floating point flags when in +_DLLInitTerm() (e.g., F). This means that even if you do not I +any function in the DLL, just the act of loading this DLL will reset your +flags. What is worse, the same compiler was used to compile some HOOK DLLs. +Given that HOOK dlls are executed in the context of I the applications +in the system, this means a complete unpredictablity of floating point +flags on systems using such HOOK DLLs. E.g., F of B +origin changes the floating point flags on each write to the TTY of a VIO +(windowed text-mode) applications. + +Some other (not completely debugged) situations when FP flags change include +some video drivers (?), and some operations related to creation of the windows. +People who code B may have more experience on this. + +Perl is generally used in the situation when all the floating-point +exceptions are ignored, as is the default under EMX. If they are not ignored, +some benign Perl programs would get a C and would die a horrible death. + +To circumvent this, Perl uses two hacks. They help against I type of +damage only: FP flags changed when loading a DLL. + +One of the hacks is to disable floating point exceptions on startup (as +is the default with EMX). This helps only with compile-time-linked DLLs +changing the flags before main() had a chance to be called. + +The other hack is to restore FP flags after a call to dlopen(). This helps +against similar damage done by DLLs _DLLInitTerm() at runtime. Currently +no way to switch these hacks off is provided. + +=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, C + +these EMX functions do not work if the path contains a trailing C. +Perl contains a workaround for this. + +=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 + +=head2 Identifying DLLs + +All the DLLs built with the current versions of Perl have ID strings +identifying the name of the extension, its version, and the version +of Perl required for this DLL. Run C to find this +info. + +=head2 Centralized management of resources + +Since to call certain OS/2 API one needs to have a correctly initialized +C subsystem, OS/2-specific extensions may require getting Cs and +Cs. If an extension would do it on its own, another extension could +fail to initialize. + +Perl provides a centralized management of these resources: + +=over + +=item C + +To get the HAB, the extension should call C in C. After +this call is performed, C may be accessed as C. There is +no need to release the HAB after it is used. + +If by some reasons F cannot be included, use + + extern int Perl_hab_GET(void); + +instead. + +=item C + +There are two cases: + +=over + +=item * + +the extension needs an C only because some API will not work otherwise. +Use C below. + +=item * + +the extension needs an C since it wants to engage in a PM event loop. +Use C below. + +=back + +To get an C, the extension should call C in C. +After this call is performed, C may be accessed as C. + +To signal to Perl that HMQ is not needed any more, call +C. Perl process will automatically morph/unmorph itself +into/from a PM process if HMQ is needed/not-needed. Perl will automatically +enable/disable C message during shutdown if the message queue is +served/not-served. + +B. If during a shutdown there is a message queue which did not disable +WM_QUIT, and which did not process the received WM_QUIT message, the +shutdown will be automatically cancelled. Do not call C +unless you are going to process messages on an orderly basis. + +=back + +=head1 Perl flavors + +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: + +=head2 F + +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 CRT DLL. This executable is a +VIO application. + +It can load perl dynamic extensions, and it can fork(). + +B Keep in mind that fork() is needed to open a pipe to yourself. + +=head2 F + +This is a statically linked C-style executable. It cannot +load dynamic Perl extensions. The executable supplied in binary +distributions has a lot of extensions prebuilt, thus the above restriction is +important only if you use custom-built extensions. This executable is a VIO +application. + +I The +friends locked into C world would appreciate the fact that this +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 F, but it is a PM +application. + +B Usually (unless explicitly redirected during the startup) +STDIN, STDERR, and STDOUT of a PM +application are redirected to F. However, it is possible to I +them if you start C from a PM program which emulates a +console window, like I of Emacs or EPM. Thus it I to use Perl debugger (see L) to debug your PM +application (but beware of the message loop lockups - this will not +work if you have a message queue to serve, unless you hook the serving +into the getc() function of the debugger). + +Another way to see the output of a PM program is to run it as + + pm_prog args 2>&1 | cat - + +with a shell I from F, so that it does not create +a link between a VIO session and the session of C. (Such a link +closes the VIO window.) E.g., this works with F - or with Perl! + + open P, 'pm_prog args 2>&1 |' or die; + print while

; + +The flavor F is required if you want to start your program without +a VIO window present, but not Ced (run C for more info). +Very useful for extensions which use PM, like C or C. + +=head2 F + +This is an C-style executable which is dynamically linked to +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 VIO application. + +=head2 Why strange names? + +Since Perl processes the C<#!>-line (cf. +L, L, +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 convention which do not contain +digits (which have absolutely different semantics). + +=head2 Why dynamic linking? + +Well, having several executables dynamically linked to the same huge +library has its advantages, but this would not substantiate the +additional work to make it compile. The reason is the complicated-to-developers +but very quick and convenient-to-users "hard" dynamic linking used by OS/2. + +There are two distinctive features of the dyna-linking model of OS/2: +all the references to external functions are resolved at the compile time; +there is no runtime fixup of the DLLs after they are loaded into memory. +The first feature is an enormous advantage over other models: it avoids +conflicts when several DLLs used by an application export entries with +the same name. In such cases "other" models of dyna-linking just choose +between these two entry points using some random criterion - with predictable +disasters as results. But it is the second feature which requires the build +of F. + +The address tables of DLLs are patched only once, when they are +loaded. The addresses of the entry points into DLLs are guaranteed to be +the same for all the programs which use the same DLL. This removes the +runtime fixup - once DLL is loaded, its code is read-only. + +While this allows some (significant?) performance advantages, this makes life +much harder for developers, since the above scheme makes it impossible +for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this +would need a DLL to have different relocations tables for the +(different) executables which use this DLL. + +However, a dynamically loaded Perl extension is forced to use some symbols +from the perl +executable, e.g., to know how to find the arguments to the functions: +the arguments live on the perl +internal evaluation stack. The solution is to put the main code of +the interpreter into a DLL, and make the F<.EXE> file which just loads +this DLL into memory and supplies command-arguments. The extension DLL +cannot link to symbols in F<.EXE>, but it has no problem linking +to symbols in the F<.DLL>. + +This I increases the load time for the application (as well as +complexity of the compilation). Since interpreter is in a DLL, +the C RTL is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). There are some advantages if +you use different flavors of perl, such as running F and +F simultaneously: they share the memory of F. + +B. There is one additional effect which makes DLLs more wasteful: +DLLs are loaded in the shared memory region, which is a scarse resource +given the 512M barrier of the "standard" OS/2 virtual memory. The code of +F<.EXE> files is also shared by all the processes which use the particular +F<.EXE>, but they are "shared in the private address space of the process"; +this is possible because the address at which different sections +of the F<.EXE> file are loaded is decided at compile-time, thus all the +processes have these sections loaded at same addresses, and no fixup +of internal links inside the F<.EXE> is needed. + +Since DLLs may be loaded at run time, to have the same mechanism for for DLLs +one needs to have the address range of I DLLs in the +system to be available I which did not load a particular +DLL yet. This is why the DLLs are mapped to the shared memory region. + +=head2 Why chimera build? + +Current EMX environment does not allow DLLs compiled using Unixish +C format to export symbols for data (or at least some types of +data). This forces C-style compile of F. + +Current EMX environment does not allow F<.EXE> files compiled in +C format to fork(). fork() is needed for exactly three Perl +operations: + +=over 4 + +=item * + +explicit fork() in the script, + +=item * + +C + +=item * + +C, in other words, opening pipes to itself. + +=back + +While these operations are not questions of life and death, they are +needed for a lot of +useful scripts. This forces C-style compile of +F. + + +=head1 ENVIRONMENT + +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 EMX port. Should have the form + + path1;path2 + +or + + path1 path2 + +If the beginning of some prebuilt path matches F, it is +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. For example, 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 + +This will cause Perl with the prebuilt @INC of + + f:/perllib/lib/5.00553/os2 + f:/perllib/lib/5.00553 + f:/perllib/lib/site_perl/5.00553/os2 + f:/perllib/lib/site_perl/5.00553 + . + +to use the following @INC: + + h:/opt/gnu/5.00553/os2 + h:/opt/gnu/5.00553 + h:/opt/gnu/site_perl/5.00553/os2 + h:/opt/gnu/site_perl/5.00553 + . + +=head2 C + +If 0, perl ignores setlocale() failing. May be useful with some +strange Is. + +=head2 C + +If 0, perl would not warn of in case of unwarranted free(). With older +perls this might be +useful in conjunction with the module DB_File, which was buggy when +dynamically linked and OMF-built. + +Should not be set with newer Perls, since this may hide some I problems. + +=head2 C + +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 EMX port. Used as storage place for temporary files. + +=head1 Evolution + +Here we list major changes which could make you by surprise. + +=head2 Priorities + +C and C are not compatible with earlier +ports by Andreas Kaiser. See C<"setpriority, getpriority">. + +=head2 DLL name mangling + +With the release 5.003_01 the dynamically loadable libraries +should be rebuilt when a different version of Perl is compiled. In particular, +DLLs (including F) are now created with the names +which contain a checksum, thus allowing workaround for OS/2 scheme of +caching DLLs. + +It may be possible to code a simple workaround which would + +=over + +=item * + +find the old DLLs looking through the old @INC; + +=item * + +mangle the names according to the scheme of new perl and copy the DLLs to +these names; + +=item * + +edit the internal C tables of DLL to reflect the change of the name +(probably not needed for Perl extension DLLs, since the internally coded names +are not used for "specific" DLLs, they used only for "global" DLLs). + +=item * + +edit the internal C tables and change the name of the "old" +F to the "new" F. + +=back + +=head2 Threading + +As of release 5.003_01 perl is linked to multithreaded C RTL +DLL. If perl itself is not compiled multithread-enabled, so will not be perl's +malloc(). However, extensions may use multiple thread on their own +risk. + +This was needed to compile C for XFree86-OS/2 out-of-the-box, and +link with DLLs for other useful libraries, which typically are compiled +with C<-Zmt -Zcrtdll>. + +=head2 Calls to external programs + +Due to a popular demand the perl external program calling has been +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 path F above is set up automatically during +the build to a correct value on the builder machine, but is +overridable at runtime, + +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. This assures almost +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 pdksh calls external programs +via fork()/exec(), and there is I functioning exec() on +OS/2. exec() is emulated by EMX by an asynchronous call while the caller +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). + +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 thousands of your +scripts, the long-term solution proposed on p5-p is to have a directive + + use OS2::Cmd; + +which will override system(), exec(), C<``>, and +C. With current perl you may override only system(), +readpipe() - the explicit version of C<``>, and maybe exec(). The code +will substitute the one-argument call to system() by +C. + +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. Set us mention a couple +of features: + +=over 4 + +=item * + +External scripts may be called by their basename. Perl will try the same +extensions as when processing B<-S> command-line switch. + +=item * + +External scripts starting with C<#!> or C will be executed directly, +without calling the shell, by calling the program specified on the rest of +the first line. + +=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 quicker +than EMX one. I do not have convincing data about memory footprint, but +a (pretty random) benchmark showed that Perl's 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 4 + +=item C + +may have a race condition. Needs a reimplementation (in terms of chaining +waiting threads, with the linked 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 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 +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 (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 +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. At least two are available: tied access to EA's, and tied access +to system databases. - KSH_VERSION='@(#)PD KSH v5.2.4 96/01/17' - (Ilya's patched version.) +=head1 AUTHOR - `make --version` reports: 'GNU Make version 3.74' - (Ilya's patched version.) +Ilya Zakharevich, ilya@math.ohio-state.edu - `emxrev` reports: - EMX : revision = 42 - EMXIO : revision = 40 - EMXLIBC : revision = 40 - EMXLIBCM : revision = 43 - EMXLIBCS : revision = 43 - EMXWRAP : revision = 40 +=head1 SEE ALSO ------------------------------------------------------------------------------ +perl(1). -Rocco - +=cut