lib/perl5/5.6.1/pods/perlmpeix.pod

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