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
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</"F<perl_.exe>">.
Note that not all features of Perl are available under these
environments. This depends on the features the I<extender> - most
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</"Other OSes">). RSX would not work with VCPI
only, as EMX would, it requires DMPI.
Having RSX and the latest F<sh.exe> one gets a fully functional
pipes in between, and/or quoting of arguments), Perl uses an external
shell. With EMX port such shell should be named F<sh.exe>, and located
either in the wired-in-during-compile locations (usually F<F:/bin>),
-or in configurable location (see L<"PERL_SH_DIR">).
+or in configurable location (see L</"C<PERL_SH_DIR>">).
For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
under DOS (with L</RSX>) as well, see
perl ../../blah/foo.cmd arg1 arg2 arg3
(note that the argument C<-my_opts> is taken care of by the C<extproc> line
-in your script, see L<C<extproc> on the first line>).
+in your script, see L</C<extproc> on the first line>).
To understand what the above I<magic> does, read perl docs about C<-S>
switch - see L<perlrun>, and cmdref about C<extproc>:
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</"Pdksh">,
+L</"Frequently asked questions">), and perl should be able to find it
+(see L</"C<PERL_SH_DIR>">).
The cases when the shell is used are:
=item *
Did you run your programs with C<-w> switch? See
-L<Starting OSE<sol>2 (and DOS) programs under Perl>.
+L</Starting OSE<sol>2 (and DOS) programs under Perl>.
=item *
=head2 C<``> and pipe-C<open> 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</"I cannot run external programs">, or a
deeper problem. Basically: you I<need> RSX (see L</Prerequisites>)
for these commands to work, and you may need a port of F<sh.exe> which
understands command arguments. One of such ports is listed in
L</Prerequisites> under RSX. Do not forget to set variable
-C<L<"PERL_SH_DIR">> as well.
+L</"C<PERL_SH_DIR>"> as well.
DPMI is required for RSX.
=item C<PERL_BADLANG>
may be needed if you change your codepage I<after> 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</"C<PERL_BADLANG>">.
=item C<PERL_BADFREE>
-see L<"PERL_BADFREE">.
+see L</"C<PERL_BADFREE>">.
=item F<Config.pm>
B<NOTE>. Because of a typo the binary installer of 5.00305
would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
-remove this variable and put C<L</PERL_SH_DIR>> instead.
+remove this variable and put L</C<PERL_SH_DIR>> instead.
=head2 Manual binary installation
into F<perl.exe>, you do not need to change
anything. However, for perl to find the library if you use a different
path, you need to
-C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
+C<set PERLLIB_PREFIX> in F<Config.sys>, see L</"C<PERLLIB_PREFIX>">.
=item Additional Perl modules
- unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.19.10/
+ 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<PERLLIB_PREFIX>), you
require shell, like the commands using I<redirection> and I<shell
metacharacters>. It is also used instead of explicit F</bin/sh>.
-Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
+Set C<PERL_SH_DIR> (see L</"C<PERL_SH_DIR>">) if you move F<sh.exe> from
the above location.
B<Note.> It may be possible to use some other sh-compatible shell (untested).
=head2 B<Warning>
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</"C<PERLLIB_PREFIX>">, L</"C<PERL_SH_DIR>">), some people may prefer
binary editing of paths inside the executables/DLLs.
=head1 Accessing documentation
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</"SYNOPSIS">.
If you want to build the docs yourself, and have I<OS/2 toolkit>, run
of the build may fail since an older version of F<perl.dll> loaded into
memory may be found. Running C<make test> becomes meaningless, since
the test are checking a previous build of perl (this situation is detected
-and reported by F<lib/os2_base.t> test). Do not forget to unset
+and reported by F<os2/os2_base.t> test). Do not forget to unset
C<PERL_EMXLOAD_SEC> in environment.
Also make sure that you have F</tmp> directory on the current drive,
C<prefix> means: where to install the resulting perl library. Giving
correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
-see L<"PERLLIB_PREFIX">.
+see L</"C<PERLLIB_PREFIX>">.
I<Ignore the message about missing C<ln>, and about C<-c> option to
tr>. The latter is most probably already fixed, if you see it and can trace
=item A lot of C<bad free>
in database tests related to Berkeley DB. I<This should be fixed already.>
-If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
+If it persists, you may disable this warnings, see L</"C<PERL_BADFREE>">.
=item Process terminated by SIGTERM/SIGINT
The report with F<io/pipe.t> 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:
=head2 C<a.out>-style build
-Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
+Proceed as above, but make F<perl_.exe> (see L</"F<perl_.exe>">) by
make perl_
Install the bundle C<Bundle::OS2_default>
- 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.
a new executable per XS extension.
Here is a possible workaround: create a toplevel F<Makefile.PL> in
-F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
+F<$CPANHOME/.cpan/build/> with contents being (compare with L</Making
executables with a custom collection of statically loaded extensions>)
use ExtUtils::MakeMaker;
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<make> to speed up
to ignore the environment when setting the Perl-library search patch, etc.
If you fill comfortable with I<embedding> interface (see L<perlembed>), such
-things are easy to do repeating the steps outlined in L<Making
+things are easy to do repeating the steps outlined in L/<Making
executables with a custom collection of statically loaded extensions>, and
doing more comprehensive edits to main() of F<perlmain.c>. The people with
little desire to understand Perl can just rename main(), and do necessary
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 <os2.h>
-
- #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 <os2.h>
+
+ #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
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</bin/sh> Perl uses
-the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
+the hardwired-or-customized shell (see L</"C<PERL_SH_DIR>">).
The above search for "interpreter" is recursive: if F<bash> executable is not
found, but F<bash.btm> is found, Perl will investigate its first line etc.
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</"Centralized management of resources"> for additional details.
=item C<OS2::Serve_Messages(force)>
handling exception mask: if no C<mask>, uses exception mask part of C<new>
only. If no C<new>, disables all the floating point exceptions.
-See L<"Misfeatures"> for details.
+See L</"Misfeatures"> for details.
=item C<OS2::DLLname([how [, \&xsub]])>
=item *
-See L<"Text-mode filehandles">.
+See L</"Text-mode filehandles">.
=item *
=item C<popen>
-C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
+C<my_popen> uses F<sh.exe> if shell is required, cf. L</"C<PERL_SH_DIR>">.
=item C<tmpnam>
- and also C<PMWIN_entries> - in F<os2ish.h>). 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.
I<This is the only executable with does not require OS/2.> The
friends locked into C<M$> 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</"Other OSes">.
=head2 F<perl__.exe>
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).
Due to a popular demand the perl external program calling has been
changed wrt Andreas Kaiser's port. I<If> perl needs to call an
external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
-whatever is the override, see L<"PERL_SH_DIR">.
+whatever is the override, see L</"C<PERL_SH_DIR>">.
Thus means that you need to get some copy of a F<sh.exe> as well (I
use one from pdksh). The path F<F:/bin> above is set up automatically during
cannot test it.
For the details of the current situation with calling external programs,
-see L<Starting OSE<sol>2 (and DOS) programs under Perl>. Set us mention a couple
-of features:
+see L</Starting OSE<sol>2 (and DOS) programs under Perl>. Set us
+mention a couple of features:
=over 4
Note that OS2 perl defines 2 pseudo-extension functions
OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
-L<Prebuilt methods>).
+L</Prebuilt methods>).
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
https://perl5.git.perl.org / perl5.git / blobdiff