VM/ESA updates.

[perl5.git] / README.vmesa

diff --git a/README.vmesa b/README.vmesa
new file mode 100644 (file)
index 0000000..a6bb96b
--- /dev/null
+++ b/README.vmesa
@@ -0,0 +1,76 @@
+README.vmesa
+
+This is a fully ported perl for VM/ESA 2.3.0.  It may work on
+other versions, but that's the one we've tested it on.
+
+If you've downloaded the binary distribution, it needs to be
+installed below /usr/local.  Source code distributions have an
+automated `make install` step that means you do not need to extract
+the source code below /usr/local (though that is where it will be
+installed by default).  You may need to worry about the networking
+configuration files discussed in the last bullet below.
+
+To extract an ASCII tar archive on VM/ESA, try this:
+
+   pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
+
+GNU make for VM/ESA, which may be required for the build of perl,
+is available from:
+
+  http://pucc.princeton.edu/~neale/vmoe.html
+
+Once you've unpacked the distribution, run Configure (see INSTALL for
+full discussion of the Configure options), and then run make, then
+"make test" then "make install" (this last step may require UID=0
+privileges)
+
+There is a "hints" file for vmesa that specifies the correct values
+for most things.  Some things to watch out for are
+
+       - this port does support dynamic loading but it's not had much testing
+
+       - Don't turn on the compiler optimization flag "-O".  There's
+         a bug in the compiler (APAR PQ18812) that generates some bad code
+         the optimizer is on.
+
+       - As VM/ESA doesn't fully support the fork() API programs relying on
+         this call will not work. I've replaced fork()/exec() with spawn()
+         and the standalone exec() with spawn(). This has a side effect when
+         opening unnamed pipes in a shell script: there is no child process
+         generated under.
+
+       - At the moment the hints file for VM/ESA basically bypasses all of the
+         automatic configuration process. This is because Configure relies on:
+         1. The header files living in the Byte File System (you could put the
+            there if you want;
+         2. The C preprocessor including the #include statements in the
+            preprocessor output (.i) file.
+       
+When using perl on VM/ESA please keep in mind that the EBCDIC and ASCII
+character sets are different.  Perl builtin functions that may behave
+differently under EBCDIC are mentioned in the perlport.pod document.
+
+OpenEdition (UNIX System Services) does not (yet) support the #! means
+of script invokation.
+See:
+
+    head `whence perldoc`
+
+for an example of how to use the "eval exec" trick to ask the shell to
+have perl run your scripts for you.
+
+If you are interested in the VM and OS/390 ports of perl then see the
+perl-mvs mailing list: The Perl Institute (http://www.perl.org/)
+maintains a mailing list of interest to all folks building and/or
+using perl on EBCDIC platforms.  To subscibe, send a message of:
+
+    subscribe perl-mvs
+
+to majordomo@perl.org.
+
+Regression tests: as the 5.005 kit was was being assembled
+the following "failures" were known to appear on some machines
+during `make test` (mostly due to ASCII vs. EBCDIC conflicts),
+your results may differ:
+
+[the list of failures being compiled]