From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1914) id 7B4BD3858010; Mon, 4 Oct 2021 08:47:54 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7B4BD3858010 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Pierre-Marie de Rodat To: gcc-cvs@gcc.gnu.org Subject: [gcc r12-4116] [Ada] Adjust documentation of -fdump-ada-spec in GNAT UG X-Act-Checkin: gcc X-Git-Author: Eric Botcazou X-Git-Refname: refs/heads/master X-Git-Oldrev: 43a59d4dc88db02b7e19a1edf73db1b1f9d890b1 X-Git-Newrev: 6109bcaf72f86d206f1f76a1968a6cfeafa80576 Message-Id: <20211004084754.7B4BD3858010@sourceware.org> Date: Mon, 4 Oct 2021 08:47:54 +0000 (GMT) X-BeenThere: gcc-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 04 Oct 2021 08:47:54 -0000 https://gcc.gnu.org/g:6109bcaf72f86d206f1f76a1968a6cfeafa80576 commit r12-4116-g6109bcaf72f86d206f1f76a1968a6cfeafa80576 Author: Eric Botcazou Date: Thu Aug 26 15:42:05 2021 +0200 [Ada] Adjust documentation of -fdump-ada-spec in GNAT UG gcc/ada/ * doc/gnat_ugn/the_gnat_compilation_model.rst (Binding generation): Document specific behavior for /include/-ending paths and update. * gnat_ugn.texi: Regenerate. Diff: --- .../doc/gnat_ugn/the_gnat_compilation_model.rst | 52 +++++---------------- gcc/ada/gnat_ugn.texi | 54 ++++++---------------- 2 files changed, 25 insertions(+), 81 deletions(-) diff --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst index 39b9ca1cb09..8b4d4581350 100644 --- a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst +++ b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst @@ -4526,8 +4526,8 @@ Some of the known limitations include: constants. Function macros (macros with arguments) are partially translated as comments, to be completed manually if needed. * some extensions (e.g. vector types) are not supported -* pointers to pointers or complex structures are mapped to System.Address -* identifiers with identical name (except casing) will generate compilation +* pointers to pointers are mapped to System.Address +* identifiers with identical name (except casing) may generate compilation errors (e.g. ``shm_get`` vs ``SHM_GET``). The code is generated using Ada 2012 syntax, which makes it easier to interface @@ -4546,14 +4546,17 @@ header files needed by these files transitively. For example: .. code-block:: sh - $ g++ -c -fdump-ada-spec -C /usr/include/time.h + $ gcc -c -fdump-ada-spec -C /usr/include/time.h $ gcc -c *.ads will generate, under GNU/Linux, the following files: :file:`time_h.ads`, :file:`bits_time_h.ads`, :file:`stddef_h.ads`, :file:`bits_types_h.ads` which correspond to the files :file:`/usr/include/time.h`, -:file:`/usr/include/bits/time.h`, etc..., and will then compile these Ada specs -in Ada 2005 mode. +:file:`/usr/include/bits/time.h`, etc..., and then compile these Ada specs. +That is to say, the name of the Ada specs is in keeping with the relative path +under :file:`/usr/include/` of the header files. This behavior is specific to +paths ending with :file:`/include/`; in all the other cases, the name of the +Ada specs is derived from the simple name of the header files instead. The :switch:`-C` switch tells ``gcc`` to extract comments from headers, and will attempt to generate corresponding Ada comments. @@ -4564,39 +4567,8 @@ can use instead the :switch:`-fdump-ada-spec-slim` switch. You can optionally specify a parent unit, of which all generated units will be children, using :switch:`-fada-spec-parent={unit}`. -Note that we recommend when possible to use the *g++* driver to -generate bindings, even for most C headers, since this will in general -generate better Ada specs. For generating bindings for C++ headers, it is -mandatory to use the *g++* command, or *gcc -x c++* which -is equivalent in this case. If *g++* cannot work on your C headers -because of incompatibilities between C and C++, then you can fallback to -``gcc`` instead. - -For an example of better bindings generated from the C++ front-end, -the name of the parameters (when available) are actually ignored by the C -front-end. Consider the following C header: - -.. code-block:: c - - extern void foo (int variable); - -with the C front-end, ``variable`` is ignored, and the above is handled as: - -.. code-block:: c - - extern void foo (int); - -generating a generic: - -.. code-block:: ada - - procedure foo (param1 : int); - -with the C++ front-end, the name is available, and we generate: - -.. code-block:: ada - - procedure foo (variable : int); +The simple ``gcc```-based command works only for C headers. For C++ headers +you need to use either the ``g++`` command or the combination ``gcc -x c++```. In some cases, the generated bindings will be more complete or more meaningful when defining some macros, which you can do via the :switch:`-D` switch. This @@ -4604,7 +4576,7 @@ is for example the case with :file:`Xlib.h` under GNU/Linux: .. code-block:: sh - $ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h + $ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h The above will generate more complete bindings than a straight call without the :switch:`-DXLIB_ILLEGAL_ACCESS` switch. @@ -4626,7 +4598,7 @@ and then generate Ada bindings from this file: .. code-block:: sh - $ g++ -c -fdump-ada-spec readline1.h + $ gcc -c -fdump-ada-spec readline1.h .. _Generating_bindings_for_C++_headers: diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 68a223c061c..d7627ab413f 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -21,7 +21,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , Aug 03, 2021 +GNAT User's Guide for Native Platforms , Sep 28, 2021 AdaCore @@ -6421,10 +6421,10 @@ as comments, to be completed manually if needed. some extensions (e.g. vector types) are not supported @item -pointers to pointers or complex structures are mapped to System.Address +pointers to pointers are mapped to System.Address @item -identifiers with identical name (except casing) will generate compilation +identifiers with identical name (except casing) may generate compilation errors (e.g. @code{shm_get} vs @code{SHM_GET}). @end itemize @@ -6450,15 +6450,18 @@ spec files for the header files specified on the command line, and all header files needed by these files transitively. For example: @example -$ g++ -c -fdump-ada-spec -C /usr/include/time.h +$ gcc -c -fdump-ada-spec -C /usr/include/time.h $ gcc -c *.ads @end example will generate, under GNU/Linux, the following files: @code{time_h.ads}, @code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which correspond to the files @code{/usr/include/time.h}, -@code{/usr/include/bits/time.h}, etc…, and will then compile these Ada specs -in Ada 2005 mode. +@code{/usr/include/bits/time.h}, etc…, and then compile these Ada specs. +That is to say, the name of the Ada specs is in keeping with the relative path +under @code{/usr/include/} of the header files. This behavior is specific to +paths ending with @code{/include/}; in all the other cases, the name of the +Ada specs is derived from the simple name of the header files instead. The @code{-C} switch tells @code{gcc} to extract comments from headers, and will attempt to generate corresponding Ada comments. @@ -6469,46 +6472,15 @@ can use instead the @code{-fdump-ada-spec-slim} switch. You can optionally specify a parent unit, of which all generated units will be children, using @code{-fada-spec-parent=@emph{unit}}. -Note that we recommend when possible to use the @emph{g++} driver to -generate bindings, even for most C headers, since this will in general -generate better Ada specs. For generating bindings for C++ headers, it is -mandatory to use the @emph{g++} command, or @emph{gcc -x c++} which -is equivalent in this case. If @emph{g++} cannot work on your C headers -because of incompatibilities between C and C++, then you can fallback to -@code{gcc} instead. - -For an example of better bindings generated from the C++ front-end, -the name of the parameters (when available) are actually ignored by the C -front-end. Consider the following C header: - -@example -extern void foo (int variable); -@end example - -with the C front-end, @code{variable} is ignored, and the above is handled as: - -@example -extern void foo (int); -@end example - -generating a generic: - -@example -procedure foo (param1 : int); -@end example - -with the C++ front-end, the name is available, and we generate: - -@example -procedure foo (variable : int); -@end example +The simple @code{gcc`}-based command works only for C headers. For C++ headers +you need to use either the @code{g++} command or the combination @code{gcc -x c++`}. In some cases, the generated bindings will be more complete or more meaningful when defining some macros, which you can do via the @code{-D} switch. This is for example the case with @code{Xlib.h} under GNU/Linux: @example -$ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h +$ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h @end example The above will generate more complete bindings than a straight call without @@ -6530,7 +6502,7 @@ lines in e.g. @code{readline1.h}: and then generate Ada bindings from this file: @example -$ g++ -c -fdump-ada-spec readline1.h +$ gcc -c -fdump-ada-spec readline1.h @end example @node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers