public inbox for gcc-patches@gcc.gnu.org
 help / color / mirror / Atom feed
* [PATCH 0/3] Option handling: add documentation URLs
@ 2023-11-10 21:42 David Malcolm
  2023-11-10 21:42 ` [PATCH 1/3] options: add gcc/regenerate-opt-urls.py David Malcolm
                   ` (3 more replies)
  0 siblings, 4 replies; 47+ messages in thread
From: David Malcolm @ 2023-11-10 21:42 UTC (permalink / raw)
  To: gcc-patches, Joseph Myers; +Cc: David Malcolm

In r14-5118-gc5db4d8ba5f3de I added a mechanism to automatically add
URLs to quoted strings in diagnostics.  This was based on a data table
mapping strings to URLs, with placeholder data covering various pragmas
and a couple of options.

The following patches add automatic URLification in our diagnostic
messages to mentions of *all* of our options in quoted strings, linking
to our HTML documentation.

For example, with these patches, given:

  ./xgcc -B. -S t.c -Wctad-maybe-unsupported
  cc1: warning: command-line option ‘-Wctad-maybe-unsupported’ is valid for C++/ObjC++ but not for C

the quoted string '-Wctad-maybe-unsupported' gets automatically URLified
in a sufficiently modern terminal to:
  https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html#index-Wctad-maybe-unsupported

Objectives:
- integrate with DOCUMENTATION_ROOT_URL
- integrate with the existing .opt mechanisms
- automate keeping the URLs up-to-date
- work with target-specific options based on current configuration
- work with lang-specific options based on current configuration
- keep autogenerated material separate from the human-maintained .opt
  files
- no new build-time requirements (by using awk at build time)
- be maintainable

The approach is a new regenerate-opt-urls.py which:
- scrapes the generated HTML documentation finding anchors
  for options,
- reads all the .opt files in the source tree
- for each .opt file, generates a .opt.urls file; for each
  option in the .opt file it has either a UrlSuffix directives giving
  the final part of the URL of that option's documentation (relative
  to DOCUMENTATION_ROOT_URL), or a comment describing the problem.

regenerate-opt-urls.py is written in Python 3, and has unit tests.
I tested it with Python 3.8, and it probably works with earlier
releases of Python 3.
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.

At build time, the .opt.urls are added to .opt files when regenerating
the optionslist file.  A new "options-urls-cc-gen.awk" is run at build
time on the optionslist to generate a "options-urls.cc" file containing
a big array of strings for all of the options present in the
configuration:

const char * const opt_url_suffixes[] =
{
  [...snip...]

  /* [563] (OPT_Wclass_memaccess) = */
  "gcc/C_002b_002b-Dialect-Options.html#index-Wclass-memaccess",

  /* [564] (OPT_Wclobbered) = */
  "gcc/Warning-Options.html#index-Wclobbered",

  [...snip...]
};

and this is then used by the gcc_urlifier class when emitting
diagnostics.

Successfully bootstrapped & regrtested on x86_64-pc-linux-gnu.
OK for trunk?

David Malcolm (3):
  options: add gcc/regenerate-opt-urls.py
  Add generated .opt.urls files
  diagnostics: use the .opt.urls files to urlify quoted text

 gcc/Makefile.in                              |   18 +-
 gcc/ada/gcc-interface/lang.opt.urls          |   28 +
 gcc/analyzer/analyzer.opt.urls               |  206 ++
 gcc/c-family/c.opt.urls                      | 1404 ++++++++++++++
 gcc/common.opt.urls                          | 1823 ++++++++++++++++++
 gcc/config/aarch64/aarch64.opt.urls          |   84 +
 gcc/config/alpha/alpha.opt.urls              |   76 +
 gcc/config/alpha/elf.opt.urls                |    2 +
 gcc/config/arc/arc-tables.opt.urls           |    2 +
 gcc/config/arc/arc.opt.urls                  |  260 +++
 gcc/config/arm/arm-tables.opt.urls           |    2 +
 gcc/config/arm/arm.opt.urls                  |  149 ++
 gcc/config/arm/vxworks.opt.urls              |    2 +
 gcc/config/avr/avr.opt.urls                  |   71 +
 gcc/config/bfin/bfin.opt.urls                |   61 +
 gcc/config/bpf/bpf.opt.urls                  |   35 +
 gcc/config/c6x/c6x-tables.opt.urls           |    2 +
 gcc/config/c6x/c6x.opt.urls                  |   18 +
 gcc/config/cris/cris.opt.urls                |   65 +
 gcc/config/cris/elf.opt.urls                 |    8 +
 gcc/config/csky/csky.opt.urls                |  104 +
 gcc/config/csky/csky_tables.opt.urls         |    2 +
 gcc/config/darwin.opt.urls                   |  221 +++
 gcc/config/dragonfly.opt.urls                |    9 +
 gcc/config/epiphany/epiphany.opt.urls        |   52 +
 gcc/config/fr30/fr30.opt.urls                |    8 +
 gcc/config/freebsd.opt.urls                  |    9 +
 gcc/config/frv/frv.opt.urls                  |  111 ++
 gcc/config/ft32/ft32.opt.urls                |   20 +
 gcc/config/fused-madd.opt.urls               |    4 +
 gcc/config/g.opt.urls                        |    5 +
 gcc/config/gcn/gcn.opt.urls                  |   23 +
 gcc/config/gnu-user.opt.urls                 |    9 +
 gcc/config/h8300/h8300.opt.urls              |   29 +
 gcc/config/hpux11.opt.urls                   |    6 +
 gcc/config/i386/cygming.opt.urls             |   30 +
 gcc/config/i386/cygwin.opt.urls              |    6 +
 gcc/config/i386/djgpp.opt.urls               |    2 +
 gcc/config/i386/i386.opt.urls                |  602 ++++++
 gcc/config/i386/mingw-w64.opt.urls           |    5 +
 gcc/config/i386/mingw.opt.urls               |   12 +
 gcc/config/i386/nto.opt.urls                 |    5 +
 gcc/config/ia64/ia64.opt.urls                |  122 ++
 gcc/config/ia64/ilp32.opt.urls               |    8 +
 gcc/config/ia64/vms.opt.urls                 |    2 +
 gcc/config/iq2000/iq2000.opt.urls            |   14 +
 gcc/config/linux-android.opt.urls            |   11 +
 gcc/config/linux.opt.urls                    |   14 +
 gcc/config/lm32/lm32.opt.urls                |   14 +
 gcc/config/loongarch/loongarch.opt.urls      |   60 +
 gcc/config/lynx.opt.urls                     |    5 +
 gcc/config/m32c/m32c.opt.urls                |    8 +
 gcc/config/m32r/m32r.opt.urls                |   27 +
 gcc/config/m68k/ieee.opt.urls                |    4 +
 gcc/config/m68k/m68k-tables.opt.urls         |    2 +
 gcc/config/m68k/m68k.opt.urls                |  107 +
 gcc/config/m68k/uclinux.opt.urls             |    2 +
 gcc/config/mcore/mcore.opt.urls              |   38 +
 gcc/config/microblaze/microblaze.opt.urls    |   59 +
 gcc/config/mips/mips-tables.opt.urls         |    2 +
 gcc/config/mips/mips.opt.urls                |  269 +++
 gcc/config/mips/sde.opt.urls                 |    2 +
 gcc/config/mmix/mmix.opt.urls                |   44 +
 gcc/config/mn10300/mn10300.opt.urls          |   32 +
 gcc/config/moxie/moxie.opt.urls              |   14 +
 gcc/config/msp430/msp430.opt.urls            |   53 +
 gcc/config/nds32/nds32-elf.opt.urls          |    5 +
 gcc/config/nds32/nds32-linux.opt.urls        |    5 +
 gcc/config/nds32/nds32.opt.urls              |   57 +
 gcc/config/netbsd-elf.opt.urls               |    5 +
 gcc/config/netbsd.opt.urls                   |    6 +
 gcc/config/nios2/elf.opt.urls                |   14 +
 gcc/config/nios2/nios2.opt.urls              |   50 +
 gcc/config/nvptx/nvptx-gen.opt.urls          |    2 +
 gcc/config/nvptx/nvptx.opt.urls              |   29 +
 gcc/config/openbsd.opt.urls                  |    6 +
 gcc/config/or1k/elf.opt.urls                 |    8 +
 gcc/config/or1k/or1k.opt.urls                |   46 +
 gcc/config/pa/pa-hpux.opt.urls               |   11 +
 gcc/config/pa/pa-hpux1010.opt.urls           |    2 +
 gcc/config/pa/pa-hpux1111.opt.urls           |    2 +
 gcc/config/pa/pa-hpux1131.opt.urls           |    2 +
 gcc/config/pa/pa.opt.urls                    |   71 +
 gcc/config/pa/pa64-hpux.opt.urls             |    8 +
 gcc/config/pdp11/pdp11.opt.urls              |   41 +
 gcc/config/pru/pru.opt.urls                  |   17 +
 gcc/config/riscv/riscv.opt.urls              |   88 +
 gcc/config/rl78/rl78.opt.urls                |   31 +
 gcc/config/rpath.opt.urls                    |    2 +
 gcc/config/rs6000/476.opt.urls               |    2 +
 gcc/config/rs6000/aix64.opt.urls             |   23 +
 gcc/config/rs6000/darwin.opt.urls            |   14 +
 gcc/config/rs6000/linux64.opt.urls           |    4 +
 gcc/config/rs6000/rs6000-tables.opt.urls     |    2 +
 gcc/config/rs6000/rs6000.opt.urls            |  214 ++
 gcc/config/rs6000/sysv4.opt.urls             |   87 +
 gcc/config/rtems.opt.urls                    |    6 +
 gcc/config/rx/elf.opt.urls                   |   14 +
 gcc/config/rx/rx.opt.urls                    |   54 +
 gcc/config/s390/s390.opt.urls                |   92 +
 gcc/config/s390/tpf.opt.urls                 |    8 +
 gcc/config/sh/sh.opt.urls                    |  174 ++
 gcc/config/sh/superh.opt.urls                |    4 +
 gcc/config/sol2.opt.urls                     |   21 +
 gcc/config/sparc/long-double-switch.opt.urls |    6 +
 gcc/config/sparc/sparc.opt.urls              |  108 ++
 gcc/config/stormy16/stormy16.opt.urls        |    5 +
 gcc/config/v850/v850.opt.urls                |   60 +
 gcc/config/vax/elf.opt.urls                  |    2 +
 gcc/config/vax/vax.opt.urls                  |   10 +
 gcc/config/visium/visium.opt.urls            |   29 +
 gcc/config/vms/vms.opt.urls                  |    8 +
 gcc/config/vxworks-smp.opt.urls              |    5 +
 gcc/config/vxworks.opt.urls                  |   20 +
 gcc/config/xtensa/elf.opt.urls               |    5 +
 gcc/config/xtensa/uclinux.opt.urls           |    2 +
 gcc/config/xtensa/xtensa.opt.urls            |   37 +
 gcc/d/lang.opt.urls                          |   95 +
 gcc/doc/options.texi                         |   17 +
 gcc/fortran/lang.opt.urls                    |  153 ++
 gcc/gcc-urlifier.cc                          |  106 +-
 gcc/gcc-urlifier.def                         |    2 -
 gcc/gcc-urlifier.h                           |    2 +-
 gcc/gcc.cc                                   |    2 +-
 gcc/go/lang.opt.urls                         |   15 +
 gcc/lto/lang.opt.urls                        |    8 +
 gcc/m2/lang.opt.urls                         |  110 ++
 gcc/opt-functions.awk                        |    7 +
 gcc/options-urls-cc-gen.awk                  |   79 +
 gcc/opts.cc                                  |   75 +-
 gcc/opts.h                                   |    4 +
 gcc/params.opt.urls                          |    2 +
 gcc/regenerate-opt-urls.py                   |  366 ++++
 gcc/rust/lang.opt.urls                       |   27 +
 gcc/testsuite/lib/gcc-dg.exp                 |    6 +
 gcc/toplev.cc                                |    2 +-
 136 files changed, 9044 insertions(+), 61 deletions(-)
 create mode 100644 gcc/ada/gcc-interface/lang.opt.urls
 create mode 100644 gcc/analyzer/analyzer.opt.urls
 create mode 100644 gcc/c-family/c.opt.urls
 create mode 100644 gcc/common.opt.urls
 create mode 100644 gcc/config/aarch64/aarch64.opt.urls
 create mode 100644 gcc/config/alpha/alpha.opt.urls
 create mode 100644 gcc/config/alpha/elf.opt.urls
 create mode 100644 gcc/config/arc/arc-tables.opt.urls
 create mode 100644 gcc/config/arc/arc.opt.urls
 create mode 100644 gcc/config/arm/arm-tables.opt.urls
 create mode 100644 gcc/config/arm/arm.opt.urls
 create mode 100644 gcc/config/arm/vxworks.opt.urls
 create mode 100644 gcc/config/avr/avr.opt.urls
 create mode 100644 gcc/config/bfin/bfin.opt.urls
 create mode 100644 gcc/config/bpf/bpf.opt.urls
 create mode 100644 gcc/config/c6x/c6x-tables.opt.urls
 create mode 100644 gcc/config/c6x/c6x.opt.urls
 create mode 100644 gcc/config/cris/cris.opt.urls
 create mode 100644 gcc/config/cris/elf.opt.urls
 create mode 100644 gcc/config/csky/csky.opt.urls
 create mode 100644 gcc/config/csky/csky_tables.opt.urls
 create mode 100644 gcc/config/darwin.opt.urls
 create mode 100644 gcc/config/dragonfly.opt.urls
 create mode 100644 gcc/config/epiphany/epiphany.opt.urls
 create mode 100644 gcc/config/fr30/fr30.opt.urls
 create mode 100644 gcc/config/freebsd.opt.urls
 create mode 100644 gcc/config/frv/frv.opt.urls
 create mode 100644 gcc/config/ft32/ft32.opt.urls
 create mode 100644 gcc/config/fused-madd.opt.urls
 create mode 100644 gcc/config/g.opt.urls
 create mode 100644 gcc/config/gcn/gcn.opt.urls
 create mode 100644 gcc/config/gnu-user.opt.urls
 create mode 100644 gcc/config/h8300/h8300.opt.urls
 create mode 100644 gcc/config/hpux11.opt.urls
 create mode 100644 gcc/config/i386/cygming.opt.urls
 create mode 100644 gcc/config/i386/cygwin.opt.urls
 create mode 100644 gcc/config/i386/djgpp.opt.urls
 create mode 100644 gcc/config/i386/i386.opt.urls
 create mode 100644 gcc/config/i386/mingw-w64.opt.urls
 create mode 100644 gcc/config/i386/mingw.opt.urls
 create mode 100644 gcc/config/i386/nto.opt.urls
 create mode 100644 gcc/config/ia64/ia64.opt.urls
 create mode 100644 gcc/config/ia64/ilp32.opt.urls
 create mode 100644 gcc/config/ia64/vms.opt.urls
 create mode 100644 gcc/config/iq2000/iq2000.opt.urls
 create mode 100644 gcc/config/linux-android.opt.urls
 create mode 100644 gcc/config/linux.opt.urls
 create mode 100644 gcc/config/lm32/lm32.opt.urls
 create mode 100644 gcc/config/loongarch/loongarch.opt.urls
 create mode 100644 gcc/config/lynx.opt.urls
 create mode 100644 gcc/config/m32c/m32c.opt.urls
 create mode 100644 gcc/config/m32r/m32r.opt.urls
 create mode 100644 gcc/config/m68k/ieee.opt.urls
 create mode 100644 gcc/config/m68k/m68k-tables.opt.urls
 create mode 100644 gcc/config/m68k/m68k.opt.urls
 create mode 100644 gcc/config/m68k/uclinux.opt.urls
 create mode 100644 gcc/config/mcore/mcore.opt.urls
 create mode 100644 gcc/config/microblaze/microblaze.opt.urls
 create mode 100644 gcc/config/mips/mips-tables.opt.urls
 create mode 100644 gcc/config/mips/mips.opt.urls
 create mode 100644 gcc/config/mips/sde.opt.urls
 create mode 100644 gcc/config/mmix/mmix.opt.urls
 create mode 100644 gcc/config/mn10300/mn10300.opt.urls
 create mode 100644 gcc/config/moxie/moxie.opt.urls
 create mode 100644 gcc/config/msp430/msp430.opt.urls
 create mode 100644 gcc/config/nds32/nds32-elf.opt.urls
 create mode 100644 gcc/config/nds32/nds32-linux.opt.urls
 create mode 100644 gcc/config/nds32/nds32.opt.urls
 create mode 100644 gcc/config/netbsd-elf.opt.urls
 create mode 100644 gcc/config/netbsd.opt.urls
 create mode 100644 gcc/config/nios2/elf.opt.urls
 create mode 100644 gcc/config/nios2/nios2.opt.urls
 create mode 100644 gcc/config/nvptx/nvptx-gen.opt.urls
 create mode 100644 gcc/config/nvptx/nvptx.opt.urls
 create mode 100644 gcc/config/openbsd.opt.urls
 create mode 100644 gcc/config/or1k/elf.opt.urls
 create mode 100644 gcc/config/or1k/or1k.opt.urls
 create mode 100644 gcc/config/pa/pa-hpux.opt.urls
 create mode 100644 gcc/config/pa/pa-hpux1010.opt.urls
 create mode 100644 gcc/config/pa/pa-hpux1111.opt.urls
 create mode 100644 gcc/config/pa/pa-hpux1131.opt.urls
 create mode 100644 gcc/config/pa/pa.opt.urls
 create mode 100644 gcc/config/pa/pa64-hpux.opt.urls
 create mode 100644 gcc/config/pdp11/pdp11.opt.urls
 create mode 100644 gcc/config/pru/pru.opt.urls
 create mode 100644 gcc/config/riscv/riscv.opt.urls
 create mode 100644 gcc/config/rl78/rl78.opt.urls
 create mode 100644 gcc/config/rpath.opt.urls
 create mode 100644 gcc/config/rs6000/476.opt.urls
 create mode 100644 gcc/config/rs6000/aix64.opt.urls
 create mode 100644 gcc/config/rs6000/darwin.opt.urls
 create mode 100644 gcc/config/rs6000/linux64.opt.urls
 create mode 100644 gcc/config/rs6000/rs6000-tables.opt.urls
 create mode 100644 gcc/config/rs6000/rs6000.opt.urls
 create mode 100644 gcc/config/rs6000/sysv4.opt.urls
 create mode 100644 gcc/config/rtems.opt.urls
 create mode 100644 gcc/config/rx/elf.opt.urls
 create mode 100644 gcc/config/rx/rx.opt.urls
 create mode 100644 gcc/config/s390/s390.opt.urls
 create mode 100644 gcc/config/s390/tpf.opt.urls
 create mode 100644 gcc/config/sh/sh.opt.urls
 create mode 100644 gcc/config/sh/superh.opt.urls
 create mode 100644 gcc/config/sol2.opt.urls
 create mode 100644 gcc/config/sparc/long-double-switch.opt.urls
 create mode 100644 gcc/config/sparc/sparc.opt.urls
 create mode 100644 gcc/config/stormy16/stormy16.opt.urls
 create mode 100644 gcc/config/v850/v850.opt.urls
 create mode 100644 gcc/config/vax/elf.opt.urls
 create mode 100644 gcc/config/vax/vax.opt.urls
 create mode 100644 gcc/config/visium/visium.opt.urls
 create mode 100644 gcc/config/vms/vms.opt.urls
 create mode 100644 gcc/config/vxworks-smp.opt.urls
 create mode 100644 gcc/config/vxworks.opt.urls
 create mode 100644 gcc/config/xtensa/elf.opt.urls
 create mode 100644 gcc/config/xtensa/uclinux.opt.urls
 create mode 100644 gcc/config/xtensa/xtensa.opt.urls
 create mode 100644 gcc/d/lang.opt.urls
 create mode 100644 gcc/fortran/lang.opt.urls
 create mode 100644 gcc/go/lang.opt.urls
 create mode 100644 gcc/lto/lang.opt.urls
 create mode 100644 gcc/m2/lang.opt.urls
 create mode 100644 gcc/options-urls-cc-gen.awk
 create mode 100644 gcc/params.opt.urls
 create mode 100755 gcc/regenerate-opt-urls.py
 create mode 100644 gcc/rust/lang.opt.urls

-- 
2.26.3


^ permalink raw reply	[flat|nested] 47+ messages in thread

end of thread, other threads:[~2024-03-15 10:06 UTC | newest]

Thread overview: 47+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-11-10 21:42 [PATCH 0/3] Option handling: add documentation URLs David Malcolm
2023-11-10 21:42 ` [PATCH 1/3] options: add gcc/regenerate-opt-urls.py David Malcolm
2023-11-10 21:42 ` [PATCH 2/3] Add generated .opt.urls files David Malcolm
2023-11-12 10:56   ` Iain Buclaw
2023-11-13 14:07     ` David Malcolm
2023-11-13 13:11   ` Marc Poulhiès
2023-11-13 14:07     ` David Malcolm
2023-11-13 16:02       ` Marc Poulhiès
2023-12-19 14:47         ` Marc Poulhiès
2023-11-10 21:42 ` [PATCH 3/3] diagnostics: use the .opt.urls files to urlify quoted text David Malcolm
2023-11-14 17:44   ` Arthur Cohen
2023-11-14  0:12 ` [PATCH 0/3] Option handling: add documentation URLs Joseph Myers
2023-11-15 22:50   ` David Malcolm
2023-11-15 23:40     ` Joseph Myers
2023-11-16 14:28       ` [PATCH 0/4] v2 of " David Malcolm
2023-11-16 14:28         ` [PATCH 1/4] options: add gcc/regenerate-opt-urls.py David Malcolm
2023-11-16 14:28         ` [PATCH 2/4] Add generated .opt.urls files David Malcolm
2023-11-16 14:28         ` [PATCH 3/4] opts: add logic to generate options-urls.cc David Malcolm
2023-11-16 14:28         ` [PATCH 4/4] options: wire up options-urls.cc into gcc_urlifier David Malcolm
2023-11-21  1:09         ` [PATCH 0/4] v2 of Option handling: add documentation URLs Hans-Peter Nilsson
2023-11-21 13:57           ` David Malcolm
2023-11-21 14:12             ` Tobias Burnus
2023-11-21 15:23               ` David Malcolm
2023-11-21 23:43               ` Joseph Myers
2023-12-08 23:35                 ` David Malcolm
2023-12-10 23:35                   ` Mark Wielaard
2023-12-14 15:01                     ` [PATCH 0/4] v3 of: " David Malcolm
2023-12-14 15:01                       ` [PATCH 1/4; v3] options: add gcc/regenerate-opt-urls.py David Malcolm
2023-12-20  0:24                         ` Joseph Myers
2023-12-14 15:01                       ` [PATCH 2/4; v3] Add generated .opt.urls files David Malcolm
2023-12-14 15:01                       ` [PATCH 3/4; v2] opts: add logic to generate options-urls.cc David Malcolm
2023-12-14 15:01                       ` [PATCH 4/4; v2] options: wire up options-urls.cc into gcc_urlifier David Malcolm
2023-12-15  0:59                       ` [PATCH 0/4] v3 of: Option handling: add documentation URLs Mark Wielaard
2023-12-15 14:47                         ` David Malcolm
2024-01-04 14:57                         ` CI for "Option handling: add documentation URLs" David Malcolm
2024-02-18 22:58                           ` Mark Wielaard
2024-02-19 11:38                             ` Mark Wielaard
2024-02-22  3:57                             ` YunQiang Su
2024-02-24 17:42                               ` Mark Wielaard
2024-03-03 20:04                                 ` Mark Wielaard
2024-03-04 13:48                                   ` David Malcolm
2024-03-05 12:06                                     ` Mark Wielaard
2024-03-05 13:34                                       ` David Malcolm
2024-03-05 20:24                                         ` Mark Wielaard
2024-03-15  7:33                                           ` YunQiang Su
2024-03-15 10:06                                             ` Mark Wielaard
2023-12-20  0:28                       ` [PATCH 0/4] v3 of: Option handling: add documentation URLs Joseph Myers

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).