X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/430812d753cb6126658aa5764d72c857935e7552..ae955d3a183337a4770d39640a21da146cf97bc7:/README.os2 diff --git a/README.os2 b/README.os2 index b0b2993..1423957 100644 --- a/README.os2 +++ b/README.os2 @@ -41,7 +41,7 @@ in EMX docs). Contents (This may be a little bit obsolete) - perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. + perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. NAME SYNOPSIS @@ -180,7 +180,7 @@ 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">. +only one works, see L">. Note that not all features of Perl are available under these environments. This depends on the features the I - most @@ -224,7 +224,7 @@ will work as well.) 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 +L). RSX would not work with VCPI only, as EMX would, it requires DMPI. Having RSX and the latest F one gets a fully functional @@ -261,7 +261,7 @@ 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">). +or in configurable location (see L">). For best results use EMX pdksh. The standard binary (5.2.14 or later) runs under DOS (with L) as well, see @@ -300,7 +300,7 @@ 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>). +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: @@ -328,9 +328,9 @@ 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">). +sh-syntax shell installed (see L, +L), and perl should be able to find it +(see L">). The cases when the shell is used are: @@ -436,7 +436,7 @@ managed to goof. C<;-)> =item * Did you run your programs with C<-w> switch? See -L2 (and DOS) programs under Perl>. +L2 (and DOS) programs under Perl>. =item * @@ -475,12 +475,12 @@ should be done "correctly". =head2 C<``> and pipe-C do not work under DOS. -This may a variant of just L<"I cannot run external programs">, or a +This may a variant of just L, or a deeper problem. Basically: you I RSX (see L) 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 under RSX. Do not forget to set variable -C> as well. +L"> as well. DPMI is required for RSX. @@ -535,11 +535,11 @@ B =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">. +and the new value is not supported by EMX. See L">. =item C -see L<"PERL_BADFREE">. +see L">. =item F @@ -558,7 +558,7 @@ of this file. 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. +remove this variable and put L> instead. =head2 Manual binary installation @@ -615,11 +615,11 @@ 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">. +C in F, see L">. =item Additional Perl modules - unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.23.2/ + unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.33.1/ Same remark as above applies. Additionally, if this directory is not one of directories on @INC (and @INC is influenced by C), you @@ -675,7 +675,7 @@ 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 +Set C (see L">) if you move F from the above location. B It may be possible to use some other sh-compatible shell (untested). @@ -695,8 +695,8 @@ 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">), some people may prefer +inside perl executables. While these paths are overwritable (see +L">, L">), some people may prefer binary editing of paths inside the executables/DLLs. =head1 Accessing documentation @@ -714,7 +714,7 @@ Most probably the most convenient form. Under OS/2 view it as view perl ExtUtils::MakeMaker (currently the last two may hit a wrong location, but this may improve -soon). Under Win* see L<"SYNOPSIS">. +soon). Under Win* see L. If you want to build the docs yourself, and have I, run @@ -870,7 +870,7 @@ 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. Running C becomes meaningless, since the test are checking a previous build of perl (this situation is detected -and reported by F test). Do not forget to unset +and reported by F test). Do not forget to unset C in environment. Also make sure that you have F directory on the current drive, @@ -948,7 +948,7 @@ wrong you find there. I do not expect it is needed anywhere. C means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify C, -see L<"PERLLIB_PREFIX">. +see L">. I, and about C<-c> option to tr>. The latter is most probably already fixed, if you see it and can trace @@ -982,7 +982,7 @@ Some tests may generate extra messages similar to =item A lot of C in database tests related to Berkeley DB. I -If it persists, you may disable this warnings, see L<"PERL_BADFREE">. +If it persists, you may disable this warnings, see L">. =item Process terminated by SIGTERM/SIGINT @@ -1002,11 +1002,12 @@ To get finer test reports, call The report with F failing may look like this: - Failed Test Status Wstat Total Fail Failed List of failed - ------------------------------------------------------------ - io/pipe.t 12 1 8.33% 9 - 7 tests skipped, plus 56 subtests skipped. - Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay. + Failed Test Status Wstat Total Fail Failed List of failed + ------------------------------------------------------------ + io/pipe.t 12 1 8.33% 9 + 7 tests skipped, plus 56 subtests skipped. + Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, + 99.98% okay. The reasons for most important skipped tests are: @@ -1072,7 +1073,7 @@ making steps.) =head2 C-style build -Proceed as above, but make F (see L<"perl_.exe">) by +Proceed as above, but make F (see L">) by make perl_ @@ -1132,15 +1133,15 @@ to manually install C. Install the bundle C - perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1 + perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1 This may take a couple of hours on 1GHz processor (when run the first time). And this should not be necessarily a smooth procedure. Some modules may not specify required dependencies, so one may need to repeat this procedure several times until the results stabilize. - perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2 - perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3 + perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2 + perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3 Even after they stabilize, some tests may fail. @@ -1194,7 +1195,7 @@ via C is going to be painfully slow, since it statically links a new executable per XS extension. Here is a possible workaround: create a toplevel F in -F<$CPANHOME/.cpan/build/> with contents being (compare with L with contents being (compare with L) use ExtUtils::MakeMaker; @@ -1224,7 +1225,7 @@ necessary external C libraries from F<.lib> format to F<.a> format: run one of emximp -o foo.a foo.lib whichever is appropriate.) Also, make sure that the DLLs for external -libraries are usable with with executables compiled without C<-Zmtd> options. +libraries are usable with executables compiled without C<-Zmtd> options. When you are sure that only a few subdirectories lead to failures, you may want to add C<-j4> option to C to speed up @@ -1366,7 +1367,7 @@ to find Perl DLL relatively to the location of the EXE file; or one may want to ignore the environment when setting the Perl-library search patch, etc. If you fill comfortable with I interface (see L), such -things are easy to do repeating the steps outlined in L, and doing more comprehensive edits to main() of F. The people with little desire to understand Perl can just rename main(), and do necessary @@ -1415,109 +1416,134 @@ an EMX applications, e.g., if compiled with Here is the sample C file: - #define INCL_DOS - #define INCL_NOPM - /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */ - #define INCL_DOSPROCESS - #include - - #include "EXTERN.h" - #define PERL_IN_MINIPERLMAIN_C - #include "perl.h" - - static char *me; - HMODULE handle; - - static void - die_with(char *msg1, char *msg2, char *msg3, char *msg4) - { - ULONG c; - char *s = " error: "; - - DosWrite(2, me, strlen(me), &c); - DosWrite(2, s, strlen(s), &c); - DosWrite(2, msg1, strlen(msg1), &c); - DosWrite(2, msg2, strlen(msg2), &c); - DosWrite(2, msg3, strlen(msg3), &c); - DosWrite(2, msg4, strlen(msg4), &c); - DosWrite(2, "\r\n", 2, &c); - exit(255); - } - - typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg); - typedef int (*main_t)(int type, char *argv[], char *env[]); - typedef int (*handler_t)(void* data, int which); - - #ifndef PERL_DLL_BASENAME - # define PERL_DLL_BASENAME "perl" - #endif - - static HMODULE - load_perl_dll(char *basename) - { - char buf[300], fail[260]; - STRLEN l, dirl; - fill_extLibpath_t f; - ULONG rc_fullname; - HMODULE handle, handle1; - - if (_execname(buf, sizeof(buf) - 13) != 0) - die_with("Can't find full path: ", strerror(errno), "", ""); - /* XXXX Fill 'me' with new value */ - l = strlen(buf); - while (l && buf[l-1] != '/' && buf[l-1] != '\\') - l--; - dirl = l - 1; - strcpy(buf + l, basename); - l += strlen(basename); - strcpy(buf + l, ".dll"); - if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0 - && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 ) - die_with("Can't load DLL ", buf, "", ""); - if (rc_fullname) - return handle; /* was loaded with short name; all is fine */ - if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f)) - die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", ""); - buf[dirl] = 0; - if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */, - 0 /* keep old value */, me)) - die_with(me, ": prepending BEGINLIBPATH", "", ""); - if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0) - die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", ""); - buf[dirl] = '\\'; - if (handle1 != handle) { - if (DosQueryModuleName(handle1, sizeof(fail), fail)) - strcpy(fail, "???"); - die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t", - fail, - "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT" - "\n\tso that the other copy is loaded via BEGINLIBPATH."); - } - return handle; - } - - int - main(int argc, char **argv, char **env) - { - main_t f; - handler_t h; - - me = argv[0]; - /**/ - handle = load_perl_dll(PERL_DLL_BASENAME); - - if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h)) - die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", ""); - if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from) - || !h((void *)"~dll", Perlos2_handler_perllib_to) - || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) ) - die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", ""); - - if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f)) - die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", ""); - return f(argc, argv, env); - } - + #define INCL_DOS + #define INCL_NOPM + /* These are needed for compile if os2.h includes os2tk.h, not + * os2emx.h */ + #define INCL_DOSPROCESS + #include + + #include "EXTERN.h" + #define PERL_IN_MINIPERLMAIN_C + #include "perl.h" + + static char *me; + HMODULE handle; + + static void + die_with(char *msg1, char *msg2, char *msg3, char *msg4) + { + ULONG c; + char *s = " error: "; + + DosWrite(2, me, strlen(me), &c); + DosWrite(2, s, strlen(s), &c); + DosWrite(2, msg1, strlen(msg1), &c); + DosWrite(2, msg2, strlen(msg2), &c); + DosWrite(2, msg3, strlen(msg3), &c); + DosWrite(2, msg4, strlen(msg4), &c); + DosWrite(2, "\r\n", 2, &c); + exit(255); + } + + typedef ULONG (*fill_extLibpath_t)(int type, + char *pre, + char *post, + int replace, + char *msg); + typedef int (*main_t)(int type, char *argv[], char *env[]); + typedef int (*handler_t)(void* data, int which); + + #ifndef PERL_DLL_BASENAME + # define PERL_DLL_BASENAME "perl" + #endif + + static HMODULE + load_perl_dll(char *basename) + { + char buf[300], fail[260]; + STRLEN l, dirl; + fill_extLibpath_t f; + ULONG rc_fullname; + HMODULE handle, handle1; + + if (_execname(buf, sizeof(buf) - 13) != 0) + die_with("Can't find full path: ", strerror(errno), "", ""); + /* XXXX Fill 'me' with new value */ + l = strlen(buf); + while (l && buf[l-1] != '/' && buf[l-1] != '\\') + l--; + dirl = l - 1; + strcpy(buf + l, basename); + l += strlen(basename); + strcpy(buf + l, ".dll"); + if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) + != 0 + && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 ) + die_with("Can't load DLL ", buf, "", ""); + if (rc_fullname) + return handle; /* was loaded with short name; all is fine */ + if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f)) + die_with(buf, + ": DLL exports no symbol ", + "fill_extLibpath", + ""); + buf[dirl] = 0; + if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */, + 0 /* keep old value */, me)) + die_with(me, ": prepending BEGINLIBPATH", "", ""); + if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0) + die_with(me, + ": finding perl DLL again via BEGINLIBPATH", + "", + ""); + buf[dirl] = '\\'; + if (handle1 != handle) { + if (DosQueryModuleName(handle1, sizeof(fail), fail)) + strcpy(fail, "???"); + die_with(buf, + ":\n\tperl DLL via BEGINLIBPATH is different: \n\t", + fail, + "\n\tYou may need to manipulate global BEGINLIBPATH" + " and LIBPATHSTRICT" + "\n\tso that the other copy is loaded via" + BEGINLIBPATH."); + } + return handle; + } + + int + main(int argc, char **argv, char **env) + { + main_t f; + handler_t h; + + me = argv[0]; + /**/ + handle = load_perl_dll(PERL_DLL_BASENAME); + + if (DosQueryProcAddr(handle, + 0, + "Perl_OS2_handler_install", + (PFN*)&h)) + die_with(PERL_DLL_BASENAME, + ": DLL exports no symbol ", + "Perl_OS2_handler_install", + ""); + if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from) + || !h((void *)"~dll", Perlos2_handler_perllib_to) + || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) ) + die_with(PERL_DLL_BASENAME, + ": Can't install @INC manglers", + "", + ""); + if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f)) + die_with(PERL_DLL_BASENAME, + ": DLL exports no symbol ", + "dll_perlmain", + ""); + return f(argc, argv, env); + } =head1 Build FAQ @@ -1593,7 +1619,7 @@ 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 hardwired-or-customized shell (see L">). The above search for "interpreter" is recursive: if F executable is not found, but F is found, Perl will investigate its first line etc. @@ -1738,7 +1764,7 @@ 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. +See L for additional details. =item C @@ -1775,7 +1801,7 @@ 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. +See L for details. =item C @@ -1873,7 +1899,7 @@ Note that C does not work with the current version of EMX. =item * -See L<"Text-mode filehandles">. +See L. =item * @@ -1932,7 +1958,7 @@ Perl modifies some standard C library calls in the following ways: =item C -C uses F if shell is required, cf. L<"PERL_SH_DIR">. +C uses F if shell is required, cf. L">. =item C @@ -2124,12 +2150,12 @@ points available for such linking is provided (see C - and also C - in F). These ordinals can be accessed via the APIs: - CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(), - DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(), - DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(), - DeclWinFuncByORD_CACHE_resetError_survive(), - DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(), - DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive() + CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(), + DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(), + DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(), + DeclWinFuncByORD_CACHE_resetError_survive(), + DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(), + DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive() See the header files and the C code in the supplied OS/2-related modules for the details on usage of these functions. @@ -2168,7 +2194,7 @@ 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">. +appropriate extender. See L. =head2 F @@ -2567,7 +2593,8 @@ F with modifying the versions/names as needed. Run - perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst + perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") + if /\"(\w+)\"/" perl5.def >lst in the Perl build directory (to make the DLL smaller replace perl5.def with the definition file for the older version of Perl if present). @@ -2593,7 +2620,7 @@ with C<-Zmt -Zcrtdll>. 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">. +whatever is the override, see L">. 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 @@ -2639,8 +2666,8 @@ 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 L2 (and DOS) programs under Perl>. Set us mention a couple -of features: +see L2 (and DOS) programs under Perl>. Set us +mention a couple of features: =over 4 @@ -2716,7 +2743,7 @@ 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). +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