Re: Ada documentation issues

[Florian Weimer <fw at deneb dot enyo dot de>]

"Joseph S. Myers" <jsm28@cam.ac.uk> writes:

> * gcc/doc/install.texi needs updating: both to include ada in the list
> of valid --enable-languages values, and to document exactly what needs
> to be preinstalled in order to build the Ada front end.  As long as
> there is a separate "make gnatlib_and_tools", this also needs to be
> documented in install.texi.

I've summed up the situation after the einfo.h and sinfo.h had been
added.

> * gcc/doc/gcc.texi should be updated, both in the chapter "Compile C,
> C++, Objective C, Fortran, Java or CHILL" and in "Language Standards
> Supported by GCC" (the latter possibly pointing to where the GNU Ada
> documentation describes Ada standards and GNAT's relation to them).

I think that's the GNAT Reference Manual.  A reference to the GNAT
User Guide (which documents how to use the GNAT toolchain) should be
added somewhere, too.

> * gcc/doc/invoke.texi should have documentation added for suffixes for
> Ada source files and for whatever -x language options there are for
> Ada.

gcc no longer recognizes .ada (see gcc/ada/lang-specs.h), therefore
only .ad[sb] is documented.


Still open (obviously):

> * The front end should have a proper manual, distributed in the ada
> directory.  Once this is done, I will attend to updating
> update_web_docs and onlinedocs/index.html to have that manual
> available online.

> * gcc/doc/contrib.texi should have GNU Ada contributors listed.

> * Some more GNU Ada maintainers may need adding to MAINTAINERS.

Patch:

Index: gcc.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/doc/gcc.texi,v
retrieving revision 1.36
diff -u -r1.36 gcc.texi
--- gcc.texi	2001/08/30 20:44:50	1.36
+++ gcc.texi	2001/10/06 11:00:56
@@ -292,16 +292,17 @@
 
 @ifset USING
 @node G++ and GCC
-@chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
+@chapter Compile C, C++, Objective-C, Fortran, Java, CHILL or Ada
 
 @cindex Objective-C
 @cindex Fortran
 @cindex Java
 @cindex CHILL
-Several versions of the compiler (C, C++, Objective-C, Fortran, Java
-and CHILL) are integrated; this is why we use the name
+@cindex Ada
+Several versions of the compiler (C, C++, Objective-C, Fortran, Java,
+CHILL, and Ada) are integrated; this is why we use the name
 ``GNU Compiler Collection''.  GCC can compile programs written in any of these
-languages.  The Fortran, CHILL, and Java compilers are described in
+languages.  The Fortran, CHILL, Java, and Ada compilers are described in
 separate manuals.
 
 @cindex GCC
@@ -317,12 +318,17 @@
 it ``GCC'' no matter what the language context; however, the term
 ``G++'' is more useful when the emphasis is on compiling C++ programs.
 
+@cindex Ada
+@cindex GNAT
+Similarly, when we talk about Ada compilation, we usually call the
+compiler ``GNAT'', for the same reasons.
+
 We use the name ``GCC'' to refer to the compilation system as a
 whole, and more specifically to the language-independent part of the
 compiler.  For example, we refer to the optimization options as
 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
 
-Front ends for other languages, such as Ada 95 and Pascal exist but
+Front ends for other languages, such as Mercury and Pascal exist but
 have not yet been integrated into GCC@.  These front ends, like that for C++,
 are built in subdirectories of GCC and link to it.  The result is an
 integrated compiler that can compile programs written in C, C++,
@@ -517,6 +523,10 @@
 
 @xref{References,,Language Definition References, chill, GNU Chill},
 for details of the CHILL standard.
+
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, 
+GNAT Reference Manual}, for information on standard
+conformance and compatibility of the Ada compiler.
 
 @include invoke.texi
 
Index: install.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/doc/install.texi,v
retrieving revision 1.68
diff -u -r1.68 install.texi
--- install.texi	2001/09/25 21:17:34	1.68
+++ install.texi	2001/10/06 11:01:01
@@ -629,12 +629,13 @@
 @var{langN} you can issue the following command in the
 @file{gcc} directory of your GCC source tree:@*
 @example
-grep language= */config-lang.in
+grep ^language= */config-lang.in
 @end example
 Currently, you can use any of the following:
-@code{c}, @code{c++}, @code{f77}, @code{java} and @code{objc}.
+@code{c}, @code{c++}, @code{f77}, @code{java}, @code{objc} and @code{ada}.
 @code{CHILL} is not currently maintained, and will almost
-certainly fail to compile.@*
+certainly fail to compile.  Building the Ada compiler has special
+requirements, see below.@*
 If you do not pass this flag, all languages available in the @file{gcc}
 sub-tree will be configured.  Re-defining @code{LANGUAGES} when calling
 @samp{make bootstrap} @strong{does not} work anymore, as those
@@ -764,7 +765,8 @@
 runtime libraries.
 
 We @strong{highly} recommend that GCC be built using GNU make;
-other versions may work, then again they might not.
+other versions may work, then again they might not.  
+GNU make is required for compiling GNAT, the Ada compiler.
 
 (For example, many broken versions of make will fail if you use the
 recommended setup where @var{objdir} is different from @var{srcdir}.
@@ -920,6 +922,36 @@
 when building GCC@.  You can use a bigger number instead of two if
 you like.  In most cases, it won't help to use a number bigger than
 the number of processors in your machine.
+
+@section Building the Ada compiler
+
+In order to build GNAT, the Ada compiler, you need a working GNAT
+compiler, since the Ada frontend is written in Ada (with some
+GNAT-specific extensions), and GNU make.
+
+However, not a full installation of GNAT is required, you only need the
+GNAT binary @file{gnat1}, a copy of @file{gnatbind}, and an compiler
+driver which can deal with both C and Ada input (the latter by invoking
+the @file{gnat1} binary).  A working run-time library installation is
+@emph{not} required.  You have to specify this compiler driver by
+setting the @env{CC} environment variable at the configure step.
+
+At the moment, the GNAT library and several tools for GNAT are not built
+by @samp{make bootstrap}.  You have to invoke 
+@samp{make gnatlib_and_tools} in the @file{@var{objdir}/gcc}
+subdirectory before proceeding with the next steps.
+
+For example, you can build a native Ada compiler by issuing the
+following commands (assuming @code{make} is GNU make):
+
+@example
+    cd @var{objdir}
+    CC=@var{gcc-with-ada} @var{srcdir}/configure --enable-languages=c,ada 
+    make bootstrap
+    cd gcc
+    make gnatlib_and_tools
+    cd ..
+@end example
 
 @html
 <hr>
Index: invoke.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/doc/invoke.texi,v
retrieving revision 1.59
diff -u -r1.59 invoke.texi
--- invoke.texi	2001/10/02 23:15:54	1.59
+++ invoke.texi	2001/10/06 11:01:16
@@ -697,11 +697,18 @@
 @c @var{file}.zip
 @c @var{file}.jar
 
+@item @var{file}.ads
+Ada source code file which contains a library unit declaration (a
+declaration of a package, subprogram, or generic, or a generic
+instantiation), or a library unit renaming declaration (a package,
+generic, or subprogram renaming declaration).  These files are also
+called @dfn{specs}.
+
+@itemx @var{file}.adb
+Ada source code file containing a library unit body (a subprogram or
+package body).  These files are also called @dfn{bodies}.
+
 @c GCC also knows about some suffixes for languages not yet included:
-@c Ada:
-@c @var{file}.ads
-@c @var{file}.adb
-@c @var{file}.ada
 @c Pascal:
 @c @var{file}.p
 @c @var{file}.pas
@@ -736,7 +743,7 @@
 objective-c  objc-cpp-output
 assembler  assembler-with-cpp
 f77  f77-cpp-input  ratfor
-java  chill
+java  chill  ada
 @end example
 @c Also f77-version, for internal use only.