From ff43a9d766baaad355a18af76b61e4ea78eb67f2 Mon Sep 17 00:00:00 2001
From: "James K. Lowden" <jklowden@symas.com>
Date: Mon, 6 May 2024 17:45:53 -0400
Subject: [PATCH] add scripts for RH8 installation
---
gcc/cobol/gcobol.1 | 29 +
gcc/cobol/scripts/migration/README.md | 133 +++++
gcc/cobol/scripts/migration/bin/build-bison | 31 +
.../scripts/migration/bin/configure-gcc-cobol | 130 +++++
.../scripts/migration/bin/prepare-gcc-cobol | 69 +++
gcc/cobol/scripts/migration/migration-guide.1 | 540 ++++++++++++++++++
.../scripts/migration/share/prerequisites | 18 +
7 files changed, 950 insertions(+)
create mode 100644 gcc/cobol/scripts/migration/README.md
create mode 100755 gcc/cobol/scripts/migration/bin/build-bison
create mode 100755 gcc/cobol/scripts/migration/bin/configure-gcc-cobol
create mode 100755 gcc/cobol/scripts/migration/bin/prepare-gcc-cobol
create mode 100644 gcc/cobol/scripts/migration/migration-guide.1
create mode 100644 gcc/cobol/scripts/migration/share/prerequisites
diff --git a/gcc/cobol/gcobol.1 b/gcc/cobol/gcobol.1
index 5f687ce41473..e8019d6fb838 100644
--- a/gcc/cobol/gcobol.1
+++ b/gcc/cobol/gcobol.1
@@ -22,6 +22,7 @@
.Fl main Ns Li = Ns Ar filename:program-id
.Oc
.Op Fl fcobol-exceptions Ar mask
+.Op Fl copyext Ar ext
.Op Fl ffixed-form | Fl ffree-form
.Op Fl findicator-column
.Op Fl finternal-ebcdic
@@ -115,6 +116,34 @@ items are initialized to zero. This option overrides the default with
.It Fl fsyntax-only
Invoke only the parser. Check the code for syntax errors, but don't do
anything beyond that.
+.It Fl copyext Ar ext
+For the CDF directive
+.D1 COPY Ar name
+if
+.Ar name
+is unquoted, several varieties of
+.Ar name
+are tried, as described below under
+.Xr Copybooks Ns .
+The
+.Fl copyext
+option extends the names searched to include
+.Ar ext .
+If
+.Ar ext
+is all uppercase or all lowercase, both forms are tried, with preference given to the one supplied. If
+.Ar ext
+is mixed-case, only that version is tried.
+For example, with
+.D1 Fl copyext Ar .abc
+given the CDF directive
+.D1 COPY name
+.Nm
+will add to possible names searched
+.Ql name.abc
+and
+.Ql name.ABC
+in that order.
.It Fl ffixed-form
Use strict
.Em "Reference Format"
diff --git a/gcc/cobol/scripts/migration/README.md b/gcc/cobol/scripts/migration/README.md
new file mode 100644
index 000000000000..4e1a58f277ab
--- /dev/null
+++ b/gcc/cobol/scripts/migration/README.md
@@ -0,0 +1,133 @@
+# gcobol Configuration and Build Notes
+
+This directory contains data and scripts to assist in building and
+installing gcobol on Linux Rocky 8, which is a proxy for Red Hat 8.
+
+- data: share/prerequisites
+- scripts, in the order they should be run:
+ - bin/prepare-gcc-cobol
+ - bin/build-bison
+ - bin/configure-gcc-cobol
+
+If you decide not to use the scripts directly, we hope you'll find
+them useful as an indication of intention.
+
+## share/prerequisites
+
+The prerequisites file lists the packages needed to make a base Rocky
+8 system ready to build gcobol. Most of the prerequisites
+are
+[GCC requirements](https://gcc.gnu.org/install/prerequisites.html).
+We don't require the full suite of gcc prerequisites because we're
+building only two compilers:
+
+- the C compiler, gcc
+- the COBOL compiler, gcobol
+
+## prepare-gcc-cobol
+
+To update your system, run `bin/prepare-gcc-cobol`. You will need
+superuser privileges because you're installing packages. The script
+reports what is installed, too. If the system is ready, running it as
+non-root will just report what it found.
+
+`bin/prepare-gcc-cobol` read and processes `share/prerequisites`. You
+can change what's installed by changing what's in that file.
+
+Bison is now a required package to build gcc. The bison required to
+build gcobol is newer than the bison provided by the Rocky 8 packages.
+For that reason, `prepare-gcc-cobol` builds bison from source, see next.
+
+## build-bison
+
+This stand-alone script is invoked by `prepare-gcc-cobol` if
+needed. You can also run it yourself, or install bison however you
+like. If you choose to run the script, you may wish first to set the
+environment variable `srcdir`, which determines where the bison
+sources are extracted and built. The default configure arguments are
+used, meaning bison is installed in `/usr/local/bin`.
+
+## configure-gcc-cobol
+
+Once the prerequisites are installed (`prepare-gcc-cobol` reports no
+problems), it's time to run the gcc configure script.
+
+`configure-gcc-cobol` consults several environment variables whose
+defaults you can override if you choose. If the variable is not set, a
+sensible default is used. The most important might be `prefix`: if you
+don't want to install in `/usr/local`, choose another.
+
+Please note that gcc *cannot* be built "in tree"; the object files
+cannot be produced in the same directory as their source files. A
+separate build directory is required. The default for
+`configure-gcc-cobol` is to produce a `build` directory right off the
+source root, which works fine.
+
+### Warning
+
+It is not possible to build any GCC compiler, including gcobol,
+without also building the C compiler. Please keep that in mind when
+deciding the PREFIX and installing the compiler, because you run the
+risk of overwriting the system's base gcc.
+
+## Build
+
+The `configure` script produces a build tree. In addition to the gcc
+directory (which houses the gcobol source files in `gcc/cobol`) there
+are many associated libraries that are used by various compilers in
+the GNU Compiler Collection. These all get built, and many installed,
+because that's how the thing works. Which ones are installed depends
+on which compilers are built, which is controlled by the `--languages`
+configure option.
+
+The first build can take a while because you're building all the
+libraries. It goes faster if you use `make -j12` or similar, depending
+on your machine. Subsequent builds, if you update the sources,
+are much faster.
+
+To kick off the build, something like this will do fine:
+
+ $ cd build
+ $ time make -s -j12 > log
+
+That will finish by producing a little report of how long it
+took. Depending on your compiler, many warning message may scroll by
+as the build proceeds. That is normal; the known way to prevent them
+is to run the configure script with **CFLAGS=-w**.
+
+Errors will of course terminate the build. Provided the above steps
+are taken to prepare the machine, no error is expected.
+
+## Install
+
+The final step is `make install`. Depending on your prefix you may
+need superuser privileges. Remember nothing prevents you, as the
+superuser, from overwriting the system's `gcc` by setting `prefix` to
+`/usr`. Please take care.
+
+In all, just over 1000 files will be installed, including about 200
+from the bison installation. You check specifically in your `prefix` for
+
+ bin/gcobol
+ lib/libgcobol.so
+ share/man/man1/gcobol.1
+
+And of course **command -v gcobol** will confirm the installed
+executable is on the `PATH`.
+
+## Further steps
+
+The installed gcobol manual (`man gcobol`) describes the compiler.
+
+In the source tree, along with file you're currently reading, you will
+find `gcc/cobol/scripts/migration/migration-guide.1`. It describes
+differences between GnuCOBOL and gcobol. To read it, **man**(1)
+accepts a filename argument:
+
+ $ man gcc/cobol/scripts/migration/migration-guide.1
+
+The migration guide is currently not installed by `make install`
+because it's not clear it *should* be. It's usefulness will be assessed over time.
+
+
+
diff --git a/gcc/cobol/scripts/migration/bin/build-bison b/gcc/cobol/scripts/migration/bin/build-bison
new file mode 100755
index 000000000000..f3b51c64db3a
--- /dev/null
+++ b/gcc/cobol/scripts/migration/bin/build-bison
@@ -0,0 +1,31 @@
+#!/bin/sh
+set -e
+
+url=https://ftp.gnu.org/gnu/bison/bison-3.8.2.tar.gz
+
+# This script relies on the following variable and default value:
+#
+# srcdir $HOME/projects/bison where to put the bison source tree
+
+srcdir=${srcdir:-$HOME/projects/bison}
+
+mkdir -p $srcdir
+cd $srcdir
+test -f $(basename $url) ||
+ curl -o $(basename $url) $url
+test -f $(basename $url .gz) ||
+ gunzip $(basename $url)
+pax -r -f $(basename $url .gz)
+
+cd $(basename $url .tar.gz)
+mkdir build
+cd build
+
+echo configuring bison ...
+../configure >log
+make -s
+make -s install
+bison --version
+
+echo "Note: bison source tree was extracted in $srcdir"
+
diff --git a/gcc/cobol/scripts/migration/bin/configure-gcc-cobol b/gcc/cobol/scripts/migration/bin/configure-gcc-cobol
new file mode 100755
index 000000000000..25672cb76f38
--- /dev/null
+++ b/gcc/cobol/scripts/migration/bin/configure-gcc-cobol
@@ -0,0 +1,130 @@
+#!/bin/sh
+set -e
+
+#
+# Configure gcc to build the COBOL compiler, gcobol, from the git repository.
+#
+# The command-line argument may be 'release'. If present, the more
+# complex configure statement is run, see $args_release, below.
+#
+# This script relies on the following variables and default values:
+#
+# srcdir $HOME/projects/gcc where to put gcc source tree
+# branch master+cobol branch to check out from git
+# build build build subdirectory name
+# bootstrap --disable-bootstrap whether to build the bootstrap xgcc
+# prefix /usr/local where to install the outputs
+# languages cobol GCC compilers to build
+#
+# Beware: No matter what, building gcc always means building a C
+# compiler. That is, setting languages=cobol is the same as
+# languages=c,cobol. That means wherever gcobol is installed, there
+# will also be a gcc. If you don't want to overwrite your system's
+# gcc (and you probably don't) set to prefix to something other than
+# the one used by your system. You may also wish to rename/remove the
+# new gcc built and installed by "make install".
+#
+# This script only prepares gcc to be built. To build and install
+# gcobol for real, run "make && make install", as indicated by the
+# final message.
+
+srcdir=${srcdir:-$HOME/projects/gcc}
+branch=${branch:-master+cobol}
+
+if [ ! -d $srcdir/$branch ]
+then
+ mkdir -p $srcdir
+ cd $srcdir
+ git clone https://gitlab.cobolworx.com/COBOLworx/gcc-cobol.git $branch
+fi
+
+cd $srcdir/$branch
+git pull --no-edit origin $(git branch --show-current)
+
+
+VERSION=$(cat gcc/BASE-VER)
+MAJOR_VERSION=$(echo $VERSION | sed 's/^\([0-9]\+\)[.].*$/\1/')
+test "$VERSION"
+
+PKGVERSION="GCOBOL ${VERSION}${COMMIT_VERSION}"
+
+arch=$(arch)
+
+test "$arch"
+if [ $arch = x86_64 ]
+then
+ arch_options='--with-abi=m64 --with-tune=generic --enable-default-pie'
+fi
+
+build=${build:-build}
+
+rm -rf $build
+mkdir -p $build
+cd $build
+
+bootstrap=${bootstrap:---disable-bootstrap}
+
+prefix=${prefix:-/usr/local}
+languages=${languages:-cobol}
+
+args_release="
+ --with-pkgversion="$PKGVERSION"
+ --enable-languages=$languages
+ --prefix=/usr
+ --libdir=/usr/lib/gcobol
+ --libexecdir=/usr/libexec/gcobol
+ --with-gcc-major-version-only
+ --program-suffix=-$MAJOR_VERSION
+ --enable-shared
+ --enable-linker-build-id
+ --without-included-gettext
+ --enable-threads=posix
+ --disable-bootstrap
+ --enable-clocale=gnu
+ --enable-libstdcxx-debug
+ --enable-libstdcxx-time=yes
+ --with-default-libstdcxx-abi=new
+ --enable-gnu-unique-object
+ --disable-vtable-verify
+ --enable-plugin
+ --with-system-zlib
+ --with-target-system-zlib=auto
+ --disable-werror
+ --disable-cet
+ $arch_options
+ --disable-multilib
+ --without-cuda-driver
+ --enable-checking=release
+ --with-build-config=bootstrap-lto-lean
+ --enable-link-mutex --without-isl
+"
+
+args_min="
+ --prefix=$prefix
+ $bootstrap
+ --disable-multilib
+ --enable-checking
+ --enable-languages=$languages
+"
+
+options="$args_min"
+config_type=minimal
+
+if [ "$1" = "release" ]
+then
+ options="$args_release"
+ config_type=release
+fi
+
+set -x
+
+../configure \
+ --build=${arch}-linux-gnu \
+ --host=${arch}-linux-gnu \
+ --target=${arch}-linux-gnu \
+ ${options}
+
+set +x
+
+echo "$config_type configure done, will be installed in $prefix"
+echo now: "cd $PWD && make && make install"
diff --git a/gcc/cobol/scripts/migration/bin/prepare-gcc-cobol b/gcc/cobol/scripts/migration/bin/prepare-gcc-cobol
new file mode 100755
index 000000000000..c07b1a573b2f
--- /dev/null
+++ b/gcc/cobol/scripts/migration/bin/prepare-gcc-cobol
@@ -0,0 +1,69 @@
+#!/bin/sh
+set -e
+
+#
+# Compare the contents of the prerequisites file to the status of the
+# existing system. For each utility or library that is missing,
+# install using yum(8).
+#
+# The exception is Bison. To build gcobol, a newer version of Bison
+# is required than is supplied by the Red Hat 8 package. Bison is
+# built & installed from source using the supplied build-bison script.
+#
+# To avoid security problems, if this script is running as root, it
+# switches to another account, "$user", presumably non-privileged,
+# when building and installing Bison. If that variable is not
+# defined, the script terminates.
+#
+
+# change to script's directory
+cd ${0%/*}
+
+if [ -z "$prerequisites" ]
+then
+ prerequisites=${0%/*}/../share/prerequisites
+fi
+
+grep -v '^#' $prerequisites |
+while read type file pkg
+do
+ case $type in
+ cmd)
+ if [ $file = bison ]
+ then
+ needed="3.8.2"
+ version=$(bison --version |
+ awk -v needed=$needed '/^bison/ {
+ print $NF < needed? $NF : needed }')
+ if [ $version = $needed ]
+ then
+ $file --version | grep -i [^/]$file
+ continue;
+ fi
+ if [ 0 = $(id -u) ]
+ then
+ jkl=$(awk -F: '/^jklowden/ {print $1}' /etc/passwd)
+ user=${user:-$jkl}
+ if [ -z "$user" ]
+ then
+ echo 'bison not installed and "$user" not defined' >&2
+ echo 'error: will not build bison as root' >&2
+ exit 1
+ fi
+ su $user -c ./build-bison
+ else
+ ./build-bison
+ fi
+ continue
+ fi
+ pattern=$(echo $file | sed 's/+/[+]/g')
+ $file --version | grep -Ei [^/]?$pattern || true
+ command -v $file > /dev/null ||
+ yum install -y $pkg
+ ;;
+ lib)
+ find /usr/include/ -name $file ||
+ yum install -y $pkg
+ ;;
+ esac
+done
diff --git a/gcc/cobol/scripts/migration/migration-guide.1 b/gcc/cobol/scripts/migration/migration-guide.1
new file mode 100644
index 000000000000..2772fd755aa3
--- /dev/null
+++ b/gcc/cobol/scripts/migration/migration-guide.1
@@ -0,0 +1,540 @@
+.ds lang COBOL
+.ds gcobol GCC\ \*[lang]\ Front-end
+.Dd \& May 2024
+.Dt GCOBOL MIGRATION GUIDE 7\& "GCC \*[lang] Compiler"
+.Os Linux
+.Sh NAME
+.Nm gcobol-migration
+.Nd feature and option comparison with GnuCOBOL and other \*[lang] compilers
+.
+.Sh DESCRIPTION
+The GCC \*[lang] compiler, gcobol, is a gcc front-end, meaning it
+parses ISO \*[lang] source code and produces executable code using the
+gcc back-end. Because it's a gcc compiler, gcobol accepts all gcc
+options that control code generation and linking. There is a small
+set of options and environment variables unique to gcobol itself.
+.Pp
+Being part of gcc means gcobol works like gcc, and not necessarily how
+other \*[lang] compilers work. This guide describes features of
+GnuCOBOL and gcobol, showing how they are similar and different:
+.Pp
+.Bl -tag -width identical -compact
+.It identical
+The feature has the same effect in both compilers.
+.It mappable
+The feature in one compiler has a similar/matching feature in the other.
+.It unique
+The feature has no comparable feature in the other compiler.
+Sometimes the same or similar effect can be obtained by other means.
+.El
+.
+.Sh COMMAND-LINE OPTIONS
+.Ss Help options
+.Bl -tag -width Identical -compact
+.It Identical
+.Fl Fl help
+.Fl Fl version
+.Fl Fl verbose
+.Fl v
+.Ef
+.It Mappable
+.Bl -column ".Sy GNU\0\0\0\0" ".Sy GCC" -compact
+.It Sy GNU Ta Sy GCC
+.It Fl h Ta Fl Fl help
+.El
+.It GnuCOBOL Only
+.Fl Fl info
+.Fl Fl list-reserved
+.Fl Fl list-intrinsics
+.Fl Fl list-system
+.Fl Fl list-mnemonics
+.El
+.Ss Build target
+.Bl -tag -width Identical -compact
+.It Identical
+.Bl -tag -width "-E" -compact
+.It Fl c
+compile each \*[lang] file to object code. Do not link.
+.It Fl D Ar name Ns = Ns Ar value
+Define CDF user-defined word
+.Ar name
+as representing the string or number
+.Ar value .
+.It Fl E
+gcobol continues with compilation. To prevent compilation, use
+.D1 -preprocess false
+because nonzero status from any preprocessor prevents
+compilation. gcobol also writes to standard output, not to a .i file.
+.It Fl I Ar pathname
+Add
+.Ar pathname
+to the search path for copybooks. If
+.Ar pathname
+does not begin with
+.Ql / ,
+it is interpreted as relative to the current working directory for the
+gcobol process.
+.It Fl L Ar pathname
+Library search path
+.It Fl l Ar libname
+Link with library
+Ar libname .
+.It Fl o Ar filename
+Write the compiled output to
+.Ar filename .
+.It Fl S
+Stop after the stage of compilation proper; do not assemble.
+Output is assembler code file for each non-assembler input file.
+.El
+.It Mappable
+.Bl -column ".Sy GNU" ".Sy GCC" -compact
+.It Sy GNU Ta Sy GCC
+.It Fl m , Fl b Ta Fl shared
+.El
+.It gcobol Only
+.Bl -tag -compact
+.It Fl main Ar filename Ns , Fl nomain
+controls whether a
+.Fn main
+function is generated for
+.Ar filename.
+.El
+.It GnuCOBOL Only
+.Bl -tag -compact
+.It Fl C
+gcobol does not translate to C.
+.It Fl x
+Inapplicable because,
+like gcc, by default gcobol produces an executable binary.
+.It Fl j Fl job
+gcobol has no job control
+.El
+.El
+.
+.Ss Source format
+.Bl -tag -width Identical -compact
+.It Identical
+None identified.
+.It Mappable
+.Bl -column ".Sy GNU\0\0\0\0" ".Sy GCC" -compact
+.It Sy GNU Ta Sy GCC
+.It Fl free , Fl F Ta Fl ffree-form
+.It Fl fixed Ta Fl ffixed-form
+.br
+gcobol truncates lines at column 72,
+i.e. strict Reference Format. For Extended Reference Format, use
+.D1 Fl indicator-column Li 7
+which places the indicator area in its standard position, and imposes
+no line length limit.
+.El
+.It GnuCOBOL Only
+None identified.
+.El
+.
+.Ss Warning options
+.Bl -tag -width Identical -compact
+.It Identical
+.Fl fsyntax-only
+.Fl fmax-errors = Ar N
+.Pp
+The following warning option are not yet implemented, but will be during gcc integration:
+.Fl w
+.Fl Werror
+.Fl Werror Ns = Ns Li WARNING
+.It GnuCOBOL Only
+.Fl Wfatal-errors
+.Fl Wall
+.Fl Wextra Ns , Fl W
+.Fl W Ns Ar WARNING
+.Fl Wno- Ns Ar WARNING
+.Fl Warchaic
+.Fl Wcall-params
+.Fl Wcolumn-overflow
+.Fl Wconstant
+.Fl Wimplicit-define
+.Fl Wlinkage
+.Fl Wobsolete
+.Fl Wparentheses
+.Fl Wredefinition
+.Fl Wstrict-typing
+.Fl Wterminator
+.Fl Wtruncate
+.Fl Wconstant-expression
+.Fl Wconstant-numlit-expression
+.Fl Wunreachable
+.Fl Wadditional
+.El
+.Ss Configuration options
+.Bl -tag -width Identical -compact
+.It Identical
+.It Mappable
+.Bl -column ".Sy GNU\0\0\0\0" ".Sy GCC" -compact
+.It Sy GNU Ta Sy GCC
+.It Fl std Ns = Ns Li mvs Ta Fl dialect Li ibm
+.It Fl std Ns = Ns Li mf Ta Fl dialect Li mf
+.El
+gcobol is an ISO-standard compiler with relatively little support for nonstandard syntax. Some common syntax extensions are supported using the
+.Fl dialect
+option. For details see
+.Xr gcobol 1 .
+.
+.It GnuCOBOL Only
+.Fl std Ns = Ns Li DIALECT
+.Fl std Ns = Ns Li default
+.Fl std Ns = Ns Li cobol85
+.Fl std Ns = Ns Li xopen
+.Fl std Ns = Ns Li cobol2002 , Fl std Ns = Ns Li cobol2014
+.Fl std Ns = Ns Li ibm-strict , Fl std Ns = Ns Li ibm
+.Fl std Ns = Ns Li mvs-strict , Fl std Ns = Ns Li mvs
+.Fl std Ns = Ns Li mf-strict
+.Fl std Ns = Ns Li bs2000-strict , Fl std Ns = Ns Li bs2000
+.Fl std Ns = Ns Li acu-strict , Fl std Ns = Ns Li acu
+.Fl std Ns = Ns Li rm-strict , Fl std Ns = Ns Li rm
+.Fl std Ns = Ns Li realia-strict , Fl std Ns = Ns Li realia
+.Fl std Ns = Ns Li gcos-strict , Fl std Ns = Ns Li gcos
+.Fl freserved-words Ns = Ns Li DIALECT
+.Fl conf Ns = Ns Li <file>
+.Fl febcdic-table Ns = Ns Li CCONV-TABLE/FILE
+.Pp
+GnuCOBOL has numerous specific options controlling acceptable syntax. gcobol has no such options.
+.El
+.
+.Ss Listing options
+gcobol produces no listing file.
+.
+.Ss Debug switches
+.Bl -tag -width Identical -compact
+.It Identical
+.Bl -tag -compact
+.It Fl g
+gcobol supports all forms of the gcc
+.Fl g
+option, including
+.Fl ggdb ,
+which can be very useful.
+.El
+.It Mappable
+.Bl -tag -compact
+.It .Fl O Ns , Fl O2 Ns , Fl \&Os Ns
+It's not clear how exactly to map these GnuCOBOL optimization options.
+gcobol supports the gcc
+.Fl \&O
+options, from
+.Fl O Ns 0
+to
+.Fl O Ns 3 ,
+with
+.Fl O Ns 2
+being perhaps the most commonly used. For debugging,
+.Fl O Ns 0
+(no optimization) probably yields the best experience.
+.It Fl fec Ns = Ns Li exception-name Ns , Fl fno Ns = Ns Li ec Ns = Ns Li exception-name
+In addition to the CDF
+.Sy >>TURN
+directive, gcobol supports
+.Fl fcobol-exceptions Ar mask ,
+where
+.Ar mask
+is hexadecimal number, as described in
+.Xr gcobol 1 .
+.It Fl Fl debug
+maps to
+.Fl d .
+.It Fl fstack-check
+may correspond to the gcc option of the same name.
+.El
+.It gcobol Only
+.Bl -tag -compact
+.It Fl preprocess Ar filter-name
+Between gathering the COBOL source file and copybooks, and sending them to the compiler, this options passes the normalized input through
+.Ar filter-name .
+More than one
+.Fl preprocess
+option can be used; they are applied in order.
+.It Fl fflex-debug Ns , Fl fyacc-debug
+produce messages useful for compiler development.
+.El
+.It GnuCOBOL Only
+.Fl fmemory-check Ns = Ns Li scope
+.Fl fsource-location
+.Fl ftrace
+.Fl ftraceall
+.Fl fdebugging-line
+.Fl fnotrunc
+.Pp
+gcobol has no trace functionality. Any runtime bounds checking is
+enabled via Exception Conditions. gcobol's support for debugging lines
+has not been thoroughly tested. The feature is deprecated in ISO, but
+is still supported by IBM's compiler. If the user needs support for
+such code, the gcobol developers will enable the NIST DB module for testing.
+.El
+.Ss Miscellaneous
+.Bl -tag -width Identical -compact
+.It Mappable
+The GnuCOBOL option
+.Fl save-temps Ns Op = Ns Ar dir
+can be emulated in gcobol using the
+.Ev GCOBOL_TEMPDIR
+environment variable, as described in
+.Xr gcobol 1 .
+.It GnuCOBOL Only
+.Fl ext Ar extension
+.Fl fintrinsics Ns = Ns Op ALL|name Op ,name,...
+.Fl ffold-copy Ns = Ns Li LOWER
+.Fl ffold-copy Ns = Ns Li UPPER
+.Fl fimplicit-init
+.El
+.
+.Sh Multiple Sources
+gcobol treats multiple sources in the way any gcc compiler does.
+Multiple source code files, object files, and libraries may appear on
+the command line. By default they are combined to produce one
+executable. If
+.Fl shared
+is used, the product is a shared object with a
+.Pa \&.so
+extension. If
+.Fl c
+is used, each source file produces a corresponding object file with a
+.Pa \&.o
+extension.
+.Ss Linkage
+As a gcc compiler, gcobol by default links with any libraries at build
+time. This differs from the GnuCOBOL default, which always defers
+.Sy CALL
+for dynamic, runtime resolution. See
+.Fl static-call
+in
+.Xr gcobol 1
+for details. gcobol also differs in how/where the produced executable
+searches for libraries. The conventional (gcc) approach is to link any
+libraries that will be needed. This applies even with
+.Fl no-static-call .
+For the linked library to be found at runtime by the dynamic linker,
+.Xr ld.so 8 ,
+the library must either be
+.Pp
+.Bl -enum -compact
+.It
+in the linker's default search path, or
+.It
+in the executable's RPATH
+.Fl Wl, Ns Ar path .
+.El
+.Pp
+The library search path can be further extended with the environment variables
+.Ev COBPATH ,
+which is specific to gcobol-produced executables, and
+.Ev LD_LIBRARY_PATH ,
+which is a feature of the dynamic linker.
+.
+.Sh C interface
+This section has two parts:
+.Pp
+.Bl -enum -compact
+.It
+how \*[lang] symbols in programs compiled
+with gcobol appear in the object code
+.It how to call C functions
+from a \*[lang] compiled with gcobol
+.El
+.Ss gcobol symbols
+.Pp
+gcobol binaries use ordinary C linkage. Each top-level PROGRAM-ID
+creates a symbol in the object code by the same name. A COBOL Program
+can be called from C as a function, and returns a value to a C caller
+just as a C function does.
+.Pp
+An EXTERNAL data item is manifested in the object code as a name with external linkage, accessible to the linker. A C program may reference it using the
+.Ql extern
+keyword.
+.Pp
+Contained programs and data items not using the EXTERNAL phrase do not
+have external linkage. gcobol has no support for the ENTRY statement.
+.
+.Ss Name mangling
+To facilitate case-insensitive name matches as mandated by the ISO
+standard, all \*[lang] symbol names appear in the object file in
+.Em "lower case" .
+This differs from the GnuCOBOL practice of using upper case symbol names.
+.Pp
+The x64 ABI used by Linux does not allow for hyphens in a symbol name,
+which is restricted to letters, digits, and underscores,
+.Pq regex Bo Bo :alnum: Bc Ns \&_ Bc .
+For this reason, names that include hyphens are
+.Dq mangled .
+The exact algorithm is too tedious to describe here. If you wish to
+access such names from C, though, it is possible. Contact the
+developers for details.
+.Ss Parameters
+In gcobol, program's parameters and return value are always 64-bit
+entities. If a program returns a numeric value, it is returned as a
+64-bit integer or floating point value, (C
+.Vt int64_t
+or
+.Vt double Ns ).
+Strings are always represented by pointers. An OPTIONAL parameter is
+represented by a NULL pointer. There is no way for a C program to
+indicate a missing parameter for which USING BY VALUE is specified.
+.Pp
+gcobol provides no functions for C programs to manipulate \*[lang]
+variables. Intrinsic functions are likewise inaccessible from C
+because their parameters do not follow the above scheme. Because they
+are designed to be called from \*[lang], they are designed to accept
+and return \*[lang] data.
+.
+.Ss Calling C functions from gcobol
+By default, gcobol assumes the target of a CALL statement is a
+\*[lang] program compiled by gcobol. It therefore converts the name
+of the CALL target to lower case (and applies the name-mangling
+algorithm). Also by default, if the target is a compile-time
+constant, static linking is used. That is, the name is manifested in
+the object code as an external reference for the linker to resolve.
+Both these defaults can be changed.
+.Pp
+To prevent a name from being converted to lowercase form, use the CDF
+.D1 >>CALL-CONVENTION VERBATIM
+directive. With that in force, the name provided will be the name
+used, without change. It remains in force until
+.D1 >>CALL-CONVENTION COBOL
+is encountered.
+.Pp
+To prevent static linking, use the command-line option
+.Dl Fl fno-static-call
+With that option, no CALL target is ever manifested as an external reference in the object code. All references are resolved at runtime using
+.Xr dlopen 3
+and
+.Xr dlsym 3 .
+.Pp
+These features are independent. One can have static linking or not
+with either call-convention.
+.Ss How links the linker
+The term
+.Dq "static linking"
+used here can be misleading, and should not be confused with static
+libraries. It means only that a name known at compile time is resolved by
+.Dq "the linker" ,
+not the gcobol runtime library. At build time, the static linker,
+.Xr ld 1 ,
+verifies that each external reference is supplied by a library named
+on the command line. That library
+.Em might
+be a static library, in which case the function (say) is incorporated
+into the produced binary. More commonly the library is a shared
+object, in which case the linker adds the library's name to the set
+required by the produced binary. When the program runs, the runtime linker,
+.Xr ld.so 8 ,
+actually resolves the external symbols from those named libraries.
+.Pp
+For the runtime linker to do its work, it must be able to find those
+libraries. That is where the ELF RPATH comes in. If the library does not reside in the default search path for
+.Xr ld.so 8 ,
+it will inspect directories in the RPATH, a property of the
+executable. In gcc, the RPATH is conventionally set with
+.D1 Fl Wl, Ns Fl rpath Ns = Ns Ar pathname
+The search can be further extended using
+.Ev LD_LIBRARY_PATH
+at time of execution. See
+.Xr ld.so 8
+for more information.
+.
+.Ss Extending runtime linking with Ev COBPATH
+When searching for a CALL target, unlike GnuCOBOL, gcobol assumes no
+relationship between the name of the target the name of the library
+that might house it. Normally, the names of all required libraries are
+defined at build time. Those libraries must be found by the runtime
+linker, and no other libraries are consulted. There is an escape
+hatch, though: the
+.Ev COBPATH
+environment variable.
+.Pp
+As described in
+.Xr gcobol 1 ,
+the value of
+.Ev COBPATH
+is a colon-separated list of directory names. If present, the gcobol runtime library,
+.Pa libgcobol.so ,
+will attempt to resolve a CALL target by searching all libraries in
+each named directory. For example,
+.D1 COBPATH=.
+makes all shared objects in the process's current working directory
+eligible to supply symbols to the program.
+.
+.Sh ENVIRONMENT
+.Ss Compile-time variables
+gcobol recognizes environment variables for copybooks. Given
+.D1 COPY Ar copybook Ar library
+gcobol will examine the environment for variables named
+.Ql copybook ,
+.Ql COPYBOOK ,
+.Ql library ,
+and
+.Ql LIBRARY .
+If found, the values of those variables are used instead of the literal.
+.Pp
+Consistent with gcc practice, gcobol uses no environment variables to
+control the compiler itself, other than a few easter eggs used by the
+developers to display details of the compilation process.
+.Ss Run-time variables
+The environment is consulted at runtime to resolve file names. See
+.Xr FILES
+below.
+.
+.Sh FILES
+gcobol uses no files for configuration.
+.Pp
+Programs compiled by gcobol consult the environment to resolve file names. For
+.D1 SELECT Ar name Li ASSIGN Ar filename
+.Ar filename
+may be a \*[lang] word or an alphanumeric literal. If it is a
+literal, it is interpreted literally; relative paths are interpreted
+as relative to the current working directory of the executing process. If
+.Ar filename
+is a \*[lang] word, the gcobol runtime support queries the environment for
+an uppercase form of the
+.Ar filename .
+If found, the value of the variable is used as the filename, with
+relative paths being interpreted just as literal names are.
+If no environment variable is found,
+.Ar filename
+is treated as a literal.
+.Pp
+The process of interpreting
+.Ar filename
+is performed for each OPEN operation. Although the functionality has
+never been tested, in theory it should be possible to OPEN
+.Ar filename ,
+operate on it, CLOSE it, change the value of
+.Ar filename
+in the environment, and then OPEN a different file.
+.Pp
+No transformation done on the text of
+.Ar filename .
+No prefix is implied and no path is searched.
+.
+.Ss Compatibility
+The on-disk format of files written by programs compiled with gcobol
+is unique to gcobol. They are incompatible with the on-disk format of
+any file system supported by GnuCOBOL. Their sole claim is to support
+the file semantics defined in the ISO standard.
+.Pp
+It is an aspiration of the gcobol developers to provide support for
+I/O plug-in modules in the form of shared objects that implement a
+defined interface.
+.
+.\" .Sh EXAMPLES
+.\" .Sh DIAGNOSTICS
+.\" .Sh COMPATIBILITY
+.Sh SEE ALSO
+.Bl -tag -compact
+.It Xr ld 1
+.It Xr ld.so 8
+.It Xr gcobol 1
+.It GnuCOBOL Programmer’s Guide
+.El
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.\" .Sh CAVEATS
+.\" .Sh BUGS
+
diff --git a/gcc/cobol/scripts/migration/share/prerequisites b/gcc/cobol/scripts/migration/share/prerequisites
new file mode 100644
index 000000000000..57b4502ad18f
--- /dev/null
+++ b/gcc/cobol/scripts/migration/share/prerequisites
@@ -0,0 +1,18 @@
+# This file is processed by the prepare-gcc-cobol script. It lists
+# commands and libraries that must be present to build gcobol, along
+# with known-working versions, if any. The package names are taken
+# from Linux Rocky 8.
+#
+# type filename package
+cmd cc gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-20)
+cmd c++ gcc-c++ (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
+cmd bison bison (GNU Bison) 3.8.2
+cmd flex flex 2.6.4
+cmd make make (GNU Make) 4.3
+cmd git git version 2.34.1
+cmd pax spax
+cmd tar tar
+lib gmp.h gmp-devel
+lib mpfr.h mpfr-devel
+lib mpc.h libmpc-devel
+lib zlib.h zlib
--
GitLab