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/ ), 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 MPE requires GETPRIVMODE() in order to setuid().  There are too many
 437 calls to setuid() within Perl/iX, so I have not attempted an automatic
 438 GETPRIVMODE() solution similar to bind().
 439
 440 =back
 441
 442 =head1 Known Perl/iX Bugs Under Investigation
 443
 444 None.
 445
 446 =head1 Perl/iX To-Do List
 447
 448 =over 4
 449
 450 =item *
 451
 452 Make setuid()/setgid() support work.
 453
 454 =item *
 455
 456 Make sure that fcntl() against a socket descriptor is redirected to sfcntl().
 457
 458 =item *
 459
 460 Add support for Berkeley DB once I've finished porting Berkeley DB.
 461
 462 =item *
 463
 464 Write an MPE XS extension library containing miscellaneous important
 465 MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl().
 466
 467 =back
 468
 469 =head1 Perl/iX Change History
 470
 471 May 6, 1999
 472
 473 =over 4
 474
 475 =item *
 476
 477 Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent
 478 Perl/iX from dying with an unresolved external reference to _getenv_libc.
 479
 480 =back
 481
 482 April 7, 1999
 483
 484 =over 4
 485
 486 =item *
 487
 488 Updated to version 5.005_03.
 489
 490 =item *
 491
 492 The official source distribution once again compiles "straight out
 493 of the box" for MPE.
 494
 495 =item *
 496
 497 The current incarnation of the 5.5 POSIX filename extended
 498 characters patch is now MPEKX40B.
 499
 500 =item *
 501
 502 The LIBSHP3K *.a -> *.sl library conversion script is now included
 503 as /PERL/PUB/LIBSHP3K.
 504
 505 =back
 506
 507 November 20, 1998
 508
 509 =over 4
 510
 511 =item *
 512
 513 Updated to version 5.005_02.
 514
 515 =item *
 516
 517 Fixed a DynaLoader bug that was unable to load symbols from relative
 518 path name libraries.
 519
 520 =item *
 521
 522 Fixed a .xs compilation bug where the mpeixish.sh include file wasn't
 523 being installed into the proper directory.
 524
 525 =item *
 526
 527 All bugfixes will be submitted back to the official Perl developers.
 528
 529 =item *
 530
 531 The current incarnation of the POSIX filename extended characters
 532 patch is now MPEKXJ3A.
 533
 534 =back
 535
 536 August 14, 1998
 537
 538 =over 4
 539
 540 =item *
 541
 542 The previous POSIX filename extended characters patch MPEKX44C has
 543 been superseded by MPEKXB5A.
 544
 545 =back
 546
 547 August 7, 1998
 548
 549 =over 4
 550
 551 =item *
 552
 553 The previous POSIX filename extended characters patch MPEKX76A has
 554 been superseded by MPEKX44C.
 555
 556 =back
 557
 558 July 28, 1998
 559
 560 =over 4
 561
 562 =item *
 563
 564 Updated to version 5.005_01.
 565
 566 =back
 567
 568 July 23, 1998
 569
 570 =over 4
 571
 572 =item *
 573
 574 Updated to version 5.005 (production release).  The public
 575 freeware sources are now 100% MPE-ready "straight out of the box".
 576
 577 =back
 578
 579 July 17, 1998
 580
 581 =over 4
 582
 583 =item *
 584
 585 Updated to version 5.005b1 (public beta release).  The public
 586 freeware sources are now 99.9% MPE-ready.  By installing and
 587 testing this beta on your own HP3000, you will be helping to
 588 insure that the final release of 5.005 will be 100% MPE-ready and
 589 100% bug free.
 590
 591 =item *
 592
 593 My MPE binary release is now extracted using my standard INSTALL script.
 594
 595 =back
 596
 597 July 15, 1998
 598
 599 =over 4
 600
 601 =item *
 602
 603 Changed startperl to #!/PERL/PUB/perl so that Perl will recognize
 604 scripts more easily and efficiently.
 605
 606 =back
 607
 608 July 8, 1998
 609
 610 =over 4
 611
 612 =item *
 613
 614 Updated to version 5.004_70 (internal developer release) which is now
 615 MPE-ready.  The next public freeware release of Perl should compile
 616 "straight out of the box" on MPE.  Note that this version of Perl/iX
 617 was strictly internal to me and never publicly released.  Note that
 618 [21]BIND/iX is now required (well, the include files and libbind.a) if
 619 you wish to compile Perl/iX.
 620
 621 =back
 622
 623 November 6, 1997
 624
 625 =over 4
 626
 627 =item *
 628
 629 Updated to version 5.004_04.  No changes in MPE-specific functionality.
 630
 631 =back
 632
 633 October 16, 1997
 634
 635 =over 4
 636
 637 =item *
 638
 639 Added Demos section to the Perl/iX home page so you can see some
 640 sample Perl applications running on my 3000.
 641
 642 =back
 643
 644 October 3, 1997
 645
 646 =over 4
 647
 648 =item *
 649
 650 Added System Requirements section to the Perl/iX home page just so the
 651 prerequisites stand out more. Various other home page tweaks.
 652
 653 =back
 654
 655 October 2, 1997
 656
 657 =over 4
 658
 659 =item *
 660
 661 Initial public release.
 662
 663 =back
 664
 665 September 1997
 666
 667 =over 4
 668
 669 =item *
 670
 671 Porting begins.
 672
 673 =back
 674
 675 =head1 AUTHOR
 676
 677 Mark Bixby, mark@bixby.org
 678