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