Re: [PATCH 0/3] Option handling: add documentation URLs

[David Malcolm <dmalcolm@redhat.com>]

On Tue, 2023-11-14 at 00:12 +0000, Joseph Myers wrote:
> On Fri, 10 Nov 2023, David Malcolm wrote:
> 
> > The .opt.urls files it generates become part of the source tree,
> > and
> > would be regenerated by maintainers whenever new options are added.
> > Forgetting to update the files (or not having Python 3 handy)
> > merely
> > means that URLs might be missing or out of date until someone else
> > regenerates them.
> 
> Do I understand correctly that there are no makefile targets to
> regenerate 
> these files; it's up to maintainers to regenerate them manually?
> 
> Advantages:
> 
> * No need to update contrib/gcc_update to handle timestamps for the
> files.
> 
> * No modifications unexpectedly appearing in source trees, if the
> checked 
> in files are out of date and you run a build with the timestamps such
> that 
> the file gets regenerated.

The .opt.urls are generated from the generated HTML.  I think this
needs to be a manually-triggered process, otherwise the optionlist
depends on the generated HTML, and thus the generated HTML would become
a hard early dependency during the build (which I don't think we would
want).

> 
> Disadvantages:
> 
> * You need to know how to do the regeneration manually; "make" is the
> uniform way for generating any file the build system can generate,
> without 
> needing more specific knowledge about that file.

In the patches I posted I merely listed the commands in a comment in
the script, but I'm currently working on adding support for options
from the gdc and gfortran docs, and in doing so found that running the
script with the correct options was a pain.

So to make it easier, I'm currently thinking of adding this convenience
target, so that when a maintainer does decide to regenerate the
.opt.urls, they can simply type "make regenerate-opt-urls" in the gcc
build subdir:

diff --git a/gcc/Makefile.in b/gcc/Makefile.in
index c3ed960b8f3c..6d24b7b9db34 100644
--- a/gcc/Makefile.in
+++ b/gcc/Makefile.in
@@ -3616,6 +3616,12 @@ $(build_htmldir)/gccinstall/index.html: $(TEXI_GCCINSTALL_FILES)
        DESTDIR=$(@D) \
        $(SHELL) $(srcdir)/doc/install.texi2html
 
+# Regenerate the .opt.urls files from the generated html, and from the .opt
+# files.
+.PHONY: regenerate-opt-urls
+regenerate-opt-urls:
+       $(srcdir)/regenerate-opt-urls.py $(build_htmldir) $(shell dirname $(srcdir))
+
 MANFILES = doc/gcov.1 doc/cpp.1 doc/gcc.1 doc/gfdl.7 doc/gpl.7 \
            doc/fsf-funding.7 doc/gcov-tool.1 doc/gcov-dump.1 \
           $(if $(filter yes,@enable_lto@),doc/lto-dump.1)


> 
> Given the recent discussion starting at 
> <https://gcc.gnu.org/pipermail/gcc/2023-November/242835.html> of 
> post-commit CI to detect auto*-generated files that aren't fully up
> to 
> date, maybe it would be appropriate to add a check for .opt.urls
> files 
> being up to date (including making sure that each .opt file does have
> a 
> corresponding .opt.urls file checked in) to that CI?
> 
> Since the Python script has hardcoded information about .opt files
> and 
> corresponding URLs for target options documentation, the patch series
> should update sourcebuild.texi, section "Back End", to identify that 
> script as one of the places to update when adding a new target back
> end.

Thanks, will do.

As mentioned, I'm currently investigating capturing per-language option
URLs (to address Iain's and Marc's comments about D and Ada); if I get
that working, I may need to add a similar note for adding a new
frontend.

Hope the overall approach seems reasonable.
Dave