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