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