From patchwork Mon Jan 23 12:41:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Arsen_Arsenovi=C4=87?= X-Patchwork-Id: 63589 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 50EE83858431 for ; Mon, 23 Jan 2023 12:49:21 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 50EE83858431 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1674478161; bh=zt7eCY7TrQc5zzjpCNZVs/fmPk8PrhaMraiBVHTghiM=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=j18ZcuuKjKcfhJB1qvL2WxXwu4uW01V8wI6voINz/jJBiaOhThm7k1ABM33T2RrMo /F0w4A2LrvpSgz4TiAC2foHAAX18Pexk+PiwIlp0STwTZUA2Fd98GsIYCBqhNs6aXE LmtjBxKHbB6Gjx3p3Z0izYOKDu5p6c9Vm9rczfkw= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mout-p-102.mailbox.org (mout-p-102.mailbox.org [80.241.56.152]) by sourceware.org (Postfix) with ESMTPS id 7BCB23858D32; Mon, 23 Jan 2023 12:48:50 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 7BCB23858D32 Received: from smtp1.mailbox.org (smtp1.mailbox.org [10.196.197.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-102.mailbox.org (Postfix) with ESMTPS id 4P0qfL6cChz9sZ1; Mon, 23 Jan 2023 13:48:42 +0100 (CET) To: libstdc++@gcc.gnu.org Cc: gcc-patches@gcc.gnu.org, =?utf-8?q?Arsen_Arsenovi=C4=87?= Subject: [PATCH] libstdc++: Document P1642 and extensions Date: Mon, 23 Jan 2023 13:41:45 +0100 Message-Id: <20230123124145.965541-1-arsen@aarsen.me> MIME-Version: 1.0 X-Spam-Status: No, score=-11.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_INFOUSMEBIZ, KAM_SHORT, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) 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: =?utf-8?q?Arsen_Arsenovi=C4=87_via_Gcc-patches?= From: =?utf-8?q?Arsen_Arsenovi=C4=87?= Reply-To: =?utf-8?q?Arsen_Arsenovi=C4=87?= Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" libstdc++-v3/ChangeLog: * doc/xml/manual/using.xml: Document newly-freestanding headers and the effect of the -ffreestanding flag. * doc/xml/manual/status_cxx2023.xml: Document P1642R11 as completed. * doc/xml/manual/configure.xml: Document that hosted installs respect __STDC_HOSTED__. * doc/xml/manual/test.xml: Document how to run tests in freestanding mode. --- Afternoon, This patch documents the freestanding changes that are to be included in GCC 13. This revision assumes the changes submitted earlier about building a nearly empty library in freestanding, and simplifies the linking section a bit as a result. Due to -ffreestanding now working on hosted builds of libstdc++, however, it still includes the advice of ``gcc -lsupc++'' for those that are using hosted builds. Thanks in advance, have a great day. libstdc++-v3/doc/xml/manual/configure.xml | 5 +- .../doc/xml/manual/status_cxx2023.xml | 11 ++++ libstdc++-v3/doc/xml/manual/test.xml | 14 ++++ libstdc++-v3/doc/xml/manual/using.xml | 66 +++++++++++++++++-- 4 files changed, 88 insertions(+), 8 deletions(-) diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml index 8b3b8cab8c7..7ff07aea886 100644 --- a/libstdc++-v3/doc/xml/manual/configure.xml +++ b/libstdc++-v3/doc/xml/manual/configure.xml @@ -362,7 +362,10 @@ built. The C++ Standard also describes a freestanding environment, in which only a minimal set of headers are provided. This option builds such an - environment. + environment. Note that a hosted library installs headers that still can + be used in non hosted environments, as the library checks for + __STDC_HOSTED__, however, a library configured with + --disable-hosted-libstdcxx will not install unusable headers. diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2023.xml b/libstdc++-v3/doc/xml/manual/status_cxx2023.xml index 365df505f54..f23c64d6a29 100644 --- a/libstdc++-v3/doc/xml/manual/status_cxx2023.xml +++ b/libstdc++-v3/doc/xml/manual/status_cxx2023.xml @@ -566,6 +566,17 @@ or any notes about the implementation. + + Easy [utilities], [ranges], and [iterators] + + + P1642R11 + + + 13.1 + + + diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml index 7bc6e339723..964c53d2632 100644 --- a/libstdc++-v3/doc/xml/manual/test.xml +++ b/libstdc++-v3/doc/xml/manual/test.xml @@ -350,6 +350,20 @@ cat 27_io/objects/char/3_xin.in | a.out + + If you wish to run the testsuite in a freestanding configuration, you can + pass the -ffreestanding flag. Doing so will run the tests + that do not require hosted features, and emit a + UNSUPPORTED for those that do. To run tests in the + freestanding configuration, you still need to build for a target you can + run programs on, e.g. x86_64-pc-linux-gnu, as a few tests + still execute the code they build. Here's an example of how to run the + testsuite with libstdc++ in freestanding mode: + + make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board=unix/-ffreestanding' + + + You can run the tests with a compiler and library that have already been installed. Make sure that the compiler (e.g., diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml index 9c444dd2997..7f011a6d931 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -132,6 +132,17 @@ + + -ffreestanding + + Limits the library to its freestanding subset. Headers that are + not supported in freestanding will emit a "This header is not available + in freestanding mode" error. + Headers that are in the freestanding subset partially will not expose + functionality that is not part of the freestanding subset. + + + @@ -1523,19 +1534,60 @@ namespace gtk - There exists a library that offers runtime support for - just these headers, and it is called - libsupc++.a. To use it, compile with gcc instead of g++, like so: + + As of GCC 13, libstdc++ implements P1642, which brings in many more + headers, as well a quite a few ones not covered by the paper. + + In general, if a feature does not require traditionally libc-provided + facilities, or dynamic memory allocation, it's enabled in the + freestanding subset. In addition, if only a subset of a header + requires such features, it is partially included. Some examples + include: + + + + + + string_view + + + + + tuple + + + + + bitset + + + + + + Currently, this subset includes all of the iterator APIs (including the + ranges APIs) that do not involve streams, the entire C++ algorithms + library, excluding parallel algorithms, and a large part of the + utilities library. This is on top of the headers included in the lists + above. + + + + If you're using a libstdc++ configured for hosted environments, and + would like to not involve the libraries libstdc++ would depend on in + your programs, you will need to use gcc to link your + application with only libsupc++.a, + like so: - gcc foo.cc -lsupc++ + gcc -ffreestanding foo.cc -lsupc++ - No attempt is made to verify that only the minimal subset - identified above is actually used at compile time. Violations - are diagnosed as undefined symbols at link time. + If you configured libstdc++ with + --disable-hosted-libstdcxx, however, you can use the + normal g++ command to link, as this configuration + provides a (nearly) empty libstdc++.a.