From 833d3f255ed68b969f062cec63d33f853ed9237c Mon Sep 17 00:00:00 2001 From: Ilya Zakharevich Date: Thu, 20 Feb 1997 19:24:16 -0500 Subject: Re: OS/2 patch for _27 The bulk of this patch is README.os2 which has a lot of formatting stripped (it is at the end). The rest (340 lines of -u) is quite simple. INSTALL t/harness documented. lib/Test/Harness.pm Can test files with -T on hash-bang line. Gets more info from tests which coredump. Will not try to load Devel::CoreStack on each test. os2/Changes Updated. os2/OS2/PrfDB/t/os2_prfdb.t File closed. os2/os2.c Poor-man's setup of environment if DLL run from non-conforming EXE. os2/os2ish.h Poor-man's setup of environment if DLL run from non-conforming EXE. ALTERNATE_SHEBANG defined. os2/perl2cmd.pl Updated for ALTERNATE_SHEBANG. perl.c If ALTERNATE_SHEBANG defined, just ignore -S on the starting line. (It might be already used by OS to start perl.) pod/perldelta.pod Malloc's PERL_DEBUG_MSTATS, EMERGENCY_SBR, PACK_MALLOC, TWO_POT_OPTIMIZE documented. t/harness Does not require -I../lib any more. t/op/magic.t Now works under OS/2 with both tests. t/TEST Adds an advice to use perl harness to get better granularity. README.os2 A lot of markup stripped (in the hope that smart converters will add it back), minor updates. p5p-msgid: <199702210024.TAA03174@monk.mps.ohio-state.edu> --- INSTALL | 8 ++ README.os2 | 305 +++++++++++++++++++++++++------------------- lib/Test/Harness.pm | 34 ++++- os2/Changes | 10 ++ os2/OS2/PrfDB/t/os2_prfdb.t | 2 + os2/os2.c | 5 +- os2/os2ish.h | 8 +- os2/perl2cmd.pl | 2 +- perl.c | 4 + pod/perldelta.pod | 56 +++++++- t/TEST | 7 + t/harness | 5 +- t/op/magic.t | 9 +- 13 files changed, 304 insertions(+), 151 deletions(-) diff --git a/INSTALL b/INSTALL index 156fdd90ed..a74afdb66f 100644 --- a/INSTALL +++ b/INSTALL @@ -913,6 +913,14 @@ bomb, you can run them by hand, e.g., ./perl op/groups.t +Another way to get more detailed information about failed tests and +individual subtests is to B to the F directory and run + + ./perl harness + +(this assumes that I tests succeed, since F uses +complicated constructs). + You can also read the individual tests to see if there are any helpful comments that apply to your system. diff --git a/README.os2 b/README.os2 index e6782e3dc1..c0a19601f3 100644 --- a/README.os2 +++ b/README.os2 @@ -27,9 +27,9 @@ 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 B's +in F. This gives one an access to EMX's F<.INF> docs as well (text form is available in F in -B's distribution). +EMX's distribution). =cut @@ -43,12 +43,13 @@ Contents - Target - Other OSes - Prerequisites - - Starting Perl programs under OS/2 - - Starting OS/2 programs under Perl + - 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 @@ -77,9 +78,10 @@ Contents - Some problem (forget which ;-) - Library ... not found - Segfault in make - Specific (mis)features of OS/2 port + Specific (mis)features of EMX port - setpriority, getpriority - system() + - extproc on the first line - Additional modules: - Prebuilt methods: - Misfeatures @@ -113,7 +115,8 @@ Contents 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. +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: @@ -131,10 +134,10 @@ to use PM code in your application (like the forthcoming Perl/Tk). =item * -There is no simple way to access B objects. The only way I know +There is no simple way to access WPS objects. The only way I know is via C extension (see L), and we do not have access to -convenience methods of B. (Is it possible at all? I know -of no B API.) +convenience methods of Object-REXX. (Is it possible at all? I know +of no Object-REXX API.) =back @@ -142,7 +145,7 @@ Please keep this list up-to-date by informing me about other items. =head2 Other OSes -Since OS/2 port of perl uses a remarkable B environment, it can +Since OS/2 port of perl uses a remarkable EMX environment, it can run (and build extensions, and - possibly - be build itself) under any environment which can run EMX. The current list is DOS, DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, @@ -150,7 +153,7 @@ only one works, see L<"perl_.exe">. Note that not all features of Perl are available under these environments. This depends on the features the I - most -probably C - decided to implement. +probably RSX - decided to implement. Cf. L. @@ -158,19 +161,20 @@ Cf. L. =over 6 -=item B +=item EMX -B runtime is required (may be substituted by B). Note that +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 B runtime, which +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 B is required if there is no C present. Note the -B requires C. +fact RSX is required if there is no VCPI present. Note the +RSX requires DPMI. -Only the latest runtime is supported, currently C<0.9c>. +Only the latest runtime is supported, currently C<0.9c>. Perl may run +under earlier versions of EMX, but this is not tested. -One can get different parts of B from, say +One can get different parts of EMX from, say ftp://ftp.cdrom.com/pub/os2/emx0.9c/ ftp://hobbes.nmsu.edu/os2/unix/gnu/ @@ -184,19 +188,19 @@ does not need to specify them explicitly (though this will work as well.) -=item B +=item RSX -To run Perl on C platforms one needs B runtime. This is +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">). B would not work with C -only, as B would, it requires C. +L<"Other OSes">). RSX would not work with VCPI +only, as EMX would, it requires DMPI. -Having B and the latest F one gets a fully functional +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 B from, say +One can get RSX from, say ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc @@ -207,18 +211,32 @@ The latest F with DOS hooks is available at ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe -=item B +=item HPFS Perl does not care about file systems, but to install the whole perl library intact one needs a file system which supports long file names. Note that if you do not plan to build the perl itself, it may be -possible to fool B to truncate file names. This is not supported, -read B docs to see how to do it. +possible to fool EMX to truncate file names. This is not supported, +read EMX docs to see how to do it. + +=item pdksh + +To start external programs with complicated command lines (like with +pipes in between, and/or quoting of arguments), Perl uses an external +shell. With EMX port such shell should be named , and located +either in the wired-in-during-compile locations (usually F), +or in configurable location (see L<"PERL_SH_DIR">). + +For best results use EMX pdksh. The soon-to-be-available standard +binary (5.2.12?) runs under DOS (with L) as well, meanwhile use +the binary from + + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe =back -=head2 Starting Perl programs under OS/2 +=head2 Starting Perl programs under OS/2 (and DOS and...) Start your Perl program F with arguments C the same way as on any other platform, by @@ -230,33 +248,28 @@ opposed to to your program), use perl -my_opts foo.pl arg1 arg2 arg3 -Alternately, if you use OS/2-ish shell, like C or C<4os2>, put +Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the following at the start of your perl script: - extproc perl -x -S - #!/usr/bin/perl -my_opts + extproc perl -S -my_opts rename your program to F, and start it by typing foo arg1 arg2 arg3 -(Note that having *nixish full path to perl F is not -necessary, F would be enough, but having full path would make it -easier to use your script under *nix.) - Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use C, thus you are forced to use C<-S> perl switch, and your script should be on path. As a plus side, if you know a full path to your script, you may still start it with - perl -x ../../blah/foo.cmd arg1 arg2 arg3 + perl ../../blah/foo.cmd arg1 arg2 arg3 -(note that the argument C<-my_opts> is taken care of by the C<#!> line -in your script). +(note that the argument C<-my_opts> is taken care of by the C line +in your script, see L on the first line>). To understand what the above I does, read perl docs about C<-S> -and C<-x> switches - see L, and cmdref about C: +switch - see L, and cmdref about C: view perl perlrun man perlrun @@ -266,11 +279,11 @@ and C<-x> switches - see L, and cmdref about C: or whatever method you prefer. There are also endless possibilities to use I of -B<4OS2>, I of B and so on... However, if you use +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. -=head2 Starting OS/2 programs under Perl +=head2 Starting OS/2 (and DOS) programs under Perl This is what system() (see L), C<``> (see L), and I (see L) @@ -278,7 +291,7 @@ are for. (Avoid exec() (see L) unless you know what you do). Note however that to use some of these operators you need to have a -C-syntax shell installed (see L<"Pdksh">, +sh-syntax shell installed (see L<"Pdksh">, L<"Frequently asked questions">), and perl should be able to find it (see L<"PERL_SH_DIR">). @@ -296,7 +309,7 @@ meta-characters. =item Did you run your programs with C<-w> switch? See -L. +L. =item @@ -312,12 +325,12 @@ program. =over 4 -=item Is your program B-compiled with C<-Zmt -Zcrtdll>? +=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>? If not, you need to build a stand-alone DLL for perl. Contact me, I did it once. Sockets would not work, as a lot of other stuff. -=item Did you use C? +=item Did you use L? I had reports it does not work. Somebody would need to fix it. @@ -326,12 +339,29 @@ I had reports it does not work. Somebody would need to fix it. =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 B (see L<"Prerequisites">) +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 B. +L<"Prerequisites"> under RSX. Do not forget to set variable +C> as well. + +DPMI is required for RSX. + +=head2 Cannot start C -C is required for B. +Use one of + + system 'cmd', '/c', 'find "pattern" file'; + `cmd /c 'find "pattern" file'` + +This would start F via F via C via +C, but this is a price to pay if you want to use +non-conforming program. In fact F cannot be started at all +using C library API only. Otherwise the following command-lines were +equivalent: + + find "pattern" file + find pattern file =head1 INSTALLATION @@ -342,9 +372,9 @@ F. Just follow the instructions, and 99% of the installation blues would go away. Note however, that you need to have F on your path, and -B environment I. The latter means that if you just -installed B, and made all the needed changes to F, -you may need to reboot in between. Check B runtime by running +EMX environment I. The latter means that if you just +installed EMX, and made all the needed changes to F, +you may need to reboot in between. Check EMX runtime by running emxrev @@ -358,7 +388,7 @@ B =item C may be needed if you change your codepage I perl installation, -and the new value is not supported by B. See L<"PERL_BADLANG">. +and the new value is not supported by EMX. See L<"PERL_BADLANG">. =item C @@ -377,19 +407,23 @@ 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 C files are not absolute, but +installation, the file paths in the zip files are not absolute, but relative to some directory. Note that the extraction with the stored paths is still necessary -(default with C, specify C<-d> to C). However, you +(default with unzip, specify C<-d> to pkunzip). However, you need to know where to extract the files. You need also to manually change entries in F to reflect where did you put the files. Note that if you have some primitive unzipper (like -C), you may get a lot of warnings/errors during +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 @@ -402,20 +436,20 @@ machine: unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin unzip perl_exc.zip *.dll -d f:/emx.add/dll -(have the directories with C<*.exe> on C, and C<*.dll> on -C); +(have the directories with C<*.exe> on PATH, and C<*.dll> on +LIBPATH); =item Perl_ VIO executable (statically linked) unzip perl_aou.zip -d f:/emx.add/bin -(have the directory on C); +(have the directory on PATH); =item Executables for Perl utilities unzip perl_utl.zip -d f:/emx.add/bin -(have the directory on C); +(have the directory on PATH); =item Main Perl library @@ -447,25 +481,25 @@ C in F, see L<"PERLLIB_PREFIX">. unzip perl_man.zip -d f:/perllib/man This directory should better be on C. You need to have a -working C to access these files. +working man to access these files. =item Manpages for Perl modules unzip perl_mam.zip -d f:/perllib/man This directory should better be on C. You need to have a -working C to access these files. +working man to access these files. =item Source for Perl documentation unzip perl_pod.zip -d f:/perllib/lib This is used by by C program (see L), and may be used to -generate B documentation usable by WWW browsers, and +generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: C, C, C, C and so on. -=item Perl manual in .INF format +=item Perl manual in F<.INF> format unzip perl_inf.zip -d d:/os2/book @@ -482,7 +516,7 @@ metacharacters>. It is also used instead of explicit F. Set C (see L<"PERL_SH_DIR">) if you move F from the above location. -B It may be possible to use some other C-compatible shell +B It may be possible to use some other sh-compatible shell (I). =back @@ -511,7 +545,7 @@ identical) Perl documentation in the following formats: =head2 OS/2 F<.INF> file -Most probably the most convenient form. View it as +Most probably the most convenient form. Under OS/2 view it as view perl view perl perlfunc @@ -519,7 +553,7 @@ Most probably the most convenient form. View it as view perl ExtUtils::MakeMaker (currently the last two may hit a wrong location, but this may improve -soon). +soon). Under Win* see L<"SYNOPSIS">. If you want to build the docs yourself, and have I, run @@ -535,7 +569,7 @@ BOOKSHELF path. =head2 Plain text If you have perl documentation in the source form, perl utilities -installed, and B C installed, you may use +installed, and GNU groff installed, you may use perldoc perlfunc perldoc less @@ -548,7 +582,7 @@ Alternately, try running pod2text on F<.pod> files. =head2 Manpages -If you have C installed on your system, and you installed perl +If you have man installed on your system, and you installed perl manpages, use something like this: man perlfunc @@ -568,11 +602,11 @@ on our C, like this set MANPATH=c:/man;f:/perllib/man -=head2 B +=head2 HTML If you have some WWW browser available, installed the Perl documentation in the source form, and Perl utilities, you can build -B docs. Cd to directory with F<.pod> files, and do like this +HTML docs. Cd to directory with F<.pod> files, and do like this cd f:/perllib/lib/pod pod2html @@ -582,11 +616,11 @@ directory, and go ahead with reading docs, like this: explore file:///f:/perllib/lib/pod/perl.html -Alternatively you may be able to get these docs prebuilt from C. +Alternatively you may be able to get these docs prebuilt from CPAN. -=head2 B C files +=head2 GNU C files -Users of C would appreciate it very much, especially with +Users of Emacs would appreciate it very much, especially with C mode loaded. You need to get latest C from C, or, alternately, prebuilt info pages. @@ -606,8 +640,8 @@ Here we discuss how to build Perl under OS/2. There is an alternative =head2 Prerequisites -You need to have the latest B development environment, the full -B tool suite (C renamed to C, and B F +You need to have the latest EMX development environment, the full +GNU tool suite (gawk renamed to awk, and GNU F earlier on path than the OS/2 F, same with F, to check use @@ -636,17 +670,17 @@ latter condition by if you use something like F or latest versions of F<4os2.exe>. -Make sure your C is good for C<-Zomf> linking: run C +Make sure your gcc is good for C<-Zomf> linking: run C script in F directory. -Check that you have C installed. It comes standard with OS/2, +Check that you have link386 installed. It comes standard with OS/2, but may be not installed due to customization. If typing link386 shows you do not have it, do I, and choose C in I. If you get into -C, press C. +link386, press C. =head2 Getting perl source @@ -675,10 +709,6 @@ Extract it like this You may see a message about errors while extracting F. This is because there is a conflict with a similarly-named file F. -Rename F to F. Extract F like this - - tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure - Change to the directory of extraction. =head2 Application of the patches @@ -692,10 +722,10 @@ F<./os2/POSIX.mkfifo> like this: You may also need to apply the patches supplied with the binary distribution of perl. -Note also that the F and F from the B distribution +Note also that the F and F from the EMX distribution are not suitable for multi-threaded compile (note that currently perl -is not multithreaded, but is compiled as multithreaded for -compatibility with B-OS/2). Get a corrected one from +is not multithread-safe, but is compiled as multithreaded for +compatibility with XFree86-OS/2). Get a corrected one from ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip @@ -708,12 +738,12 @@ wrong you find there. I do not expect it is needed anywhere. sh Configure -des -D prefix=f:/perllib -Prefix means where to install the resulting perl library. Giving +C means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify C, see L<"PERLLIB_PREFIX">. I, and about C<-c> option to -C>. In fact if you can trace where the latter spurious warning +tr>. In fact if you can trace where the latter spurious warning comes from, please inform me. Now @@ -723,9 +753,11 @@ Now At some moment the built may die, reporting a I or I>. This means that most of the build has been finished, and it is the time to move the constructed F to -some I location in C. After this done the build -should finish without a lot of fuss. I on C.> +some I location in LIBPATH. After this is done the build +should finish without a lot of fuss. I on LIBPATH, but +probably this is not needed anymore, since F is linked +statically now.> Warnings which are safe to ignore: I inside F. @@ -740,7 +772,7 @@ Some tests (4..6) should fail. Some perl invocations should end in a segfault (system error C). To get finer error reports, cd t - perl -I ../lib harness + perl harness The report you get may look like @@ -753,11 +785,11 @@ The report you get may look like Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay. Note that using `make test' target two more tests may fail: C -because of (mis)feature of C, and C, which checks +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). -I submitted a patch to B which makes it possible to fork() with EMX +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. @@ -791,12 +823,12 @@ know why this should or should not work. =item F -Checks C module. Some feature of B - test fork()s with +Checks C module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F -Checks C module. Some feature of B - test fork()s +Checks C module. Some feature of EMX - test fork()s with dynamic extension loaded - unsupported now. =item F @@ -869,14 +901,14 @@ Run It would put the generated files into needed locations. Manually put F, F and F to a location on your -C, F to a location on your C. +PATH, F to a location on your LIBPATH. Run make cmdscripts INSTALLCMDDIR=d:/ir/on/path to convert perl utilities to F<.cmd> files and put them on -C. You need to put F<.EXE>-utilities on path manually. They are +PATH. You need to put F<.EXE>-utilities on path manually. They are installed in C<$prefix/bin>, here C<$prefix> is what you gave to F, see L. @@ -891,7 +923,7 @@ test and install by make aout_test make aout_install -Manually put F to a location on your C. +Manually put F to a location on your PATH. Since C has the extensions prebuilt, it does not suffer from the I syndrome, thus the failing tests @@ -921,13 +953,13 @@ You have a very old pdksh. See L. You do not have MT-safe F. See L. -=head2 Problems with C +=head2 Problems with tr -reported with very old version of C. +reported with very old version of tr. =head2 Some problem (forget which ;-) -You have an older version of F on your C, which +You have an older version of F on your LIBPATH, which broke the build of extensions. =head2 Library ... not found @@ -936,7 +968,7 @@ You did not run C. See L. =head2 Segfault in make -You use an old version of C make. See L. +You use an old version of GNU make. See L. =head1 Specific (mis)features of OS/2 port @@ -952,6 +984,12 @@ Multi-argument form of C allows an additional numeric argument. The meaning of this argument is described in L. +=head2 C on the first line + +If the first chars of a script are C<"extproc ">, this line is treated +as C<#!>-line, thus all the switches on this line are processed (twice +if script was started via cmd.exe). + =head2 Additional modules: L, L, L, L. This @@ -999,7 +1037,7 @@ means changes with current dir. =item C -Interface to cwd from B. Used by C. +Interface to cwd from EMX. Used by C. =item C @@ -1031,7 +1069,7 @@ eventually). =item -Since is present in B, but is not functional, the same is +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 EMX (from EMX docs): @@ -1054,7 +1092,7 @@ Since F is used for globing (see L), the bugs of F plague perl as well. In particular, uppercase letters do not work in C<[...]>-patterns with -the current C. +the current pdksh. =back @@ -1091,7 +1129,7 @@ C special-cases F and F. =head1 Perl flavors Because of idiosyncrasies of OS/2 one cannot have all the eggs in the -same basket (though C environment tries hard to overcome this +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: @@ -1099,12 +1137,12 @@ executables for Perl provided by the distribution: The main workhorse. This is a chimera executable: it is compiled as an C-style executable, but is linked with C-style dynamic -library F, and with dynamic B DLL. This executable is a -C application. +library F, and with dynamic CRT DLL. This executable is a +VIO application. It can load perl dynamic extensions, and it can fork(). Unfortunately, -with the current version of B it cannot fork() with dynamic -extensions loaded (may be fixed by patches to B). +with the current version of EMX it cannot fork() with dynamic +extensions loaded (may be fixed by patches to EMX). B Keep in mind that fork() is needed to open a pipe to yourself. @@ -1114,12 +1152,12 @@ This is a statically linked C-style executable. It can fork(), but cannot load dynamic Perl extensions. The supplied executable has a lot of extensions prebuilt, thus there are situations when it can perform tasks not possible using F, like fork()ing when -having some standard extension loaded. This executable is a C +having some standard extension loaded. This executable is a VIO application. B A better behaviour could be obtained from C if it were statically linked with standard I, but -dynamically linked with the I and C DLL. Then it would +dynamically linked with the I and CRT DLL. Then it would be able to fork() with standard extensions, I would be able to dynamically load arbitrary extensions. Some changes to Makefiles and hint files should be necessary to achieve this. @@ -1131,27 +1169,27 @@ appropriate extender. See L<"Other OSes">. =head2 F -This is the same executable as , but it is a C +This is the same executable as F, but it is a PM application. -B Usually C, C, and C of a C +B Usually STDIN, STDERR, and STDOUT of a PM application are redirected to C. However, it is possible to see them if you start C from a PM program which emulates a -console window, like I of C or C. Thus it I of Emacs or EPM. Thus it I to use Perl debugger (see L) to debug your PM application. -This flavor is required if you load extensions which use C, like +This flavor is required if you load extensions which use PM, like the forthcoming C. =head2 F This is an C-style executable which is dynamically linked to -F and C DLL. I know no advantages of this executable +F and CRT DLL. I know no advantages of this executable over C, but it cannot fork() at all. Well, one advantage is that the build process is not so convoluted as with C. -It is a C application. +It is a VIO application. =head2 Why strange names? @@ -1191,16 +1229,16 @@ this DLL into memory and supplies command-arguments. This I increases the load time for the application (as well as the number of problems during compilation). Since interpreter is in a DLL, -the C is basically forced to reside in a DLL as well (otherwise -extensions would not be able to use C). +the CRT is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). =head2 Why chimera build? -Current C environment does not allow DLLs compiled using Unixish +Current EMX environment does not allow DLLs compiled using Unixish C format to export symbols for data. This forces C-style compile of F. -Current C environment does not allow F<.EXE> files compiled in +Current EMX environment does not allow F<.EXE> files compiled in C format to fork(). fork() is needed for exactly three Perl operations: @@ -1225,12 +1263,12 @@ F. =head1 ENVIRONMENT -Here we list environment variables with are either OS/2-specific, or -are more important under OS/2 than under other OSes. +Here we list environment variables with are either OS/2- and DOS- and +Win*-specific, or are more important under OS/2 than under other OSes. =head2 C -Specific for OS/2. Should have the form +Specific for EMX port. Should have the form path1;path2 @@ -1258,12 +1296,12 @@ memory handling code is buggy. =head2 C -Specific for OS/2. Gives the directory part of the location for +Specific for EMX port. Gives the directory part of the location for F. =head2 C or C -Specific for OS/2. Used as storage place for temporary files, most +Specific for EMX port. Used as storage place for temporary files, most notably C<-e> scripts. =head1 Evolution @@ -1284,12 +1322,12 @@ caching DLLs. =head2 Threading -As of release 5.003_01 perl is linked to multithreaded C +As of release 5.003_01 perl is linked to multithreaded CRT DLL. Perl itself is not multithread-safe, as is not perl malloc(). However, extensions may use multiple thread on their own risk. -Needed to compile C for C out-of-the-box. +Needed to compile C for XFree86-OS/2 out-of-the-box. =head2 Calls to external programs @@ -1307,9 +1345,11 @@ B a consensus on C was that perl should use one non-overridable shell per platform. The obvious choices for OS/2 are F and F. Having perl build itself would be impossible with F as a shell, thus I picked up C. Thus assures almost -100% compatibility with the scripts coming from *nix. +100% compatibility with the scripts coming from *nix. As an added benefit +this works as well under DOS if you use DOS-enabled port of pdksh +(see L<"Prerequisites">). -B currently F of C calls external programs +B currently F of pdksh calls external programs via fork()/exec(), and there is I functioning exec() on OS/2. exec() is emulated by EMX by asyncroneous call while the caller waits for child completion (to pretend that the C did not change). This @@ -1370,7 +1410,8 @@ there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI files - and maybe some other extensions at the time you read it. Note that OS2 perl defines 2 pseudo-extension functions -OS2::Copy::copy and DynaLoader::mod2fname. +OS2::Copy::copy and DynaLoader::mod2fname (many more now, see +L). The -R switch of older perl is deprecated. If you need to call a REXX code which needs access to variables, include the call into a REXX compartment diff --git a/lib/Test/Harness.pm b/lib/Test/Harness.pm index ba0683a02e..e2bb89eb5a 100644 --- a/lib/Test/Harness.pm +++ b/lib/Test/Harness.pm @@ -60,9 +60,14 @@ sub runtests { chop($te); print "$te" . '.' x (20 - length($te)); my $fh = new FileHandle; - my $cmd = "$^X $switches $test|"; + $fh->open($test) or print "can't open $test. $!\n"; + my $first = <$fh>; + my $s = $switches; + $s .= " -T" if $first =~ /^#!.*\bperl.*-\w*T/; + $fh->close or print "can't close $test. $!\n"; + my $cmd = "$^X $s $test|"; $cmd = "MCR $cmd" if $^O eq 'VMS'; - $fh->open($cmd) or print "can't run. $!\n"; + $fh->open($cmd) or print "can't run $test. $!\n"; $ok = $next = $max = 0; @failed = (); while (<$fh>) { @@ -100,6 +105,7 @@ sub runtests { my $wstatus = $?; my $estatus = $^O eq 'VMS' ? $wstatus : $wstatus >> 8; if ($^O eq 'VMS' ? !($wstatus & 1) : $wstatus) { + my ($failed, $canon, $percent) = ('??', '??'); print "dubious\n\tTest returned status $estatus (wstat $wstatus)\n"; if (corestatus($wstatus)) { # until we have a wait module if ($have_devel_corestack) { @@ -109,9 +115,22 @@ sub runtests { } } $bad++; - $failedtests{$test} = { canon => '??', max => $max || '??', - failed => '??', - name => $test, percent => undef, + if ($max) { + if ($next == $max + 1 and not @failed) { + print "\tafter all the subtests completed successfully\n"; + $percent = 0; + $failed = 0; # But we do not set $canon! + } else { + push @failed, $next..$max; + $failed = @failed; + (my $txt, $canon) = canonfailed($max,@failed); + $percent = 100*(scalar @failed)/$max; + print "DIED. ",$txt; + } + } + $failedtests{$test} = { canon => $canon, max => $max || '??', + failed => $failed, + name => $test, percent => $percent, estat => $estatus, wstat => $wstatus, }; } elsif ($ok == $max && $next == $max+1) { @@ -186,6 +205,7 @@ sub runtests { return ($bad == 0 && $totmax) ; } +my $tried_devel_corestack; sub corestatus { my($st) = @_; my($ret); @@ -199,8 +219,8 @@ sub corestatus { $ret = WCOREDUMP($st); } - eval {require Devel::CoreStack}; - $have_devel_corestack++ unless $@; + eval { require Devel::CoreStack; $have_devel_corestack++ } + unless $tried_devel_corestack++; $ret; } diff --git a/os2/Changes b/os2/Changes index 4691e5bd35..15fad979f3 100644 --- a/os2/Changes +++ b/os2/Changes @@ -133,3 +133,13 @@ after 5.003_21: 'script.sh'. Form without extension will call shell only if the specified file exists (will not look on path) (to prohibit trying to run shell commands directly). - Needed by magic.t. + +after 5.003_27: + ALTERNATE_SHEBANG="extproc " supported, thus options on this + line are processed (possibly twice). -S is made legal on such + a line. This -S -x is not needed any more. + perl.dll may be used from non-EMX programs (via PERL_SYS_INIT + - the caller should have valid variable "env" with + environment). Known problems: $$ does not work - is 0, waitpid + returns immediately, thus Perl cannot wait for completion of + started programs. diff --git a/os2/OS2/PrfDB/t/os2_prfdb.t b/os2/OS2/PrfDB/t/os2_prfdb.t index a8c9752d36..b9f7d90ae2 100644 --- a/os2/OS2/PrfDB/t/os2_prfdb.t +++ b/os2/OS2/PrfDB/t/os2_prfdb.t @@ -88,6 +88,8 @@ print( OS2::Prf::Set($ini,'bbb', 'xxx','abc') ? "ok 18\n" : print( OS2::Prf::Set($ini,'bbb', 'yyy','456') ? "ok 19\n" : "not ok 19\n# err: `$^E'\n"); +OS2::Prf::Close($ini); + my %hash1; tie %hash1, 'OS2::PrfDB::Sub', $inifile, 'aaa'; diff --git a/os2/os2.c b/os2/os2.c index 017230ff0b..f8f4a82735 100644 --- a/os2/os2.c +++ b/os2/os2.c @@ -1139,12 +1139,15 @@ Xs_OS2_init() OS2_Perl_data_t OS2_Perl_data; void -Perl_OS2_init() +Perl_OS2_init(char **env) { char *shell; settmppath(); OS2_Perl_data.xs_init = &Xs_OS2_init; + if (environ == NULL) { + environ = env; + } if ( (shell = getenv("PERL_SH_DRIVE")) ) { New(404, sh_path, strlen(SH_PATH) + 1, char); strcpy(sh_path, SH_PATH); diff --git a/os2/os2ish.h b/os2/os2ish.h index 7cf56fe79b..06a92a31fb 100644 --- a/os2/os2ish.h +++ b/os2/os2ish.h @@ -47,7 +47,7 @@ * (IOW, Perl won't hand off to another interpreter via an alternate * shebang sequence that might be legal Perl code.) */ -/* #define ALTERNATE_SHEBANG "#!" / **/ +#define ALTERNATE_SHEBANG "extproc " #ifndef SIGABRT # define SIGABRT SIGILL @@ -64,12 +64,14 @@ # undef I_SYS_UN #endif -void Perl_OS2_init(); +void Perl_OS2_init(char **); + +/* XXX This code hideously puts env inside: */ #define PERL_SYS_INIT(argcp, argvp) STMT_START { \ _response(argcp, argvp); \ _wildcard(argcp, argvp); \ - Perl_OS2_init(); } STMT_END + Perl_OS2_init(env); } STMT_END #define PERL_SYS_TERM() diff --git a/os2/perl2cmd.pl b/os2/perl2cmd.pl index c17ab761aa..f9cc03bdac 100644 --- a/os2/perl2cmd.pl +++ b/os2/perl2cmd.pl @@ -23,7 +23,7 @@ foreach $file (<$idir/*>) { $base =~ s|.*/||; $file =~ s|/|\\|g ; print "Processing $file => $dir\\$base.cmd\n"; - system 'cmd.exe', '/c', "echo extproc perl -Sx > $dir\\$base.cmd"; + system 'cmd.exe', '/c', "echo extproc perl -S>$dir\\$base.cmd"; system 'cmd.exe', '/c', "type $file >> $dir\\$base.cmd"; } diff --git a/perl.c b/perl.c index 24df71a56f..be2f7d8d38 100644 --- a/perl.c +++ b/perl.c @@ -1438,6 +1438,10 @@ GNU General Public License, which may be found in the Perl 5.0 source kit.\n\n") case 'P': if (preprocess) return s+1; +#ifdef ALTERNATE_SHEBANG + case 'S': /* OS/2 needs -S on "extproc" line. */ + break; +#endif /* FALL THROUGH */ default: croak("Can't emulate -%.1s on #! line",s); diff --git a/pod/perldelta.pod b/pod/perldelta.pod index ab5cde38ff..08c0a2d066 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -331,7 +331,7 @@ possibly for cleaning up. =back -=item Efficiency Enhancements +=head2 Efficiency Enhancements All hash keys with the same string are only allocated once, so even if you have 100 copies of the same hash, the immutable keys @@ -340,6 +340,60 @@ never have to be re-allocated. Functions that have an empty prototype and that do nothing but return a fixed value are now inlined (e.g. C). +=head2 Malloc Enhancements + +If perl's malloc() is used, you can require memory statistics at +runtime by running perl thusly: + + env PERL_DEBUG_MSTATS=2 perl your_script_here + +The value of 2 means that the statistics is required after the +compilation and on exit, if value is 1 the statistics is printed on +exit only. (If you want the statistics at an arbitrary time, you need +to install an optional module Devel::Peek.) + +Three new flags are recognized by malloc.c. (They have no effect if +perl is compiled with system malloc().) + +=over + +=item B<-D>C + +If defined, running out of memory may be not a fatal error if a memory +pool is allocated by assigning to variable $^M, see L<"$^M">. + +=item B<-D>C + +Perl memory allocation is by bucket with sizes close to powers of +two. Because of these malloc overhead may be big, especially for data +of size exactly a power of two. If C is defined, perl +uses a slightly different algorithm for small allocations (up to 64 +bytes long), which makes it possible to have overhead down to 1 byte +for allocations which are powers of two (and appear quite often). + +Expected memory savings (with 8-byte alignment in C) are +circa 20% for typical Perl usage. Expected slowdown due to additional +malloc overhead is in fractions of percent (hard to measure, because +of the effect of saved memory on speed). + +=item B<-D>C + +Similarly to C, this improves allocations of data with +size close ot power of two, only it works for big allocations +(starting with 16K by default). Such allocations are typical for big +hashes and special-purpose scripts, say, image processing. + +On young systems the fact that perl requires 2M from system for 1M +allocation will not affect the speed, since the tail of such a chunk +is not going to be touched, however, this may affect the maximal +number of allocations (unless the system overcommits memory). + +Expected saving of memory is 0-100% (100% in applications which +require most memory in such 2**n chunks), expected slowdown +negligible. + +=back + =head1 Pragmata Four new pragmatic modules exist: diff --git a/t/TEST b/t/TEST index 96c5ab26a4..215138ef90 100755 --- a/t/TEST +++ b/t/TEST @@ -125,6 +125,13 @@ if ($bad == 0) { ### Since not all tests were successful, you may want to run some ### of them individually and examine any diagnostic messages they ### produce. See the INSTALL document's section on "make test". +SHRDLU + warn <<'SHRDLU' if $good / $total > 0.8; + ### + ### Since most tests were successful, you have a good chance to + ### get information with better granularity by running + ### ./perl harness + ### in directory ./t. SHRDLU } ($user,$sys,$cuser,$csys) = times; diff --git a/t/harness b/t/harness index 5b460f3de4..18feb32dc3 100755 --- a/t/harness +++ b/t/harness @@ -3,8 +3,9 @@ # We suppose that perl _mostly_ works at this moment, so may use # sophisticated testing. -# Note that _before install_ you may need to run it with -I ../lib flag - +BEGIN { + unshift @INC, '../lib'; # To get lib.pm +} use lib '../lib'; use Test::Harness; diff --git a/t/op/magic.t b/t/op/magic.t index bb65ae8b7a..789c60a93c 100755 --- a/t/op/magic.t +++ b/t/op/magic.t @@ -104,12 +104,13 @@ else { $wd = '.'; } $script = "$wd/show-shebang"; +$s = "\$^X is $wd/perl, \$0 is $script\n"; if ($^O eq 'os2') { # Started by ksh, which adds suffixes '.exe' and '.' to perl and script - $s = "\$^X is $wd/perl.exe, \$0 is $script.\n"; + $s1 = "\$^X is $wd/perl.exe, \$0 is $script.\n"; } else { - $s = "\$^X is $wd/perl, \$0 is $script\n"; + $s1 = $s; } ok 19, open(SCRIPT, ">$script"), $!; ok 20, print(SCRIPT < Date: Tue, 18 Feb 1997 16:00:08 -0500 Subject: INSTALL updates since _26 Here are my proposed updates to the INSTALL file. Comments are welcome. (I'd particularly welcome an AIX bos.* blurb from someone who understand those things.) It's not all that much, really; just some sections have been moved around into what I hope is a more logical order. p5p-msgid: private-msgid: && cd .. - cd pod; make tex && && cd .. + # You may also wish to add these: + (cd /usr/include && h2ph *.h sys/*.h) + (cd pod && make html && mv *.html ) + (cd pod && make tex && ) Each of these is explained in further detail below. For information on non-Unix systems, see the section on -L<"Porting Information">, below. +L<"Porting Information"> below. =head1 DESCRIPTION @@ -40,7 +36,7 @@ If you're building Perl on a non-Unix system, you should also read the README file specific to your operating system, since this may provide additional or different instructions for building Perl. -=head1 Space Requirements. +=head1 Space Requirements The complete perl5 source tree takes up about 7 MB of disk space. The complete tree after completing C takes roughly @@ -48,7 +44,7 @@ The complete tree after completing C takes roughly system-dependent. The installation directories need something on the order of 7 MB, though again that value is system-dependent. -=head1 Start with a Fresh Distribution. +=head1 Start with a Fresh Distribution If you have built perl before, you should clean out the build directory with the command @@ -80,7 +76,7 @@ precompiled binary, it might not use the same name. In short, if you wish to use your old config.sh, I recommend running Configure interactively rather than blindly accepting the defaults. -=head1 Run Configure. +=head1 Run Configure Configure will figure out various things about your system. Some things Configure will figure out for itself, other things it will ask @@ -119,7 +115,7 @@ are simplified. For example, if you use prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of /opt/perl/lib/perl5/. -By default, Configure will compile perl to use dynamic loading, if +By default, Configure will compile perl to use dynamic loading if your system supports it. If you want to force perl to be compiled statically, you can either choose this when Configure prompts you or you can use the Configure command line option -Uusedl. @@ -131,37 +127,19 @@ use the supplied B command, e.g. CC=gcc ./configure -The B script emulates several of the more common configure +The B script emulates a few of the more common configure options. Try ./configure --help for a listing. -Cross compiling is currently not supported. +Cross compiling is not supported. For systems that do not distinguish the files "Configure" and "configure", Perl includes a copy of B named B. -=head2 Binary Compatibility With Earlier Versions of Perl 5 - -Starting with Perl 5.003, all functions in the Perl C source code have -been protected by default by the prefix Perl_ (or perl_) so that you -may link with third-party libraries without fear of namespace -collisons. This change broke compatability with version 5.002, so -installing 5.003 or 5.004 over 5.002 or earlier will force you to -re-build and install all of your dynamically loadable extensions. -(The standard extensions supplied with Perl are handled -automatically). You can turn off this namespace protection by adding --DNO_EMBED to your ccflags variable in config.sh. - -Perl 5.003's namespace protection was incomplete, which has been -rectified in Perl 5.004. However, some sites may need to maintain -complete binary compatibility with Perl 5.003. If you are building -Perl for such a site, then when B asks if you want binary -compatibility, answer "y". - =head2 Extensions By default, Configure will offer to build every extension which appears @@ -202,7 +180,7 @@ Again, this is taken care of automatically if you don't have the ndbm library. Of course, you may always run Configure interactively and select only -the Extensions you want. +the extensions you want. Finally, if you have dynamic loading (most modern Unix systems do) remember that these extensions do not increase the size of your perl @@ -230,7 +208,7 @@ Configure. See the examples below. =over 4 -=item gdbm in /usr/local. +=item gdbm in /usr/local Suppose you have gdbm and want Configure to find it and build the GDBM_File extension. This examples assumes you have F @@ -290,7 +268,7 @@ F, then you have to include both, namely =back -=head2 Installation Directories. +=head2 Installation Directories The installation directories can all be changed by answering the appropriate questions in Configure. For convenience, all the @@ -350,6 +328,99 @@ can be moved to the site_perl and site_perl/archname directories. Again, these are just the defaults, and can be changed as you run Configure. +=head2 Changing the installation directory + +Configure distinguishes between the directory in which perl (and its +associated files) should be installed and the directory in which it +will eventually reside. For most sites, these two are the same; for +sites that use AFS, this distinction is handled automatically. +However, sites that use software such as B to manage software +packages may also wish to install perl into a different directory and +use that management software to move perl to its final destination. +This section describes how to do this. Someday, Configure may support +an option C<-Dinstallprefix=/foo> to simplify this. + +Suppose you want to install perl under the F directory. +You can edit F and change all the install* variables to +point to F instead of F. You could +also set them all from the Configure command line. Or, you can +automate this process by placing the following lines in a file +F B you run Configure (replace /tmp/perl5 by a +directory of your choice): + + installprefix=/tmp/perl5 + test -d $installprefix || mkdir $installprefix + test -d $installprefix/bin || mkdir $installprefix/bin + installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"` + installbin=`echo $installbin | sed "s!$prefix!$installprefix!"` + installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"` + installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"` + installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"` + installscript=`echo $installscript | sed "s!$prefix!$installprefix!"` + installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"` + installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"` + +Then, you can Configure and install in the usual way: + + sh Configure -des + make + make test + make install + +=head2 Creating an installable tar archive + +If you need to install perl on many identical systems, it is +convenient to compile it once and create an archive that can be +installed on multiple systems. Here's one way to do that: + + # Set up config.over to install perl into a different directory, + # e.g. /tmp/perl5 (see previous part). + sh Configure -des + make + make test + make install + cd /tmp/perl5 + tar cvf ../perl5-archive.tar . + # Then, on each machine where you want to install perl, + cd /usr/local # Or wherever you specified as $prefix + tar xvf perl5-archive.tar + +=head2 Configure-time Options + +There are several different ways to Configure and build perl for your +system. For most users, the defaults are sensible and will work. +Some users, however, may wish to further customize perl. Here are +some of the main things you can change. + +=head2 Binary Compatibility With Earlier Versions of Perl 5 + +If you have dynamically loaded extensions that you built under +perl 5.003 and that you wish to continue to use with perl 5.004, then you +need to ensure that 5.004 remains binary compatible with 5.003. + +Starting with Perl 5.003, all functions in the Perl C source code have +been protected by default by the prefix Perl_ (or perl_) so that you +may link with third-party libraries without fear of namespace +collisions. This change broke compatibility with version 5.002, so +installing 5.003 or 5.004 over 5.002 or earlier will force you to +re-build and install all of your dynamically loadable extensions. +(The standard extensions supplied with Perl are handled +automatically). You can turn off this namespace protection by adding +-DNO_EMBED to your ccflags variable in config.sh. + +Perl 5.003's namespace protection was incomplete, but this has +been fixed in 5.004. However, some sites may need to maintain +complete binary compatibility with Perl 5.003. If you are building +Perl for such a site, then when B asks if you want binary +compatibility, answer "y". + +On the other hand, if you are embedding perl into another application +and want the maximum namespace protection, then you probably ought to +answer "n" when B asks if you want binary compatibility. + +The default answer of "y" to maintain binary compatibility is probably +appropriate for almost everyone. + =head2 Selecting File IO mechanisms Previous versions of perl used the standard IO mechanisms as defined in @@ -374,7 +445,7 @@ everywhere. =item 1. AT&T's "sfio". This has superior performance to in many -cases, and is extensible by the use of "disipline" modules. Sfio +cases, and is extensible by the use of "discipline" modules. Sfio currently only builds on a subset of the UNIX platforms perl supports. Because the data structures are completely different from stdio, perl extension modules or external libraries may not work. This @@ -401,7 +472,7 @@ abstraction. This configuration should work on all platforms (but might not). -You select this option via : +You select this option via: sh Configure -Duseperlio -Uusesfio @@ -410,46 +481,7 @@ detect sfio, then this will be the default suggested by Configure. =back -=head2 Changing the installation directory - -Configure distinguishes between the directory in which perl (and its -associated files) should be installed and the directory in which it -will eventually reside. For most sites, these two are the same; for -sites that use AFS, this distinction is handled automatically. -However, sites that use software such as B to manage software -packages may also wish to install perl into a different directory and -use that management software to move perl to its final destination. -This section describes how to do this. Someday, Configure may support -an option C<-Dinstallprefix=/foo> to simplify this. - -Suppose you want to install perl under the F directory. -You can edit F and change all the install* variables to -point to F instead of F. You could -also set them all from the Configure command line. Or, you can -automate this process by placing the following lines in a file -F B you run Configure (replace /tmp/perl5 by a -directory of your choice): - - installprefix=/tmp/perl5 - test -d $installprefix || mkdir $installprefix - test -d $installprefix/bin || mkdir $installprefix/bin - installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"` - installbin=`echo $installbin | sed "s!$prefix!$installprefix!"` - installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"` - installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"` - installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"` - installscript=`echo $installscript | sed "s!$prefix!$installprefix!"` - installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"` - installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"` - -Then, you can Configure and install in the usual way: - - sh Configure -des - make - make test - make install - -=head2 Building a shared libperl.so Perl library. +=head2 Building a shared libperl.so Perl library Currently, for most systems, the main perl executable is built by linking the "perl library" libperl.a with perlmain.o, your static @@ -465,7 +497,7 @@ can share the same library. The disadvantages are that there may be a significant performance penalty associated with the shared libperl.so, and that the overall -meachanism is still rather fragile with respect to different versions +mechanism is still rather fragile with respect to different versions and upgrades. In terms of performance, on my test system (Solaris 2.5_x86) the perl @@ -488,7 +520,7 @@ You can elect to build a shared libperl by sh Configure -Duseshrplib To actually build perl, you must add the current working directory to your -LD_LIBRARY_PATH environtment variable before running make. You can do +LD_LIBRARY_PATH environment variable before running make. You can do this with LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH @@ -520,23 +552,22 @@ version of perl. You can do this with by changing all the *archlib* variables in config.sh, namely archlib, archlib_exp, and installarchlib, to point to your new architecture-dependent library. -=head2 Creating an installable tar archive +=head2 Other Compiler Flags -If you need to install perl on many identical systems, it is -convenient to compile it once and create an archive that can be -installed on multiple systems. Here's one way to do that: +For most users, all of the Configure defaults are fine. However, +you can change a number of factors in the way perl is built +by adding appropriate -D directives to your ccflags variable in +config.sh. - # Set up config.over to install perl into a different directory, - # e.g. /tmp/perl5 (see previous part). - sh Configure -des - make - make test - make install - cd /tmp/perl5 - tar cvf ../perl5-archive.tar . - # Then, on each machine where you want to install perl, - cd /usr/local # Or wherever you specified as $prefix - tar xvf perl5-archive.tar +For example, you can replace the rand() and srand() functions in the +perl source by any other random number generator by a trick such as the +following: + + sh Configure -Dccflags='-Drand=random -Dsrand=srandom' + +or by adding C<-Drand=random> and C<-Dsrandom=srandom> to your ccflags +at the appropriate Configure prompt. (You may also have to adjust +Configure's guess for 'randbits' as well.) =head2 What if it doesn't work? @@ -549,15 +580,15 @@ Configure interactively so that you can check (and correct) its guesses. All the installation questions have been moved to the top, so you don't -have to wait for them. Once you've handled them (and your C compiler & -flags) you can type C<&-d> at the next Configure prompt and Configure +have to wait for them. Once you've handled them (and your C compiler and +flags) you can type C<&-d> at the next Configure prompt and Configure will use the defaults from then on. If you find yourself trying obscure command line incantations and config.over tricks, I recommend you run Configure interactively instead. You'll probably save yourself time in the long run. -=item Hint files. +=item Hint files The perl distribution includes a number of system-specific hints files in the hints/ directory. If one of them matches your system, Configure @@ -651,7 +682,7 @@ To change the C flags for all the files, edit F and change either C<$ccflags> or C<$optimize>, and then re-run B. -=item No sh. +=item No sh If you don't have sh, you'll have to copy the sample file config_H to config.h and edit the config.h to reflect your system's peculiarities. @@ -660,8 +691,8 @@ mechanism. =item Porting information -Specific information for the OS/2, Plan9, and VMS ports are in the -corresponing subdirectories. Additional information, including +Specific information for the OS/2, Plan9, VMS and Win32 ports are in the +corresponding subdirectories. Additional information, including a glossary of all those config.sh variables, is in the Porting subdirectory. @@ -694,12 +725,7 @@ If none of them help, and careful reading of the error message and the relevant manual pages on your system doesn't help, you can send a message to either the comp.lang.perl.misc newsgroup or to perlbug@perl.com with an accurate description of your problem. -Please include the I of the B<./myconfig> shell script -that comes with the distribution. - -[The B program that comes with the perl distribution is -useful for sending in such reports, but you need to have -perl compiled and installed before you can use it.] +See L<"Reporting Problems"> below. =over 4 @@ -726,7 +752,8 @@ locale. See the discussion under L below about locales. =item * -If you get duplicates upon linking for malloc et al, say -DHIDEMYMALLOC. +If you get duplicates upon linking for malloc et al, +add -DHIDEMYMALLOC to your ccflags variable in config.sh. =item varargs @@ -770,7 +797,8 @@ L<"Solaris and SunOS dynamic loading">. =item * If you run into dynamic loading problems, check your setting of -the LD_LIBRARY_PATH environment variable. Perl should build +the LD_LIBRARY_PATH environment variable. If you're creating a static +Perl library (libperl.a rather than libperl.so) it should build fine with LD_LIBRARY_PATH unset, though that may depend on details of your local set-up. @@ -780,13 +808,13 @@ The primary cause of the 'dlopen: stub interception failed' message is that the LD_LIBRARY_PATH environment variable includes a directory which is a symlink to /usr/lib (such as /lib). -The reason this causes a problem is quite subtle. The file libdl.so.1.0 +The reason this causes a problem is quite subtle. The file libdl.so.1.0 actually *only* contains functions which generate 'stub interception failed' errors! The runtime linker intercepts links to "/usr/lib/libdl.so.1.0" and links in internal implementation of those functions instead. [Thanks to Tim Bunce for this explanation.] -=item * +=item nm extraction If Configure seems to be having trouble finding library functions, try not using nm extraction. You can do this from the command line @@ -812,10 +840,10 @@ If Configure guessed wrong, it is likely that Configure guessed wrong on a number of other common functions too. You are probably better off re-running Configure without using nm extraction (see previous item). -=item * +=item Optimizer If you can't compile successfully, try turning off your compiler's -optimizier. Edit config.sh and change the line +optimizer. Edit config.sh and change the line optimize='-O' @@ -860,7 +888,7 @@ If you see such a message during the building of an extension, but the extension passes its tests anyway (see L<"make test"> below), then don't worry about the warning message. The extension Makefile.PL goes looking for various libraries needed on various -systems; few systems will need all the possible libries listed. +systems; few systems will need all the possible libraries listed. For example, a system may have -lcposix or -lposix, but it's unlikely to have both, so most users will see warnings for the one they don't have. The message 'will try anyway' is intended to @@ -879,6 +907,20 @@ It is true that, in principle, Configure could have figured all of this out, but Configure and the extension building process are not quite that tightly coordinated. +=item sh: ar: not found + +This is a message from your shell telling you that the command 'ar' +was not found. You need to check your PATH environment variable to +make sure that it includes the directory with the 'ar' command. This +is a common problem on Solaris, where 'ar' is in the F +directory. + +=item db-recno failure on tests 51, 53 and 55 + +Old versions of the DB library (including the DB library which comes +with FreeBSD 2.1) had broken handling of recno databases with modified +bval settings. Upgrade your DB library or OS. + =item * Some additional things that have been reported for either perl4 or perl5: @@ -893,22 +935,17 @@ If you get syntax errors on '(', try -DCRIPPLED_CC. Machines with half-implemented dbm routines will need to #undef I_ODBM -db-recno failure on tests 51, 53 and 55: Old versions of the DB library -(including the DB library which comes with FreeBSD 2.1) had broken -handling of recno databases with modified bval settings. Upgrade your -DB library or OS. - =back =head1 make test This will run the regression tests on the perl you just made. If it doesn't say "All tests successful" then something went wrong. See the -file F in the F subdirectory. Note that you can't run it -in background if this disables opening of /dev/tty. +file F in the F subdirectory. Note that you can't run the +tests in background if this disables opening of /dev/tty. If B bombs out, just B to the F directory and run -B by hand to see if it makes any difference. If individual tests +F<./TEST> by hand to see if it makes any difference. If individual tests bomb, you can run them by hand, e.g., ./perl op/groups.t @@ -924,20 +961,26 @@ complicated constructs). You can also read the individual tests to see if there are any helpful comments that apply to your system. -B: one possible reason for errors is that some external programs +B: One possible reason for errors is that some external programs may be broken due to the combination of your environment and the way C exercises them. For example, this may happen if you have -one or more of these environment variables set: C. In some versions of UNIX, the non-English locales are known to cause programs to exhibit mysterious errors. If you have any of the above environment variables set, please try -C (for C shell) or (for -Bourne or Korn shell) from the command line and then retry C. If the tests then succeed, you may have a broken program that -is confusing the testing. Please run the troublesome test by hand as +is confusing the testing. Please run the troublesome test by hand as shown above and see whether you can locate the program. Look for -things like: C or +things like: C or C. All these mean that Perl is trying to run some external program. @@ -946,14 +989,10 @@ external program. This will put perl into the public directory you specified to B; by default this is F. It will also try to put the man pages in a reasonable place. It will not nroff the man -page, however. You may need to be root to run B. If you +pages, however. You may need to be root to run B. If you are not root, you must own the directories in question and you should ignore any messages about chown not working. -You may see some harmless error messages and warnings from pod2man. -You may safely ignore them. (Yes, they should be fixed, but they -didn't seem important enough to warrant holding up the entire release.) - If you want to see exactly what will happen without installing anything, you can run @@ -973,12 +1012,16 @@ B will install the following: c2ph, pstruct Scripts for handling C structures in header files. s2p sed-to-perl translator find2perl find-to-perl translator + h2ph Extract constants and simple macros from C headers h2xs Converts C .h header files to Perl extensions. perlbug Tool to report bugs in Perl. perldoc Tool to read perl's pod documentation. + pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules pod2html, Converters from perl's pod documentation format - pod2latex, and to other useful formats. - pod2man + pod2latex, to other useful formats. + pod2man, and + pod2text + splain Describe Perl warnings and errors library files in $privlib and $archlib specified to Configure, usually under /usr/local/lib/perl5/. @@ -1000,34 +1043,7 @@ under $archlib so that any user may later build new extensions, run the optional Perl compiler, or embed the perl interpreter into another program even if the Perl source is no longer available. -Most of the documentation in the pod/ directory is also available -in HTML and LaTeX format. Type - - cd pod; make html; cd .. - -to generate the html versions, and - - cd pod; make tex; cd .. - -to generate the LaTeX versions. - -=head1 cd /usr/include; h2ph *.h sys/*.h - -Some of the perl library files need to be able to obtain information from -the system header files. This command will convert the most commonly used -header files in F into files that can be easily interpreted -by perl. These files will be placed in architectural library directory -you specified to B; by default this is -F, where B is your architecture -(such as C) and B is the version of perl you are -building (for example, C<5.003>). - -B Due to differences in the C and perl languages, the conversion of -the header files in not perfect. You may have to hand edit some of the -converted files to get them to parse correctly. For example, it breaks -spectacularly on type casting and certain structures. - -=head1 Coexistence with earlier versions of perl5. +=head1 Coexistence with earlier versions of perl5 You can safely install the current version of perl5 and still run scripts under the old binaries for versions 5.003 and later ONLY. Instead of @@ -1040,7 +1056,7 @@ in incompatible ways. The architecture-dependent files are stored in a version-specific directory (such as F) so that -they are still accessible. I Perl 5.000 and 5.001 did not +they are still accessible. I Perl 5.000 and 5.001 did not put their architecture-dependent libraries in a version-specific directory. They are simply in F. If you will not be using 5.000 or 5.001, you may safely remove those @@ -1053,8 +1069,8 @@ Most extensions will probably not need to be recompiled to use with a newer version of perl. If you do run into problems, and you want to continue to use the old version of perl along with your extension, simply move those extension files to the appropriate version directory, such as -F. Then Perl 5.004 will find your -files in the 5.004 directory, and newer versions of perl will find your +F. Then Perl 5.003 will find your +files in the 5.003 directory, and newer versions of perl will find your newer extension in the site_perl directory. Some users may prefer to keep all versions of perl in completely @@ -1082,6 +1098,55 @@ the C<#!> line at the top of them by C<#!/usr/local/bin/perl4.036> (or whatever the appropriate pathname is). See pod/perltrap.pod for possible problems running perl4 scripts under perl5. +=head1 cd /usr/include; h2ph *.h sys/*.h + +Some perl scripts need to be able to obtain information from +the system header files. This command will convert the most commonly used +header files in F into files that can be easily interpreted +by perl. These files will be placed in the architectural library directory +you specified to B; by default this is +F, where B is your architecture +(such as C) and B is the version of perl you are +building (for example, C<5.004>). + +B Due to differences in the C and perl languages, the +conversion of the header files is not perfect. You will probably have +to hand-edit some of the converted files to get them to parse +correctly. For example, h2ph breaks spectacularly on type casting and +certain structures. + +=head1 cd pod && make html && mv *.html (www home dir) + +Some sites may wish to make the documentation in the pod/ directory +available in HTML format. Type + + cd pod && make html && mv *.html + +where F is wherever your site keeps HTML files. + +=head1 cd pod && make tex && (process the latex files) + +Some sites may also wish to make the documentation in the pod/ directory +available in TeX format. Type + + (cd pod && make tex && ) + +=head1 Reporting Problems + +If you have difficulty building perl, and none of the advice in this +file helps, and careful reading of the error message and the relevant +manual pages on your system doesn't help either, then you should send a +message to either the comp.lang.perl.misc newsgroup or to +perlbug@perl.com with an accurate description of your problem. + +Please include the I of the B<./myconfig> shell script +that comes with the distribution. Alternatively, you can use the +B program that comes with the perl distribution, +but you need to have perl compiled and installed before you can use it. + +You might also find helpful information in the F +directory of the perl distribution. + =head1 DOCUMENTATION Read the manual entries before running perl. The main documentation is @@ -1095,9 +1160,11 @@ along with its I by going to the pod/ subdirectory and running (either): ./roffitall -groff # If you have GNU groff installed - ./roffitall -psroff # Otherwise + ./roffitall -psroff # If you have psroff This will leave you with two postscript files ready to be printed. +(You may need to fix the roffitall command to use your local troff +set-up.) Note that you must have performed the installation already before running the above, since the script collects the installed files to @@ -1110,4 +1177,4 @@ from the original README by Larry Wall. =head1 LAST MODIFIED -8 February 1997 +18 February 1997 -- cgit v1.2.1