X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.os2;h=1e7464bb6742583182cd0f5f5997d39f6b459570;hb=188ff3c1f17467ccacb0b31f3e13fd49b5b438a7;hp=c0a19601f36306d9e135d582e656b4389c332d6f;hpb=aa6893958c2bfb6fa4ab923c8466c188c65748fd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/README.os2 b/README.os2 index c0a1960..1e7464b 100644 --- a/README.os2 +++ b/README.os2 @@ -31,6 +31,12 @@ 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 @@ -106,6 +112,7 @@ Contents - Threading - Calls to external programs - Memory allocation + - Threads AUTHOR SEE ALSO @@ -176,8 +183,8 @@ under earlier versions of EMX, but this is not tested. 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. @@ -202,14 +209,15 @@ can have Perl development environment under DOS. One can get RSX from, say - ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib + 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 at - ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip =item HPFS @@ -232,7 +240,7 @@ 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.exe + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip =back @@ -283,6 +291,9 @@ There are also endless possibilities to use I of *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 @@ -295,10 +306,86 @@ 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 @@ -650,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 @@ -713,10 +809,8 @@ Change to the directory of extraction. =head2 Application of the patches -You need to apply the patches in F<./os2/diff.*> and -F<./os2/POSIX.mkfifo> like this: +You need to apply the patches in F<./os2/diff.*> like this: - gnupatch -p0 < os2\POSIX.mkfifo gnupatch -p0 < os2\diff.configure You may also need to apply the patches supplied with the binary @@ -729,6 +823,22 @@ 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 @@ -764,55 +874,75 @@ 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 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/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay. +=item A lot of C + +in database tests related to Berkeley DB. This is a confirmed bug of +DB. You may disable this warnings, see L<"PERL_BADFREE">. + +There is not much we can do with it (but apparently it does not cause +any real error with data). + +=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. + +=back -Note that using `make test' target two more tests may fail: C -because of (mis)feature of pdksh, and C, which checks -that the buffers are not flushed on C<_exit> (this is a bug in the test -which assumes that tty output is buffered). +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. I submitted a patch to EMX which makes it possible to fork() with EMX -dynamic libraries loaded, which makes F tests pass. This means -that soon the number of failing tests may decrease yet more. +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. -However, the test F is disabled, since it never terminates, I -do not know why. Comments/fixes welcome. +To get finer test reports, call -The reasons for failed tests are: + perl t/harness -=over 8 +The report with F failing may look like this: -=item F + 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. -Checks I operations. Tests: +The reasons for most important skipped tests are: -=over 10 +=over 8 -=item 2-5, 7-11 +=item F -Check C and C - nonesuch under OS/2. +=over 4 =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 @@ -837,64 +967,24 @@ 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! +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). =back -=back +=item F -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 - -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 @@ -953,9 +1043,9 @@ You have a very old pdksh. See L. You do not have MT-safe F. See L. -=head2 Problems with tr +=head2 Problems with tr or sed -reported with very old version of tr. +reported with very old version of tr and sed. =head2 Some problem (forget which ;-) @@ -992,8 +1082,9 @@ 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. @@ -1006,7 +1097,7 @@ C, are included into my ftp directory, mirrored on CPAN. =item C -used by C, see L. +used by C, see L. =item C @@ -1045,7 +1136,7 @@ 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 @@ -1069,21 +1160,44 @@ eventually). =item -Since is present in EMX, but is not functional, the same is -true for perl. Here is the list of things which may be "broken" on +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): - - The functions recvmsg(), sendmsg(), and socketpair() are not - implemented. - - sock_init() is not required and not implemented. - - flock() is not yet implemented (dummy function). - - kill: - Special treatment of PID=0, PID=1 and PID=-1 is not implemented. - - waitpid: +=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 @@ -1124,6 +1238,12 @@ a dummy implementation. 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 @@ -1281,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 @@ -1299,6 +1423,12 @@ memory handling code is buggy. 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, most @@ -1323,7 +1453,7 @@ caching DLLs. =head2 Threading As of release 5.003_01 perl is linked to multithreaded CRT -DLL. Perl itself is not multithread-safe, as is not perl +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. @@ -1337,7 +1467,7 @@ 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, @@ -1351,7 +1481,7 @@ this works as well under DOS if you use DOS-enabled port of pdksh 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 +OS/2. exec() is emulated by EMX by 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 @@ -1379,17 +1509,25 @@ 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. -Unfortunately, it is also quite frivolous with memory usage as well. - -Since kitchen-top machines are usually low on memory, perl is compiled with -all the possible memory-saving options. This probably makes perl's -malloc() as greedy with memory as the neighbor's malloc(), but still -much quickier. Note that this is true only for a "typical" usage, -it is possible that the perl malloc will be worse for some very special usage. +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 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 @@ -1398,6 +1536,31 @@ 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