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