From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 Authentication-Results: sourceware.org; dmarc=pass (p=reject dis=none) header.from=aarsen.me Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=aarsen.me 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) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=aarsen.me; s=MBO0001; t=1674478122; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=zt7eCY7TrQc5zzjpCNZVs/fmPk8PrhaMraiBVHTghiM=; b=FjoyYMgoDlFdwx/sk0zhhynmMpXsa7EXHYyrWFK2sT1UnQyC9lXO+ZQX7oGdo+wvcd3bRz MfzxjEv9NbyOQGcEtesLV3n2M4B7oTn2Ng5FZA4u9XDJ5R2qIVSFlmGxNQ/jiWqxkSHfSb DeaKAj1HjpdhwcxqgcMxsJyYTVs6qtXZBBCPYSHSP8XV73+smhqy1YQj+FNgfgvGp1fJ7o KsMO6jnqSPybwPb1pHShGpzSJPqGzqo70SN38kP988jrvgZPKyC7IiP6iw0biQHSbxK5GZ idm6e8zPfcGPYHwsKUuBl2SA97MYO14rdINzHYaMD2m0m78BSTF3iPhudQbrXw== From: =?UTF-8?q?Arsen=20Arsenovi=C4=87?= To: libstdc++@gcc.gnu.org Cc: gcc-patches@gcc.gnu.org, =?UTF-8?q?Arsen=20Arsenovi=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 Content-Transfer-Encoding: 8bit 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 List-Id: 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. -- 2.39.1