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