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