From patchwork Wed Apr 17 11:16:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jakub Jelinek X-Patchwork-Id: 1924591 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=XaHv9BcH; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=server2.sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4VKJKH5gJpz1yYB for ; Wed, 17 Apr 2024 21:17:22 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 74D043858D33 for ; Wed, 17 Apr 2024 11:17:13 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 8137B3858D20 for ; Wed, 17 Apr 2024 11:16:51 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8137B3858D20 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 8137B3858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713352615; cv=none; b=RM95N0FSjgNtogJdbwN432k99xUJXDGJh93h3qAhiWBXRfi6PO9jawaWViOIZnEj3dHTTdG0TQoCqrg2aSNZB+v8oUdzZQp8zjfAnQmaSVx1KS+Du74fveTqNnpsD7bHPwa608XS5110GDyy3jmQSV5bsO0AfjCb0uasafE+t/o= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713352615; c=relaxed/simple; bh=8rEh5gxYOAfIstn8W9Os7Qt1K/UIM1g9L+1E9Fsox/M=; h=DKIM-Signature:Date:From:To:Subject:Message-ID:MIME-Version; b=SIWSFvDASm4+kUQoTh7JvBiNYDPUryUM2jzVgemRVOkpxMPKOC7EuIdUSTqYptrA9G5dWqZiFdxOP3v7hB3eagru220jmH0aJbBu3xpbgNqpKjm6C/2nKMlS0OuO5jf5+ZIraZnhLqQdi1Iwc2szEEp54IzsnqP/BSah85M1oYE= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713352611; h=from:from:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SGPwzp9NrQpT3NFrFicQkjtPHTga5QOAl2OUfllpBl8=; b=XaHv9BcHVouZic6q7cWFKuXOzlz4XqS8swDmLGVihJhQWZbyGGzDqoTve7JzhL9PbiiT6A 16NirEFx9KoQTh+UkzlF8Q5amMGngnbNUxJmqpPGiopov38HgtYxozieCysZiqyzvG8IVw PZEUE8NvOtiUNYxNQvPwqVXMBQNyKtg= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-189-mDKL3D8JNYi9uGAzCWa29w-1; Wed, 17 Apr 2024 07:16:49 -0400 X-MC-Unique: mDKL3D8JNYi9uGAzCWa29w-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 52E87188E9C5 for ; Wed, 17 Apr 2024 11:16:49 +0000 (UTC) Received: from tucnak.zalov.cz (unknown [10.45.224.5]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D36ED51EF; Wed, 17 Apr 2024 11:16:48 +0000 (UTC) Received: from tucnak.zalov.cz (localhost [127.0.0.1]) by tucnak.zalov.cz (8.17.1/8.17.1) with ESMTPS id 43HBGhfo2662576 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NOT); Wed, 17 Apr 2024 13:16:43 +0200 Received: (from jakub@localhost) by tucnak.zalov.cz (8.17.1/8.17.1/Submit) id 43HBGhY32662575; Wed, 17 Apr 2024 13:16:43 +0200 Date: Wed, 17 Apr 2024 13:16:43 +0200 From: Jakub Jelinek To: David Malcolm , Mark Wielaard Cc: gcc-patches@gcc.gnu.org Subject: [PATCH] DOCUMENTATION_ROOT_URL vs. release branches [PR114738] Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline X-Spam-Status: No, score=-4.3 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_SHORT, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, 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.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Jakub Jelinek Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Hi! Starting with GCC 14 we have the nice URLification of the options printed in diagnostics, say for in test.c:4:23: warning: format ‘%d’ expects argument of type ‘int’, but argument 2 has type ‘long int’ [-Wformat=] the -Wformat= is underlined in some terminals and hovering on it shows https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wformat link. This works nicely on the GCC trunk, where the online documentation is regenerated every day from a cron job and more importantly, people rarely use the trunk snapshots for too long, so it is unlikely that further changes in the documentation will make too many links stale, because users will simply regularly update to newer snapshots. I think it doesn't work properly on release branches though. Some users only use the relased versions (i.e. MAJOR.MINOR.0) from tarballs but can use them for a couple of years, others use snapshots from the release branches, but again they could be in use for months or years and the above mentioned online docs which represent just the GCC trunk might diverge significantly. Now, for the relases we always publish also online docs for the release, which unlike the trunk online docs will not change further, under e.g. https://gcc.gnu.org/onlinedocs/gcc-14.1.0/gcc/Warning-Options.html#index-Wformat or https://gcc.gnu.org/onlinedocs/gcc-14.2.0/gcc/Warning-Options.html#index-Wformat etc. So, I think at least for the MAJOR.MINOR.0 releases we want to use URLs like above rather than the trunk ones and we can use the same process of updating *.opt.urls as well for that. For the snapshots from release branches, we don't have such docs. One option (implemented in the patch below for the URL printing side) is point to the MAJOR.MINOR.0 docs even for MAJOR.MINOR.1 snapshots. Most of the links will work fine, for options newly added on the release branches (rare thing but still happens) can have until the next release no URLs for them and get them with the next point release. The question is what to do about make regenerate-opt-urls for the release branch snapshots. Either just document that users shouldn't make regenerate-opt-urls on release branches (and filter out *.opt.urls changes from their commits), add make regenerate-opt-urls task be RM responsibility before making first release candidate from a branch and adjust the autoregen CI to know about that. Or add a separate goal which instead of relying on make html created files would download copy of the html files from the last release from web (kind of web mirroring the https://gcc.gnu.org/onlinedocs/gcc-14.1.0/ subtree locally) and doing regenerate-opt-urls on top of that? But how to catch the point when first release candidate is made and we want to update to what will be the URLs once the release is made (but will be stale URLs for a week or so)? Another option would be to add to cron daily regeneration of the online docs for the release branches. I don't think that is a good idea though, because as I wrote earlier, not all users update to the latest snapshot frequently, so there can be users that use gcc 13.1.1 20230525 for months or years, and other users which use gcc 13.1.1 20230615 for years etc. Another question is what is most sensible for users who want to override the default root and use the --with-documentation-root-url= configure option. Do we expect them to grab the whole onlinedocs tree or for release branches at least include gcc-14.1.0/ subdirectory under the root? If so, the patch below deals with that. Or should we just change the default documentation root url, so if user doesn't specify --with-documentation-root-url= and we are on a release branch, default that to https://gcc.gnu.org/onlinedocs/gcc-14.1.0/ or https://gcc.gnu.org/onlinedocs/gcc-14.2.0/ etc. and don't add any infix in get_option_url/make_doc_url, but when people supply their own, let them point to the root of the tree which contains the right docs? Then such changes would go into gcc/configure.ac, some case based on "$gcc_version", from that decide if it is a release branch or trunk. 2024-04-17 Jakub Jelinek PR other/114738 * opts.cc (get_option_url): On release branches append gcc-MAJOR.MINOR.0/ after DOCUMENTATION_ROOT_URL. * gcc-urlifier.cc (gcc_urlifier::make_doc_url): Likewise. Jakub --- gcc/opts.cc.jj 2024-01-05 08:35:13.600828652 +0100 +++ gcc/opts.cc 2024-04-17 12:03:10.961525141 +0200 @@ -3761,7 +3761,19 @@ get_option_url (const diagnostic_context { label_text url_suffix = get_option_url_suffix (option_index, lang_mask); if (url_suffix.get ()) - return concat (DOCUMENTATION_ROOT_URL, url_suffix.get (), nullptr); + { + char infix[32]; + /* On release branches, append to DOCUMENTATION_ROOT_URL the + subdirectory with documentation of the latest release made + from the branch. */ + if (BUILDING_GCC_MINOR != 0 && BUILDING_GCC_PATCHLEVEL <= 1U) + sprintf (infix, "gcc-%u.%u.0/", + BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR); + else + infix[0] = '\0'; + return concat (DOCUMENTATION_ROOT_URL, infix, url_suffix.get (), + nullptr); + } } return nullptr; --- gcc/gcc-urlifier.cc.jj 2024-01-10 17:15:31.851855587 +0100 +++ gcc/gcc-urlifier.cc 2024-04-17 12:14:47.902706021 +0200 @@ -26,6 +26,7 @@ along with GCC; see the file COPYING3. #include "gcc-urlifier.h" #include "opts.h" #include "options.h" +#include "diagnostic-core.h" #include "selftest.h" namespace { @@ -208,7 +209,16 @@ gcc_urlifier::make_doc_url (const char * if (!doc_url_suffix) return nullptr; - return concat (DOCUMENTATION_ROOT_URL, doc_url_suffix, nullptr); + char infix[32]; + /* On release branches, append to DOCUMENTATION_ROOT_URL the + subdirectory with documentation of the latest release made + from the branch. */ + if (BUILDING_GCC_MINOR != 0 && BUILDING_GCC_PATCHLEVEL <= 1U) + sprintf (infix, "gcc-%u.%u.0/", + BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR); + else + infix[0] = '\0'; + return concat (DOCUMENTATION_ROOT_URL, infix, doc_url_suffix, nullptr); } } // anonymous namespace