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