Re: [PATCH 0/4] v2 of Option handling: add documentation URLs

[David Malcolm <dmalcolm@redhat.com>]

On Tue, 2023-11-21 at 23:43 +0000, Joseph Myers wrote:
> On Tue, 21 Nov 2023, Tobias Burnus wrote:
> 
> > On 21.11.23 14:57, David Malcolm wrote:
> > > On Tue, 2023-11-21 at 02:09 +0100, Hans-Peter Nilsson wrote:
> > > > Sorry for barging in though I did try finding the relevant
> > > > discussion, but is committing this generated stuff necessary?
> > > > Is it because we don't want to depend on Python being
> > > > present at build time?
> > > Partly, yes, [...]
> > 
> > I wonder how to ensure that this remains up to date. Should there
> > be an
> > item at
> > 
> > https://gcc.gnu.org/branching.html and/or
> > https://gcc.gnu.org/releasing.html similar to the .pot generation?
> 
> My suggestion earlier in the discussion was that it should be added
> to the 
> post-commit CI discussed starting at 
> <https://gcc.gnu.org/pipermail/gcc/2023-November/242835.html> (I
> think 
> that CI is now in operation).  These are generated files that ought
> to be 
> kept up to date with each commit that affects .opt files, unlike the
> .pot 
> files where the expectation is that they should be up to date for
> releases 
> and updated from time to time at other times for submission to the
> TP.

I had a go at scripting the testing of this, but I am terrible at shell
scripts (maybe I should use Python?).  Here's what I have so far:

$ cat contrib/regenerate-index-urls.sh

set -x

SRC_DIR=$1
BUILD_DIR=$2
NUM_JOBS=$3

# FIXME: error-checking!

mkdir -p $BUILD_DIR || exit 1
cd $BUILD_DIR
$SRC_DIR/configure --disable-bootstrap --enable-languages=c,d,fortran || exit 2
make html-gcc -j$NUM_JOBS || exit 3
cd gcc || exit 4
make regenerate-opt-urls || exit 5
cd $SRC_DIR
(git diff $1 > /dev/null ) && echo "regenerate-opt-urls needs to be run and the results committed" || exit 6

# e.g.
#  time bash contrib/regenerate-index-urls.sh $(pwd) $(pwd)/../build-ci 64

This takes about 100 seconds of wallclock on my 64-core box (mostly
configuring gcc, which as well as the usual sequence of unparallelized
tests seems to require building libiberty and lto-plugin).  Is that
something we want to do on every commit?  Is implementing the CI a
blocker for getting the patches in? (if so, I'll likely need some help)

As it turned out, I hadn't regenerated the .opt.urls in my working copy
for a couple of weeks, leading to a correct-looking patch containing
things like:

@@ -154,8 +157,8 @@ UrlSuffix(gcc/Warning-Options.html#index-Wbuiltin-declaration-mismatch) LangUrlS
 Wbuiltin-macro-redefined
 UrlSuffix(gcc/Warning-Options.html#index-Wbuiltin-macro-redefined)
 
-Wc11-c2x-compat
-UrlSuffix(gcc/Warning-Options.html#index-Wc11-c2x-compat)
+Wc11-c23-compat
+UrlSuffix(gcc/Warning-Options.html#index-Wc11-c23-compat)
 
 Wc90-c99-compat
 UrlSuffix(gcc/Warning-Options.html#index-Wc90-c99-compat)

so I think the idea works; and the only issue for not regenerating was
some missing/out-of-date URLs.

Dave