Update docs for z/OS support

Author: NWilson

NON-AUTOTOOLS-BUILD

@@ -12,7 +12,7 @@ This document contains the following sections:
   Building PCRE2 on Windows with CMake
   Building PCRE2 on Windows with Visual Studio
   Testing with RunTest.bat
-  Building PCRE2 on native z/OS and z/VM
+  Building PCRE2 on z/OS and z/VM
   Building PCRE2 under VMS
 
 
@@ -419,23 +419,47 @@ Otherwise:
 To independently test the just-in-time compiler, run pcre2_jit_test.exe.
 
 
-Building PCRE2 on native z/OS and z/VM
---------------------------------------
+Building PCRE2 on z/OS and z/VM
+-------------------------------
 
 z/OS and z/VM are operating systems for mainframe computers, produced by IBM.
 The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and
-applications can be supported through UNIX System Services, and in such an
-environment it should be possible to build PCRE2 in the same way as in other
-systems, with the EBCDIC related configuration settings, but it is not known if
-anybody has tried this.
-
-In native z/OS (without UNIX System Services) and in z/VM, special ports are
-required. For details, please see file 939 on this web site:
+applications can be supported through UNIX System Services.
+
+The PCRE2 codebase compiles and runs with native EBCDIC support on modern z/OS
+systems, using the pre-installed tools (/bin/sh, ./configure, and the XLC or
+IBM-Clang compilers). PCRE2 supports z/OS using both Autoconf (./configure) and
+CMake (which IBM distributes via "zopen install cmake"). Any EBCDIC codepage
+should work (PCRE2 does not assume or require IBM-1047).
+
+After unpacking the PCRE2 tarball, you must subsequently tag the files as ASCII
+in order for the z/OS shell and compiler to interpret them correctly:
+    chtag -R -tc ISO8859-1 <directory>
+
+Some unusual features on the IBM platform are:
+  - The _ALL_SOURCE macro must be provided. Unlike on Linux or macOS, even quite
+    standard POSIX APIs are not made visible by default. PCRE2's Autoconf and
+    CMake system both provide this for you.
+  - The `cc`, `c89`, and even `c99` compilers provided by IBM do not default to
+    the same argument ordering as other Unix platforms.
+  - The XLC compiler requires `-qhaltonmsg=CCN3296`, otherwise it will treat any
+    preprocessor #include errors as a warning rather than an error. Needless to
+    say this default wrecks Autoconf and CMake's feature-detection tests.
+    PCRE2's build system is aware of this.
+  - The test suite (in the testdata/ directory) is entirely in ASCII/UTF-8.
+    When running the tests, you must ensure that the EBCDIC-native build of
+    pcre2test receives an EBCDIC version of these files. The easiest way to
+    achieve this is via filesystem tagging (chtag). Alternatively, you could
+    manually re-encode the testdata files as EBCDIC, and tag them as EBCDIC.
+    (Latin-1 and EBCDIC are one-to-one convertible encodings, a simple
+    byte-by-byte permutation of the 256 values.)
+
+In native z/OS (without UNIX System Services) and in z/VM, a user has provided a
+special port of PCRE2. For details, please see file 939 on this web site:
 
   http://www.cbttape.org
 
-Everything in that location, source and executable, is in EBCDIC and native
-z/OS file formats. The port provides an API for LE languages such as COBOL and
+The user-provided port also provides an API for LE languages such as COBOL and
 for the z/OS and z/VM versions of the Rexx languages.
 
 
@@ -447,6 +471,10 @@ OpenVMS. They are in the "vms" directory in the distribution tarball. Please
 read the file called vms/openvms_readme.txt. The pcre2test and pcre2grep
 programs contain some VMS-specific code.
 
+This has not been tested for some time. The PCRE2 maintainers would be grateful
+to learn whether it still works (or if anyone still uses it).
+
+
 ===========================
 Last updated: 24 March 2025
 ===========================

README

@@ -88,15 +88,17 @@ Building PCRE2 on non-Unix-like systems
 
 For a non-Unix-like system, please read the file NON-AUTOTOOLS-BUILD, though if
 your system supports the use of "configure" and "make" you may be able to build
-PCRE2 using autotools in the same way as for many Unix-like systems.
+PCRE2 using autotools in the same way as for many Unix-like systems. This file
+also contains useful information on building for some unusual Unix environments
+(such as EBCDIC mainframes).
 
 PCRE2 can also be configured using CMake, which can be run in various ways
 (command line, GUI, etc). This creates Makefiles, solution files, etc. The file
 NON-AUTOTOOLS-BUILD has information about CMake.
 
 PCRE2 has been compiled on many different operating systems. It should be
-straightforward to build PCRE2 on any system that has a Standard C compiler and
-library, because it uses only Standard C functions.
+straightforward to build PCRE2 on any system that has a C99 or later compiler
+and library.
 
 
 Building PCRE2 without using autotools

README.md

@@ -40,7 +40,7 @@ https://pcre2project.github.io/pcre2/
 <th align="left">Testing</th>
 <td>
 
-[![Codecov](https://img.shields.io/codecov/c/github/PCRE2Project/pcre2?style=flat-square&logo=codecov&label=Coverage&color=009400)](https://app.codecov.io/gh/PCRE2Project/pcre2/components)&nbsp;
+[![Codecov](https://img.shields.io/codecov/c/github/PCRE2Project/pcre2?component=library&style=flat-square&logo=codecov&label=Coverage&color=009400)](https://app.codecov.io/gh/PCRE2Project/pcre2/components)&nbsp;
 [![Clang Sanitizers](https://img.shields.io/badge/Clang-Sanitizers-262D3A?style=flat-square&logo=llvm&color=006094)](https://github.com/PCRE2Project/pcre2/actions/workflows/dev.yml)&nbsp;
 [![Clang Static Analyzer](https://img.shields.io/badge/Clang-Static%20Analyzer-262D3A?style=flat-square&logo=llvm&color=006094)](https://github.com/PCRE2Project/pcre2/actions/workflows/clang-analyzer.yml)&nbsp;
 [![Valgrind](https://img.shields.io/badge/Valgrind-006094?style=flat-square)](https://github.com/PCRE2Project/pcre2/actions/workflows/dev.yml)&nbsp;
@@ -53,8 +53,8 @@ https://pcre2project.github.io/pcre2/
 </tr>
 <tr>
 <th align="left">Platforms</th>
-<td>Tested continuously on Linux, Windows, macOS, FreeBSD, Solaris;<br />
-x86, ARM, RISC-V, POWER, S390X; many others known to work
+<td>Tested continuously on Linux, Windows, macOS, FreeBSD, Solaris, z/OS;<br />
+x86, ARM, RISC-V, POWER, S390X; others known to work
 </td>
 </tr>
 </tbody>
@@ -238,7 +238,7 @@ PCRE2 is portable C code, and is likely to work on any system with a C99 compile
 <dl>
 <dt>Operating systems</dt>
 <dd>
-Our continuous integration tests on <strong>Linux</strong> (GCC and Clang, glibc and musl), <strong>Windows</strong> (MSVC and MinGW-x64), and <strong>macOS</strong> (Clang), as well as <strong>FreeBSD</strong>, and <strong>Solaris</strong> (Oracle Studio <code>cc</code>).
+Our continuous integration tests on <strong>Linux</strong> (GCC and Clang, glibc and musl), <strong>Windows</strong> (MSVC and MinGW-x64), and <strong>macOS</strong> (Clang), as well as <strong>FreeBSD</strong>, <strong>Solaris</strong> (Oracle Studio <code>cc</code>), and <strong>z/OS</strong> (<code>xlc</code> and <code>ibm-clang</code>).
 </dd>
 <dt>Processors</dt>
 <dd>

doc/html/NON-AUTOTOOLS-BUILD.txt

@@ -12,7 +12,7 @@ This document contains the following sections:
   Building PCRE2 on Windows with CMake
   Building PCRE2 on Windows with Visual Studio
   Testing with RunTest.bat
-  Building PCRE2 on native z/OS and z/VM
+  Building PCRE2 on z/OS and z/VM
   Building PCRE2 under VMS
 
 
@@ -419,23 +419,47 @@ Otherwise:
 To independently test the just-in-time compiler, run pcre2_jit_test.exe.
 
 
-Building PCRE2 on native z/OS and z/VM
---------------------------------------
+Building PCRE2 on z/OS and z/VM
+-------------------------------
 
 z/OS and z/VM are operating systems for mainframe computers, produced by IBM.
 The character code used is EBCDIC, not ASCII or Unicode. In z/OS, UNIX APIs and
-applications can be supported through UNIX System Services, and in such an
-environment it should be possible to build PCRE2 in the same way as in other
-systems, with the EBCDIC related configuration settings, but it is not known if
-anybody has tried this.
-
-In native z/OS (without UNIX System Services) and in z/VM, special ports are
-required. For details, please see file 939 on this web site:
+applications can be supported through UNIX System Services.
+
+The PCRE2 codebase compiles and runs with native EBCDIC support on modern z/OS
+systems, using the pre-installed tools (/bin/sh, ./configure, and the XLC or
+IBM-Clang compilers). PCRE2 supports z/OS using both Autoconf (./configure) and
+CMake (which IBM distributes via "zopen install cmake"). Any EBCDIC codepage
+should work (PCRE2 does not assume or require IBM-1047).
+
+After unpacking the PCRE2 tarball, you must subsequently tag the files as ASCII
+in order for the z/OS shell and compiler to interpret them correctly:
+    chtag -R -tc ISO8859-1 <directory>
+
+Some unusual features on the IBM platform are:
+  - The _ALL_SOURCE macro must be provided. Unlike on Linux or macOS, even quite
+    standard POSIX APIs are not made visible by default. PCRE2's Autoconf and
+    CMake system both provide this for you.
+  - The `cc`, `c89`, and even `c99` compilers provided by IBM do not default to
+    the same argument ordering as other Unix platforms.
+  - The XLC compiler requires `-qhaltonmsg=CCN3296`, otherwise it will treat any
+    preprocessor #include errors as a warning rather than an error. Needless to
+    say this default wrecks Autoconf and CMake's feature-detection tests.
+    PCRE2's build system is aware of this.
+  - The test suite (in the testdata/ directory) is entirely in ASCII/UTF-8.
+    When running the tests, you must ensure that the EBCDIC-native build of
+    pcre2test receives an EBCDIC version of these files. The easiest way to
+    achieve this is via filesystem tagging (chtag). Alternatively, you could
+    manually re-encode the testdata files as EBCDIC, and tag them as EBCDIC.
+    (Latin-1 and EBCDIC are one-to-one convertible encodings, a simple
+    byte-by-byte permutation of the 256 values.)
+
+In native z/OS (without UNIX System Services) and in z/VM, a user has provided a
+special port of PCRE2. For details, please see file 939 on this web site:
 
   http://www.cbttape.org
 
-Everything in that location, source and executable, is in EBCDIC and native
-z/OS file formats. The port provides an API for LE languages such as COBOL and
+The user-provided port also provides an API for LE languages such as COBOL and
 for the z/OS and z/VM versions of the Rexx languages.
 
 
@@ -447,6 +471,10 @@ OpenVMS. They are in the "vms" directory in the distribution tarball. Please
 read the file called vms/openvms_readme.txt. The pcre2test and pcre2grep
 programs contain some VMS-specific code.
 
+This has not been tested for some time. The PCRE2 maintainers would be grateful
+to learn whether it still works (or if anyone still uses it).
+
+
 ===========================
 Last updated: 24 March 2025
 ===========================

doc/html/README.txt

@@ -88,15 +88,17 @@ Building PCRE2 on non-Unix-like systems
 
 For a non-Unix-like system, please read the file NON-AUTOTOOLS-BUILD, though if
 your system supports the use of "configure" and "make" you may be able to build
-PCRE2 using autotools in the same way as for many Unix-like systems.
+PCRE2 using autotools in the same way as for many Unix-like systems. This file
+also contains useful information on building for some unusual Unix environments
+(such as EBCDIC mainframes).
 
 PCRE2 can also be configured using CMake, which can be run in various ways
 (command line, GUI, etc). This creates Makefiles, solution files, etc. The file
 NON-AUTOTOOLS-BUILD has information about CMake.
 
 PCRE2 has been compiled on many different operating systems. It should be
-straightforward to build PCRE2 on any system that has a Standard C compiler and
-library, because it uses only Standard C functions.
+straightforward to build PCRE2 on any system that has a C99 or later compiler
+and library.
 
 
 Building PCRE2 without using autotools