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