correct -Dmad skip count for tests introduced in 2d85e411 and 4dc843bc
[perl.git] / README.mpeix
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see perlpod manpage) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 perlmpeix - Perl/iX for HP e3000 MPE
8
9 =head1 SYNOPSIS
10
11    http://www.bixby.org/mark/perlix.html
12    Perl language for MPE
13    Last updated January 12, 2006 @ 2100 UTC
14
15
16 =head1 NOTE
17
18 This is a podified version of what used to be on the above-mentioned web page,
19 podified by Jarkko Hietaniemi 2001-Jan-01.
20
21 =head1 What's New in Perl for MPE/iX
22
23 January 12, 2006
24
25 =over 4
26
27 =item *
28
29 Updated for perl-5.8.8 and perl-5.9.3 by Ken Hirsch.
30
31 Simplified the build process by using the MPEAUTOCONF
32 functionality in Mark Klein's ld.
33
34 If you build this from scratch, make sure you have a version
35 of ld which supports it.  In the shell, type
36
37   ld --help
38     and look for AUTOCONF or MPEAUTOCONF near the bottom
39
40   or do this:
41   ld --help 2>&1 | grep AUTOCONF
42
43 If you see don't see AUTOCONF or MPEAUTOCONF, make sure you get a new
44 version.
45
46 You also do not have to use mpeix/relink after building, so the
47 recommend sequence is:
48
49   ./Configure -de
50
51       # or ./Configure -de -Dusedevel 
52       # if you're building a development version
53
54   make
55   make test
56      # if you run this in a job, do "make test_notty"
57
58   make install
59
60 Be prepared for a wait. These take much longer on MPE/iX than on a Unix
61 system, because of a slow forking, mostly.  On a lightly-loaded HP3000
62 Series 979 running MPE/iX 7.5:
63
64     Configure: 1 hour
65     make:      1 hour 15 minutes
66     make test  1 hour 45 minutes
67
68 Various socket problems were fixed in mpeix.c.
69
70 Mark Klein provided a fixed sigsetjmp (that works with dynamic
71 libraries) in mpeix_setjmp.c
72
73 =back
74
75 June 1, 2000
76
77 =over 4
78
79 =item *
80
81 Rebuilt to be compatible with mod_perl.  If you plan on using
82 mod_perl, you MUST download and install this version of Perl/iX!
83
84 =item *
85
86 uselargefiles="undef": not available in MPE for POSIX files yet.
87
88 =item *
89
90 Now bundled with various add-on packages:
91
92 =over 8
93
94 =item *
95
96 libnet (as seen on CPAN)
97
98 =item *
99
100 libwww-perl (LWP) which lets Perl programs behave like web browsers:
101
102 =item *
103
104 mod_perl (just the perl portion; the actual DSO will be released
105 soon with Apache/iX 1.3.12 from bixby.org).  This module allows you to
106 write high performance persistent Perl CGI scripts and all sorts of
107 cool things. (L<http://perl.apache.org/>)
108
109 and much much more hiding under /PERL/PUB/.cpan/
110
111 =item *
112
113 The CPAN module now works for automatic downloading and
114 installing of add-on packages:
115
116     1. export FTP_PASSIVE=1
117     2. perl -MCPAN -e shell
118     3. Ignore any terminal I/O related complaints!
119
120 (L<http://search.cpan.org/dist/CPAN/>)
121
122 =back
123
124 =back
125
126 May 20, 2000
127
128 =over 4
129
130 =item *
131
132 Updated to version 5.6.0.  Builds straight out of the box on MPE/iX.
133
134 =item *
135
136 Perl's getpwnam() function which had regressed to being
137 unimplemented on MPE is now implemented once again.
138
139 =back
140
141 September 17, 1999
142
143 =over 4
144
145 =item *
146
147 Migrated from cccd.edu to bixby.org.
148
149 =back
150
151 =head1 Welcome to Perl/iX
152
153 This is the official home page for the HP e3000 MPE/iX
154 ( L<http://www.hp.com/go/e3000> ) port of the Perl scripting
155 language ( L<http://www.perl.com/> ) which gives you all of the power of C,
156 awk, sed, and sh in a single language. Check here for the latest news,
157 implemented functionality, known bugs, to-do list, etc. Status reports
158 about major milestones will also be posted to the HP3000-L mailing list
159 ( L<http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU> ) and
160 its associated gatewayed newsgroup comp.sys.hp.mpe.
161
162 I'm doing this port because I can't live without Perl on the Unix
163 machines that I administer, and I want to have the same power
164 available to me on MPE.
165
166 Please send your comments, questions, and bug reports directly to me,
167 Mark Bixby ( L<http://www.bixby.org/mark/> ). Or just post them to HP3000-L.
168
169 The platform I'm using to do this port is an HP 3000 957RX running
170 MPE/iX 6.0 and using the GNU gcc C compiler
171 ( L<http://jazz.external.hp.com/src/gnu/gnuframe.html> ).
172
173 The combined porting wisdom from all of my ports can be found in my
174 MPE/iX Porting Guide (L<http://www.bixby.org/mark/porting.html>).
175
176 IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of
177 the software you download from bixby.org is my personal freeware that
178 is NOT supported by HP.
179
180 =head1 System Requirements for Perl/iX
181
182 =over 4
183
184 =item *
185
186 MPE/iX 5.5 or later. This version of Perl/iX does NOT run on
187 MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines.
188
189 =item *
190
191 If you wish to recompile Perl, you must install both GNUCORE and
192 GNUGCC from jazz (L<http://jazz.external.hp.com/src/gnu/gnuframe.html>).
193
194 =item *
195
196 Perl/iX will be happier on MPE/iX 5.5 if you install the MPEKX40B
197 extended POSIX filename characters patch, but this is optional.
198
199 =item *
200
201 Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to
202 prevent Perl/iX from dying with an unresolved external reference
203 to _getenv_libc.
204
205 =item *
206
207 If you will be compiling Perl/iX yourself, you will also need
208 Syslog/iX ( L<http://www.bixby.org/mark/syslogix.html> ) and the
209 /BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX
210 ( L<http://www.bixby.org/mark/bindix.html> ).
211
212 =back
213
214 =head1 How to Obtain Perl/iX
215
216 =over 4
217
218 =item 1.
219
220 Download Perl using either FTP.ARPA.SYS or some other client
221
222 =item 2.
223
224 Extract the installation script
225
226 =item 3.
227
228 Edit the installation script
229
230 =item 4.
231
232 Run the installation script
233
234 =item 5.
235
236 Convert your *.a system archive libraries to *.sl shared libraries
237
238 =back
239
240 Download Perl using FTP.ARPA.SYS from your HP 3000 (the preferred
241 method).....
242
243     :HELLO MANAGER.SYS
244     :XEQ FTP.ARPA.SYS
245     open ftp.bixby.org
246     anonymous
247     your@email.address
248     bytestream
249     cd /pub/mpe
250     get perl-5.6.0-mpe.tar.Z /tmp/perl.tar.Z;disc=2147483647
251     exit
252
253 .....Or download using some other generic web or ftp client (the alternate
254 method)
255
256 Download the following files (make sure that you use "binary mode" or
257 whatever client feature that is 8-bit clean):
258
259 =over 4
260
261 =item *
262
263 Perl from
264
265     http://www.bixby.org/ftp/pub/mpe/perl-5.6.0-mpe.tar.Z
266
267 or
268
269     ftp://ftp.bixby.org/pub/mpe/perl-5.6.0-mpe.tar.Z
270
271 =item *
272
273 Upload those files to your HP 3000 in an 8-bit clean bytestream manner to:
274
275     /tmp/perl.tar.Z
276
277 =item *
278
279 Then extract the installation script (after both download methods)
280
281     :CHDIR /tmp
282     :XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL'
283
284 =item *
285
286 Edit the installation script
287
288 Examine the accounting structure creation commands and modify if
289 necessary (adding additional capabilities, choosing a non-system
290 volume set, etc).
291
292     :XEQ VI.HPBIN.SYS /tmp/INSTALL
293
294 =item *
295
296 Run the installation script.
297
298 The accounting structure will be created and then all files will be
299 extracted from the archive.
300
301     :XEQ SH.HPBIN.SYS /tmp/INSTALL
302
303 =item *
304
305 Convert your *.a system archive libraries to *.sl shared libraries
306
307 You only have to do this ONCE on your MPE/iX 5.5 machine in order to
308 convert /lib/lib*.a and /usr/lib/lib*.a libraries to their *.sl
309 equivalents.  This step should not be necessary on MPE/iX 6.0 or later
310 machines because the 6.0 or later update process does it for you.
311
312     :XEQ SH.HPBIN.SYS /PERL/PUB/LIBSHP3K
313
314 =back
315
316 =head1 Perl/iX Distribution Contents Highlights
317
318 =over 4
319
320 =item README
321
322 The file you're reading now.
323
324 =item INSTALL
325
326 Perl/iX Installation script.
327
328 =item LIBSHP3K
329
330 Script to convert *.a system archive libraries to *.sl shared libraries.
331
332 =item PERL
333
334 Perl NMPRG executable.  A version-numbered backup copy also
335 exists.  You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl".
336
337 =item .cpan/
338
339 Much add-on source code downloaded with the CPAN module.
340
341 =item lib/
342
343 Perl libraries, both core and add-on.
344
345 =item man/
346
347 Perl man page documentation.
348
349 =item public_html/feedback.cgi
350
351 Sample feedback CGI form written in Perl.
352
353 =item src/perl-5.6.0-mpe
354
355 Source code.
356
357 =back
358
359 =head1 How to Compile Perl/iX
360
361 =over 4
362
363 =item 1.
364
365 cd src/perl-5.6.0-mpe
366
367 =item 2.
368
369 Read the INSTALL file for the official instructions
370
371 =item 3.
372
373 ./Configure -d
374
375 =item  4.
376
377 make
378
379 =item 5.
380
381 ./mpeix/relink
382
383 =item  6.
384
385 make test (expect approximately 15 out of 11306 subtests to fail,
386 mostly due to MPE not supporting hard links, UDP socket problems,
387 and handling exit() return codes improperly)
388
389 =item 7.
390
391 make install
392
393 =item 8.
394
395 Optionally create symbolic links that point to the Perl
396 executable, i.e. ln -s /PERL/PUB/PERL /usr/local/bin/perl
397
398 =back
399
400 The summary test results from "cd t; ./perl -I../lib harness":
401
402   Failed Test  Status Wstat Total Fail  Failed  List of failed
403   ---------------------------------------------------------------------------
404   io/fs.t                      29    8  27.59%  2-5, 7-9, 11
405   io/openpid.t                 10    1  10.00%  7
406   lib/io_sock.t                14    1   7.14%  13
407   lib/io_udp.t                  7    2  28.57%  3, 5
408   lib/posix.t                  27    1   3.70%  12
409   op/lex_assign.t             187    1   0.53%  13
410   op/stat.t                    58    1   1.72%  3
411   15 tests and 94 subtests skipped.
412   Failed 7/236 test scripts, 97.03% okay. 15/11306 subtests failed, 99.87% okay.
413
414 =head1 Getting Started with Perl/iX
415
416 Create your Perl script files with "#!/PERL/PUB/perl" (or an
417 equivalent symbolic link) as the first line.  Use the chmod command to
418 make sure that your script has execute permission. Run your script!
419
420 Be sure to take a look at the CPAN module list
421 ( L<http://www.cpan.org/CPAN.html> ). A wide variety of free Perl software
422 is available.  You can automatically download these packages by using
423 the CPAN module ( L<http://search.cpan.org/dist/CPAN/> ).
424
425 =head1 MPE/iX Implementation Considerations
426
427 There some minor functionality issues to be aware of when comparing
428 Perl for Unix (Perl/UX) to Perl/iX:
429
430 =over 4
431
432 =item *
433
434 MPE gcc/ld doesn't properly support linking NMPRG executables against
435 NMXL dynamic libraries, so you must manually run mpeix/relink after
436 each re-build of Perl.
437
438 =item *
439
440 Perl/iX File::Copy will use MPE's /bin/cp command to copy files by
441 name in order to preserve file attributes like file code.
442
443 =item *
444
445 MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(),
446 setpwent(), endpwent().
447
448 =item *
449
450 MPE (and thus Perl/iX) lacks support for hard links.
451
452 =item *
453
454 MPE requires GETPRIVMODE() in order to bind() to ports less than 1024.
455 Perl/iX will call GETPRIVMODE() automatically on your behalf if you
456 attempt to bind() to these low-numbered ports.  Note that the Perl/iX
457 executable and the PERL account do not normally have CAP=PM, so if you
458 will be bind()-ing to these privileged ports, you will manually need
459 to add PM capability as appropriate.
460
461 =item *
462
463 MPE requires that you bind() to an IP address of zero.  Perl/iX
464 automatically replaces the IP address that you pass to bind() with
465 a zero.
466
467 =item *
468
469 MPE requires GETPRIVMODE() in order to setuid().  There are too many
470 calls to setuid() within Perl/iX, so I have not attempted an automatic
471 GETPRIVMODE() solution similar to bind().
472
473 =back
474
475 =head1 Known Perl/iX Bugs Under Investigation
476
477 None.
478
479 =head1 Perl/iX To-Do List
480
481 =over 4
482
483 =item *
484
485 Make setuid()/setgid() support work.
486
487 =item *
488
489 Make sure that fcntl() against a socket descriptor is redirected to sfcntl().
490
491 =item *
492
493 Add support for Berkeley DB once I've finished porting Berkeley DB.
494
495 =item *
496
497 Write an MPE XS extension library containing miscellaneous important
498 MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl().
499
500 =back
501
502 =head1 Perl/iX Change History
503
504 May 6, 1999
505
506 =over 4
507
508 =item *
509
510 Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent
511 Perl/iX from dying with an unresolved external reference to _getenv_libc.
512
513 =back
514
515 April 7, 1999
516
517 =over 4
518
519 =item *
520
521 Updated to version 5.005_03.
522
523 =item *
524
525 The official source distribution once again compiles "straight out
526 of the box" for MPE.
527
528 =item *
529
530 The current incarnation of the 5.5 POSIX filename extended
531 characters patch is now MPEKX40B.
532
533 =item *
534
535 The LIBSHP3K *.a -> *.sl library conversion script is now included
536 as /PERL/PUB/LIBSHP3K.
537
538 =back
539
540 November 20, 1998
541
542 =over 4
543
544 =item *
545
546 Updated to version 5.005_02.
547
548 =item *
549
550 Fixed a DynaLoader bug that was unable to load symbols from relative
551 path name libraries.
552
553 =item *
554
555 Fixed a .xs compilation bug where the mpeixish.sh include file wasn't
556 being installed into the proper directory.
557
558 =item *
559
560 All bugfixes will be submitted back to the official Perl developers.
561
562 =item *
563
564 The current incarnation of the POSIX filename extended characters
565 patch is now MPEKXJ3A.
566
567 =back
568
569 August 14, 1998
570
571 =over 4
572
573 =item *
574
575 The previous POSIX filename extended characters patch MPEKX44C has
576 been superseded by MPEKXB5A.
577
578 =back
579
580 August 7, 1998
581
582 =over 4
583
584 =item *
585
586 The previous POSIX filename extended characters patch MPEKX76A has
587 been superseded by MPEKX44C.
588
589 =back
590
591 July 28, 1998
592
593 =over 4
594
595 =item *
596
597 Updated to version 5.005_01.
598
599 =back
600
601 July 23, 1998
602
603 =over 4
604
605 =item *
606
607 Updated to version 5.005 (production release).  The public
608 freeware sources are now 100% MPE-ready "straight out of the box".
609
610 =back
611
612 July 17, 1998
613
614 =over 4
615
616 =item *
617
618 Updated to version 5.005b1 (public beta release).  The public
619 freeware sources are now 99.9% MPE-ready.  By installing and
620 testing this beta on your own HP3000, you will be helping to
621 insure that the final release of 5.005 will be 100% MPE-ready and
622 100% bug free.
623
624 =item *
625
626 My MPE binary release is now extracted using my standard INSTALL script.
627
628 =back
629
630 July 15, 1998
631
632 =over 4
633
634 =item *
635
636 Changed startperl to #!/PERL/PUB/perl so that Perl will recognize
637 scripts more easily and efficiently.
638
639 =back
640
641 July 8, 1998
642
643 =over 4
644
645 =item *
646
647 Updated to version 5.004_70 (internal developer release) which is now
648 MPE-ready.  The next public freeware release of Perl should compile
649 "straight out of the box" on MPE.  Note that this version of Perl/iX
650 was strictly internal to me and never publicly released.  Note that
651 [21]BIND/iX is now required (well, the include files and libbind.a) if
652 you wish to compile Perl/iX.
653
654 =back
655
656 November 6, 1997
657
658 =over 4
659
660 =item *
661
662 Updated to version 5.004_04.  No changes in MPE-specific functionality.
663
664 =back
665
666 October 16, 1997
667
668 =over 4
669
670 =item *
671
672 Added Demos section to the Perl/iX home page so you can see some
673 sample Perl applications running on my 3000.
674
675 =back
676
677 October 3, 1997
678
679 =over 4
680
681 =item *
682
683 Added System Requirements section to the Perl/iX home page just so the
684 prerequisites stand out more. Various other home page tweaks.
685
686 =back
687
688 October 2, 1997
689
690 =over 4
691
692 =item *
693
694 Initial public release.
695
696 =back
697
698 September 1997
699
700 =over 4
701
702 =item *
703
704 Porting begins.
705
706 =back
707
708 =head1 AUTHOR
709
710 Mark Bixby, L<http://www.bixby.org/mark/>
711