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