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