From patchwork Mon Oct 4 08:47:43 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Pierre-Marie de Rodat X-Patchwork-Id: 1535997 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha256 header.s=default header.b=K1gGYk8H; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=8.43.85.97; helo=sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HNF0w01B7z9t25 for ; Mon, 4 Oct 2021 19:55:27 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0957A385843D for ; Mon, 4 Oct 2021 08:55:25 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0957A385843D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1633337725; bh=RJdcjcRdgS96rdwmh/ZpHD3c3aThmGvDBwWPfkg4AJU=; h=Date:To:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=K1gGYk8Hdj7Rbpxmm+ehPJ0iBhWpDMmeEBTwXpvZzifqXOaeybEi+GbqhkDMzMGBt aXmT5ArPNcbjQQR+ZpTZb5C7dcR/L08lrfqmSKe94qHrYPwV/OotmTu85/eHtpKhAZ VronfhOqYXdflB8suF3eCgtf3nzzU68w7e3+DI8Y= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-lf1-x12b.google.com (mail-lf1-x12b.google.com [IPv6:2a00:1450:4864:20::12b]) by sourceware.org (Postfix) with ESMTPS id C0C0C3858410 for ; Mon, 4 Oct 2021 08:47:46 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C0C0C3858410 Received: by mail-lf1-x12b.google.com with SMTP id g41so68157843lfv.1 for ; Mon, 04 Oct 2021 01:47:46 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:content-transfer-encoding; bh=RJdcjcRdgS96rdwmh/ZpHD3c3aThmGvDBwWPfkg4AJU=; b=w9Cibq2OXBqcPTrElOWb7NNeO8xZDYKGm8hGuSHbeI9CxSGfMX9K+bu7vr7tqXsql2 82tvRjNaRhlhQzuExUsFeJPxmAsPqpTW1DdWYB+VMxQWqI8kjazhGJF3wTa4jnirz5mI jH4JpdYGZvanfYkqkyWIjGa++jPMBikLqq8CsxcFpWHvUMK3PM/TUyGe+JdtaSY0wCPX FIyk0B7hR82OhUCP1M/NLDv192iFOhUsd3zRQUV65YCjQXN63yLPlYzscGB3zONqJWOx LZmN+ZETqjBCR+ZVw9b2DqOgBSJ8O3DHlYnzSylsvpWqaCBRibRrmSlIm22S8aK2F5qG W8iA== X-Gm-Message-State: AOAM531nX/3tsk4O8kQ3nLu1hlCxxhmRvHPw+NIIfXy8lolD/FjqcrNF 2PEoJQJtQDb+X8YCS6pd6jr1r8mWpNdgng== X-Google-Smtp-Source: ABdhPJzXiwIm5fCPSq1qCxbX3lLtQRj4nc88GDziM+y3DCR5YlKD2kJQ0E6KRvKgxRgUAx3a0UM3Aw== X-Received: by 2002:a05:6512:3408:: with SMTP id i8mr13236192lfr.538.1633337265689; Mon, 04 Oct 2021 01:47:45 -0700 (PDT) Received: from adacore.com ([2a02:2ab8:224:2ce:72b5:e8ff:feef:ee60]) by smtp.gmail.com with ESMTPSA id r26sm1538788lfi.293.2021.10.04.01.47.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 04 Oct 2021 01:47:45 -0700 (PDT) Date: Mon, 4 Oct 2021 08:47:43 +0000 To: gcc-patches@gcc.gnu.org Subject: [Ada] Adjust documentation of -fdump-ada-spec in GNAT UG Message-ID: <20211004084743.GA1536559@adacore.com> MIME-Version: 1.0 Content-Disposition: inline X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Pierre-Marie de Rodat via Gcc-patches From: Pierre-Marie de Rodat Reply-To: Pierre-Marie de Rodat Cc: Eric Botcazou Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" This explicitly documents the behavior for /include/-ending paths and also updates other parts of the description. Tested on x86_64-pc-linux-gnu, committed on trunk 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 --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst --- 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 --- 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