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