The following set of patches update gcc documentation to include the
COBOL front end. I have tried to follow the style.
The order of appearance of the supported languages in various places
looks inconsistent to me. I don't *think* they occur in the order they
were implemented, which in any case is no service to the reader. And
they're definitely not in alphabetical order, but kinda. (If that's a
TLC issue that no one has gotten around to, I'm happy give it a try
later.) I took the liberty of adding COBOL after the C family.
It feels funny to add my own name, but I guess somebody has to.
--jkl
>From 71aca801f6dc5f6c2ea19044755f01a09742e7db Fri 21 Feb 2025 12:15:18 PM EST
From: "James K. Lowden" <jklow...@symas.com>
Date: Fri 21 Feb 2025 12:15:18 PM EST
Subject: [PATCH] COBOL inf: info updates for gcobol
gcc/doc/ChangeLog
* doc/contrib.texi: Add Dubner & Lowden.
* doc/frontends.texi: Mention COBOL, sort names.
* doc/install.texi: Document gcobol prerequisites.
* doc/invoke.texi: COBOL source code file extensions.
* doc/sourcebuild.texi: Add libgcobol runtime library.
* doc/standards.texi: Cite ISO as COBOL standard.
---
gcc/doc/contrib.texi | ++++++++-
gcc/doc/frontends.texi | ++++++++---------
gcc/doc/install.texi |
++++++++++++++++++++++++++++++++++++++++++++++++++++----------------
gcc/doc/invoke.texi | +++++++-
gcc/doc/sourcebuild.texi | +++-
gcc/doc/standards.texi | +++++++
6 files changed, 85 insertions(+), 29 deletions(-)
diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi
index 10dc64350d2..17e088845ea 100644
--- a/gcc/doc/contrib.texi
+++ b/gcc/doc/contrib.texi
@@ -268,6 +268,10 @@ libraries including for all kinds of C interface issues,
contributing and
maintaining @code{complex<>}, sanity checking and disbursement, configuration
architecture, libio maintenance, and early math work.
+@item
+Robert J. Dubner for his work on the COBOL front end, mating the
+parser output to the GENERIC tree.
+
@item
Fran@,{c}ois Dumont for his work on libstdc++-v3, especially maintaining and
improving @code{debug-mode} and associative and unordered containers.
@@ -604,6 +608,10 @@ many other diagnostics fixes and improvements.
Dave Love for his ongoing work with the Fortran front end and
runtime libraries.
+@item
+James K. Lowden for his work on the COBOL front end, mainly the parser
+and CDF.
+
@item
Martin von L@"owis for internal consistency checking infrastructure,
various C++ improvements including namespace support, and tons of
diff --git a/gcc/doc/frontends.texi b/gcc/doc/frontends.texi
index 73c222c9b0b..acd05941856 100644
--- a/gcc/doc/frontends.texi
+++ b/gcc/doc/frontends.texi
@@ -31,23 +31,23 @@ The language-independent component of GCC includes the
majority of the
optimizers, as well as the ``back ends'' that generate machine code for
various processors.
-@cindex COBOL
@cindex Mercury
The part of a compiler that is specific to a particular language is
called the ``front end''. In addition to the front ends that are
integrated components of GCC, there are several other front ends that
-are maintained separately. These support languages such as
-Mercury, and COBOL@. To use these, they must be built together with
-GCC proper.
+are maintained separately. These support languages such as Mercury.
+To use these, they must be built together with GCC proper.
+@cindex Ada
@cindex C++
+@cindex COBOL
@cindex G++
-@cindex Ada
@cindex GNAT
Most of the compilers for languages other than C have their own names.
-The C++ compiler is G++, the Ada compiler is GNAT, and so on. When we
-talk about compiling one of those languages, we might refer to that
-compiler by its own name, or as GCC@. Either is correct.
+The C++ compiler is G++, the COBOL compiler is gcobol, the Ada
+compiler is GNAT, and so on. When we talk about compiling one of
+those languages, we might refer to that compiler by its own name, or
+as GCC@. Either is correct.
@cindex compiler compared to C++ preprocessor
@cindex intermediate C version, nonexistent
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 3b9f56b0529..1fdc109183c 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -291,11 +291,39 @@ Ada runtime libraries. You can check that your build
environment is clean
by verifying that @samp{gnatls -v} lists only one explicit path in each
section.
+@cindex cobol
+@item @anchor{GCOBOL-prerequisite}GCOBOL
+
+The COBOL compiler, gcobol, first appeared in GCC 15. To build the
+COBOL parser, you need GNU Bison 3.5.1 or later (but not 3.8.0). To build
+the lexer requires GNU Flex 2.6.4, the current version as of this writing,
+released on 2017-05-06.
+
+The gcobol documentation is maintained as manpages using troff
+mdoc. GNU groff is required to convert them to PDF format. Conversion
+to HTML is done with mandoc, available at
+@uref{http://mdocml.bsd.lv/}.
+
+Because ISO COBOL defines strict requirements for numerical precision,
+gcobol requires hardware with 128-bit computation instructions. This
+requirement applies to both host and target. For integer and
+fixed-point computation, gcobol uses
+@deftp {Data type} __int128
+@end deftp
+meaning @code{16 == sizeof(long long int)}.
+For floating point, gcobol uses
+@deftp {Data type} _Float128
+@end deftp
+(On some architectures, GCC supports 128-bit floating point in software.)
+
+gcobol has so far been tested on two architectures only: x86_64 and
+aarch64 with little-endian encoding.
+
@item @anchor{GDC-prerequisite}GDC
-In order to build GDC, the D compiler, you need a working GDC
-compiler (GCC version 9.4 or later) and D runtime library,
-@samp{libphobos}, as the D front end is written in D.
+In order to build GDC, the D compiler, you need a working GDC compiler
+(GCC version 9.4 or later) and D runtime library, @samp{libphobos}, as
+the D front end is written in D.
Versions of GDC prior to 12 can be built with an ISO C++11 compiler, which can
then be installed and used to bootstrap newer versions of the D front end.
@@ -568,6 +596,14 @@ Necessary to build GCC during development because the
generated output
files are not included in the version-controlled source repository.
They are included in releases.
+@item Bison version 3.5.1 or later (but not 3.8.0)
+
+Necessary when modifying @file{*.y} files in the COBOL front end.
+
+Necessary to build GCC during development because the generated output
+files are not included in the version-controlled source repository.
+They are included in releases.
+
@item Texinfo version 4.7 (or later)
Necessary for running @command{makeinfo} when modifying @file{*.texi}
@@ -644,13 +680,14 @@ HTTPS as tarballs compressed with @command{gzip} or
@command{bzip2}.
Please refer to the @uref{https://gcc.gnu.org/releases.html,,releases web page}
for information on how to obtain GCC@.
-The source distribution includes the Ada, C, C++, Objective-C, D (GCC 9
-and later), Fortran, Go, and Modula-2 (GCC 13 and later) compilers, as
-well as runtime libraries for C++, Objective-C, and Fortran.
-For previous versions these were downloadable as separate components such
-as the core GCC distribution, which included the C language front end and
-shared components, and language-specific distributions including the
-language front end and the language runtime (where appropriate).
+The source distribution includes the Ada, C, C++, Objective-C, COBOL
+(GCC 15 and later), D (GCC 9 and later), Fortran, Go, and Modula-2
+(GCC 13 and later) compilers, as well as runtime libraries for C++,
+Objective-C, COBOL, and Fortran. For previous versions these were
+downloadable as separate components such as the core GCC distribution,
+which included the C language front end and shared components, and
+language-specific distributions including the language front end and
+the language runtime (where appropriate).
If you also intend to build binutils (either to upgrade an existing
installation or for use in place of the corresponding tools of your
@@ -2049,13 +2086,13 @@ their runtime libraries should be built. For a list of
valid values for
grep ^language= */config-lang.in
@end smallexample
Currently, you can use any of the following:
-@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++}, @code{d},
-@code{fortran}, @code{go}, @code{jit}, @code{lto}, @code{m2},
-@code{objc}, @code{obj-c++}.
+@code{all}, @code{default}, @code{ada}, @code{c}, @code{c++},
+@code{cobol}, @code{d}, @code{fortran}, @code{go}, @code{jit},
+@code{lto}, @code{m2}, @code{objc}, @code{obj-c++}.
Building the Ada compiler has special requirements, see below.
If you do not pass this flag, or specify the option @code{default}, then the
default languages available in the @file{gcc} sub-tree will be configured.
-Ada, D, Go, Jit, Objective-C++ and Modula-2 are not default languages.
+Ada, COBOL, D, Go, Jit, Objective-C++ and Modula-2 are not default languages.
LTO is not a
default language, but is built by default because @option{--enable-lto} is
enabled by default. The other languages are default languages. If
@@ -2292,7 +2329,7 @@ canadian cross build. The @option{--disable-nls} option
disables NLS@.
Note that this functionality requires either libintl (provided by GNU
gettext) or C standard library that contains support for gettext (such
as the GNU C Library).
-@xref{with-included-gettext,,--with-included-gettext} for more
+@xref{with-included-gettext,,--with-included-gettext}, for more
information on the conditions required to get gettext support.
@item --with-libintl-prefix=@var{dir}
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 9050ffa59dd..4196f22f9ea 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1639,6 +1639,12 @@ Free form Fortran source code that should not be
preprocessed.
Free form Fortran source code that must be preprocessed (with the
traditional preprocessor).
+@item @var{file}.cob
+@item @var{file}.COB
+@item @var{file}.cbl
+@item @var{file}.CBL
+COBOL source code.
+
@item @var{file}.go
Go source code.
@@ -1694,6 +1700,7 @@ objective-c objective-c-header objective-c-cpp-output
objective-c++ objective-c++-header objective-c++-cpp-output
assembler assembler-with-cpp
ada
+cobol
d
f77 f77-cpp-input f95 f95-cpp-input
go
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index 98ede70f23c..11ae4e90138 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -94,6 +94,9 @@ The @code{libffi} library, used as part of the Go runtime
library.
@item libgcc
The GCC runtime library.
+@item libgcobol
+The COBOL runtime library.
+
@item libgfortran
The Fortran runtime library.
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
index a8e95136baf..bbae3501a54 100644
--- a/gcc/doc/standards.texi
+++ b/gcc/doc/standards.texi
@@ -336,6 +336,13 @@ The authoritative manual on Objective-C 2.0 is available
from Apple:
For more information concerning the history of Objective-C that is
available online, see @uref{https://gcc.gnu.org/readings.html}
+@cindex COBOL
+@section COBOL Language
+
+As of the GCC 15 release, GCC supports the ISO COBOL language standard
+(ISO/IEC 1989:2023). It includes some support for compatibility with
+other COBOL compilers via the @option{-dialect} option.
+
@section Go Language
As of the GCC 4.7.1 release, GCC supports the Go 1 language standard,
