5a022062d2
This is v2 of the patch; v1 was here: https://gcc.gnu.org/pipermail/gcc-patches/2024-June/655541.html Changed in v2: * added a new TARGET_DOCUMENTATION_NAME hook for figuring out which documentation URL to use when there are multiple per-target docs, such as for __attribute__((interrupt)); implemented this for all targets that have target-specific attributes * moved attribute_urlifier and its support code to a new gcc-attribute-urlifier.cc since it needs to use targetm for the above; gcc-urlifier.o is used by the driver. * fixed extend.texi so that some attributes that failed to appear in attr-urls.def now do so (affected nvptx "kernel" and "shared" attrs) * regenerated attr-urls.def for the above fix, and bringing in attributes added since v1 of the patch In r14-5118-gc5db4d8ba5f3de I added a mechanism to automatically add documentation URLs to quoted strings in diagnostics. In r14-6920-g9e49746da303b8 I added a mechanism to generate URLs for mentions of command-line options in quoted strings in diagnostics. This patch does a similar thing for attributes. It adds a new Python 3 script to scrape the generated HTML looking for documentation of attributes, and uses this to (re)generate a new gcc/attr-urls.def file. Running "make regenerate-attr-urls" after rebuilding the HTML docs will regenerate gcc/attr-urls.def in the source directory. The patch uses this to optionally add doc URLs for attributes in any diagnostic emitted during the lifetime of a auto_urlify_attributes instance, and adds such instances everywhere that a diagnostic refers to a diagnostic within quotes (based on grepping the source tree for references to attributes in strings and in code). For example, given: $ ./xgcc -B. -S ../../src/gcc/testsuite/gcc.dg/attr-access-2.c ../../src/gcc/testsuite/gcc.dg/attr-access-2.c:14:16: warning: attribute ‘access(read_write, 2, 3)’ positional argument 2 conflicts with previous designation by argument 1 [-Wattributes] with this patch the quoted text `access(read_write, 2, 3)' automatically gains the URL for our docs for "access": https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-access-function-attribute in a sufficiently modern terminal. Like r14-6920-g9e49746da303b8 this avoids the Makefile target depending on the generated HTML, since a missing URL is a minor problem, whereas requiring all users to build HTML docs seems more involved. Doing so also avoids Python 3 as a build requirement for everyone, but instead just for developers addding attributes. Like the options, we could add a CI test for this. The patch gathers both general and target-specific attributes. For example, the function attribute "interrupt" has 19 URLs within our docs: one common, and 18 target-specific ones. The patch adds a new target hook used when selecting the most appropriate one. Signed-off-by: David Malcolm <dmalcolm@redhat.com> gcc/ChangeLog: * Makefile.in (OBJS): Add -attribute-urlifier.o. (ATTR_URLS_HTML_DEPS): New. (regenerate-attr-urls): New. (regenerate-attr-urls-unit-test): New. * attr-urls.def: New file. * attribs.cc: Include "gcc-urlifier.h". (decl_attributes): Use auto_urlify_attributes. * config/aarch64/aarch64.cc (TARGET_DOCUMENTATION_NAME): New. * config/arc/arc.cc (TARGET_DOCUMENTATION_NAME): New. * config/arm/arm.cc (TARGET_DOCUMENTATION_NAME): New. * config/bfin/bfin.cc (TARGET_DOCUMENTATION_NAME): New. * config/bpf/bpf.cc (TARGET_DOCUMENTATION_NAME): New. * config/epiphany/epiphany.cc (TARGET_DOCUMENTATION_NAME): New. * config/gcn/gcn.cc (TARGET_DOCUMENTATION_NAME): New. * config/h8300/h8300.cc (TARGET_DOCUMENTATION_NAME): New. * config/i386/i386.cc (TARGET_DOCUMENTATION_NAME): New. * config/ia64/ia64.cc (TARGET_DOCUMENTATION_NAME): New. * config/m32c/m32c.cc (TARGET_DOCUMENTATION_NAME): New. * config/m32r/m32r.cc (TARGET_DOCUMENTATION_NAME): New. * config/m68k/m68k.cc (TARGET_DOCUMENTATION_NAME): New. * config/mcore/mcore.cc (TARGET_DOCUMENTATION_NAME): New. * config/microblaze/microblaze.cc (TARGET_DOCUMENTATION_NAME): New. * config/mips/mips.cc (TARGET_DOCUMENTATION_NAME): New. * config/msp430/msp430.cc (TARGET_DOCUMENTATION_NAME): New. * config/nds32/nds32.cc (TARGET_DOCUMENTATION_NAME): New. * config/nvptx/nvptx.cc (TARGET_DOCUMENTATION_NAME): New. * config/riscv/riscv.cc (TARGET_DOCUMENTATION_NAME): New. * config/rl78/rl78.cc (TARGET_DOCUMENTATION_NAME): New. * config/rs6000/rs6000.cc (TARGET_DOCUMENTATION_NAME): New. * config/rx/rx.cc (TARGET_DOCUMENTATION_NAME): New. * config/s390/s390.cc (TARGET_DOCUMENTATION_NAME): New. * config/sh/sh.cc (TARGET_DOCUMENTATION_NAME): New. * config/stormy16/stormy16.cc (TARGET_DOCUMENTATION_NAME): New. * config/v850/v850.cc (TARGET_DOCUMENTATION_NAME): New. * config/visium/visium.cc (TARGET_DOCUMENTATION_NAME): New. gcc/analyzer/ChangeLog: * region-model.cc: Include "gcc-urlifier.h". (reason_attr_access::emit): Use auto_urlify_attributes. * sm-taint.cc: Include "gcc-urlifier.h". (tainted_access_attrib_size::emit): Use auto_urlify_attributes. gcc/c-family/ChangeLog: * c-attribs.cc: Include "gcc-urlifier.h". (positional_argument): Use auto_urlify_attributes. * c-common.cc: Include "gcc-urlifier.h". (parse_optimize_options): Use auto_urlify_attributes with OPT_Wattributes. (attribute_fallthrough_p): Use auto_urlify_attributes. * c-warn.cc: Include "gcc-urlifier.h". (diagnose_mismatched_attributes): Use auto_urlify_attributes. gcc/c/ChangeLog: * c-decl.cc: Include "gcc-urlifier.h". (start_decl): Use auto_urlify_attributes with OPT_Wattributes. (start_function): Likewise. * c-parser.cc: Include "gcc-urlifier.h". (c_parser_statement_after_labels): Use auto_urlify_attributes with OPT_Wattributes. * c-typeck.cc: Include "gcc-urlifier.h". (maybe_warn_nodiscard): Use auto_urlify_attributes with OPT_Wunused_result. gcc/cp/ChangeLog: * cp-gimplify.cc: Include "gcc-urlifier.h". (process_stmt_hotness_attribute): Use auto_urlify_attributes with OPT_Wattributes. * cvt.cc: Include "gcc-urlifier.h". (maybe_warn_nodiscard): Use auto_urlify_attributes with OPT_Wunused_result. * decl.cc: Include "gcc-urlifier.h". (start_decl): Use auto_urlify_attributes. (start_preparsed_function): Likewise. gcc/ChangeLog: * diagnostic.cc (diagnostic_context::override_urlifier): New. * diagnostic.h (diagnostic_context::override_urlifier): New decl. * doc/extend.texi (Nvidia PTX Function Attributes): Update @cindex to specify that "kernel" is a function attribute and "shared" is a variable attribute, so that these entries are recognized by the regex in regenerate-attr-urls.py. * doc/tm.texi: Regenerate. * doc/tm.texi.in (TARGET_DOCUMENTATION_NAME): New. * gcc-attribute-urlifier.cc: New file. * gcc-urlifier.cc: Include diagnostic.h. (gcc_urlifier::make_doc): Convert to... (make_doc_url): ...this. (auto_override_urlifier::auto_override_urlifier): New. (auto_override_urlifier::~auto_override_urlifier): New. (selftest::gcc_urlifier_cc_tests): Split out body into... (selftest::test_gcc_urlifier): ...this. * gcc-urlifier.h: Include "pretty-print-urlifier.h" and "label-text.h". (make_doc_url): New decl. (class auto_override_urlifier): New. (class attribute_urlifier): New. (class auto_urlify_attributes): New. * gimple-ssa-warn-access.cc: Include "gcc-urlifier.h". (pass_waccess::execute): Use auto_urlify_attributes. * gimplify.cc: Include "gcc-urlifier.h". (expand_FALLTHROUGH): Use auto_urlify_attributes. * internal-fn.cc: Define INCLUDE_MEMORY and include "gcc-urlifier.h. (expand_FALLTHROUGH): Use auto_urlify_attributes. * ipa-pure-const.cc: Include "gcc-urlifier.h. (suggest_attribute): Use auto_urlify_attributes. * ipa-strub.cc: Include "gcc-urlifier.h. (can_strub_p): Use auto_urlify_attributes. * regenerate-attr-urls.py: New file. * selftest-run-tests.cc (selftest::run_tests): Call gcc_attribute_urlifier_cc_tests. * selftest.h (selftest::gcc_attribute_urlifier_cc_tests): New decl. * target.def (documentation_name): New DEFHOOKPOD. * tree-cfg.cc: Include "gcc-urlifier.h. (do_warn_unused_result): Use auto_urlify_attributes. * tree-ssa-uninit.cc: Include "gcc-urlifier.h. (maybe_warn_read_write_only): Use auto_urlify_attributes. (maybe_warn_pass_by_reference): Likewise. Signed-off-by: David Malcolm <dmalcolm@redhat.com> |
||
|---|---|---|
| .forgejo | ||
| .github | ||
| c++tools | ||
| config | ||
| contrib | ||
| fixincludes | ||
| gcc | ||
| gnattools | ||
| gotools | ||
| include | ||
| INSTALL | ||
| libada | ||
| libatomic | ||
| libbacktrace | ||
| libcc1 | ||
| libcody | ||
| libcpp | ||
| libdecnumber | ||
| libffi | ||
| libgcc | ||
| libgfortran | ||
| libgm2 | ||
| libgo | ||
| libgomp | ||
| libgrust | ||
| libiberty | ||
| libitm | ||
| libobjc | ||
| libphobos | ||
| libquadmath | ||
| libsanitizer | ||
| libssp | ||
| libstdc++-v3 | ||
| libvtv | ||
| lto-plugin | ||
| maintainer-scripts | ||
| zlib | ||
| .b4-config | ||
| .dir-locals.el | ||
| .gitattributes | ||
| .gitignore | ||
| ABOUT-NLS | ||
| ar-lib | ||
| ChangeLog | ||
| ChangeLog.jit | ||
| ChangeLog.tree-ssa | ||
| compile | ||
| config-ml.in | ||
| config.guess | ||
| config.rpath | ||
| config.sub | ||
| configure | ||
| configure.ac | ||
| COPYING | ||
| COPYING.LIB | ||
| COPYING.RUNTIME | ||
| COPYING3 | ||
| COPYING3.LIB | ||
| depcomp | ||
| install-sh | ||
| libtool-ldflags | ||
| libtool.m4 | ||
| ltgcc.m4 | ||
| ltmain.sh | ||
| ltoptions.m4 | ||
| ltsugar.m4 | ||
| ltversion.m4 | ||
| lt~obsolete.m4 | ||
| MAINTAINERS | ||
| Makefile.def | ||
| Makefile.in | ||
| Makefile.tpl | ||
| missing | ||
| mkdep | ||
| mkinstalldirs | ||
| move-if-change | ||
| multilib.am | ||
| README | ||
| SECURITY.txt | ||
| symlink-tree | ||
| test-driver | ||
| ylwrap | ||
This directory contains the GNU Compiler Collection (GCC). The GNU Compiler Collection is free software. See the files whose names start with COPYING for copying permission. The manuals, and some of the runtime libraries, are under different terms; see the individual source files for details. The directory INSTALL contains copies of the installation information as HTML and plain text. The source of this information is gcc/doc/install.texi. The installation information includes details of what is included in the GCC sources and what files GCC installs. See the file gcc/doc/gcc.texi (together with other files that it includes) for usage and porting information. An online readable version of the manual is in the files gcc/doc/gcc.info*. See http://gcc.gnu.org/bugs/ for how to report bugs usefully. Copyright years on GCC source files may be listed using range notation, e.g., 1987-2012, indicating that every year in the range, inclusive, is a copyrightable year that could otherwise be listed individually.