| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
This patch moves the documentation root URL infix for release branches
from get_option_url/make_doc_url to configure, such that only the default
changes and when users specify a custom documentation root URL, they don't
have to add gcc-MAJOR.MINOR.0 subdirectories for release branches.
Tested by checking
../configure --disable-bootstrap --enable-languages=c --disable-multilib
built trunk on
void
foo (int x)
{
__builtin_printf ("%ld\n", x);
}
testcase and looking for the URL in there, then repeating that after
changing gcc/BASE-VER to 14.1.0 and again after changing it to 14.1.1,
plus normal bootstrap/regtest.
2024-04-24 Jakub Jelinek <jakub@redhat.com>
PR other/114738
* opts.cc (get_option_url): Revert 2024-04-17 changes.
* gcc-urlifier.cc: Don't include diagnostic-core.h.
(gcc_urlifier::make_doc_url): Revert 2024-04-17 changes.
* configure.ac (documentation-root-url): On release branches
append gcc-MAJOR.MINOR.0/ to the default DOCUMENTATION_ROOT_URL.
* doc/install.texi (--with-documentation-root-url=): Document
the change of the default.
* configure: Regenerate.
|
|
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 <jakub@redhat.com>
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.
|
|
Given e.g. this missppelled option (omitting the trailing 's'):
$ LANG=C ./xgcc -B. -fno-inline-small-function
xgcc: error: unrecognized command-line option '-fno-inline-small-function'; did you mean '-fno-inline-small-functions'?
we weren't providing a documentation URL for the suggestion.
The issue is the URLification code uses find_opt, which doesn't consider
the various '-fno-' prefixes.
This patch adds a way to find the pertinent prefix remapping and uses it
when determining URLs.
With this patch, the suggestion '-fno-inline-small-functions' now gets a
documentation link (to that of '-finline-small-functions').
gcc/ChangeLog:
* gcc-urlifier.cc (gcc_urlifier::get_url_suffix_for_option):
Handle prefix mappings before calling find_opt.
(selftest::gcc_urlifier_cc_tests): Add example of urlifying a
"-fno-"-prefixed command-line option.
* opts-common.cc (get_option_prefix_remapping): New.
* opts.h (get_option_prefix_remapping): New decl.
Signed-off-by: David Malcolm <dmalcolm@redhat.com>
|
|
Changed in v2:
- split out from the code that generates options-urls.cc
- call the generated function, rather than use a generated array
- pass around lang_mask
gcc/ChangeLog:
* diagnostic.h (diagnostic_make_option_url_cb): Add lang_mask
param.
(diagnostic_context::make_option_url): Update for lang_mask param.
* gcc-urlifier.cc: Include "opts.h" and "options.h".
(gcc_urlifier::gcc_urlifier): Add lang_mask param.
(gcc_urlifier::m_lang_mask): New field.
(doc_urls): Make static.
(gcc_urlifier::get_url_for_quoted_text): Use label_text.
(gcc_urlifier::get_url_suffix_for_quoted_text): Use label_text.
Look for an option by name before trying a binary search in
doc_urls.
(gcc_urlifier::get_url_suffix_for_quoted_text): Use label_text.
(gcc_urlifier::get_url_suffix_for_option): New.
(make_gcc_urlifier): Add lang_mask param.
(selftest::gcc_urlifier_cc_tests): Update for above changes.
Verify that a URL is found for "-fpack-struct".
* gcc-urlifier.def: Drop options "--version" and "-fpack-struct".
* gcc-urlifier.h (make_gcc_urlifier): Add lang_mask param.
* gcc.cc (driver::global_initializations): Pass 0 for lang_mask
to make_gcc_urlifier.
* opts-diagnostic.h (get_option_url): Add lang_mask param.
* opts.cc (get_option_html_page): Remove special-casing for
analyzer and LTO.
(get_option_url_suffix): New.
(get_option_url): Reimplement.
(selftest::test_get_option_html_page): Rename to...
(selftest::test_get_option_url_suffix): ...this and update for
above changes.
(selftest::opts_cc_tests): Update for renaming.
* opts.h: Include "rich-location.h".
(get_option_url_suffix): New decl.
gcc/testsuite/ChangeLog:
* lib/gcc-dg.exp: Set TERM to xterm.
gcc/ChangeLog:
* toplev.cc (general_init): Pass lang_mask to urlifier.
Signed-off-by: David Malcolm <dmalcolm@redhat.com>
|
|
|
|
Without the change `./configure --enable-checking=release` bootstrap
fails as:
gcc/gcc-urlifier.cc:100:1: error: 'get_url_suffix_for_quoted_text()'
defined but not used [-Werror=unused-function]
This happens because the helper is used only in `ASSERT` macros which
don't always get expanded to executable code.
The fix marks helper function with `ATTRIBUTE_UNUSED`.
gcc/
PR bootstrap/112379
* gcc-urlifier.cc (get_url_suffix_for_quoted_text): Mark as
ATTRIBUTE_UNUSED.
|
|
In r10-3781-gd26082357676a3 GCC's pretty-print framework gained
the ability to emit embedding URLs via escape sequences
for marking up text output..
In r10-3783-gb4c7ca2ef3915a GCC started using this for the
[-Wname-of-option] emitted at the end of each diagnostic so that it
becomes a hyperlink to the documentation for that option on the GCC
website.
This makes it much more convenient for the user to locate pertinent
documentation when a diagnostic is emitted.
The above involved special-casing in one specific place, but there is
plenty of quoted text throughout GCC's diagnostic messages that could
usefully have a documentation URL: references to options, pragmas, etc
This patch adds a new optional "urlifier" parameter to pp_format.
The idea is that a urlifier object has responsibility for mapping from
quoted strings in diagnostic messages to URLs, and pp_format has the
ability to automatically add URL escapes for strings that the urlifier
gives it URLs for.
For example, given the format string:
"%<#pragma pack%> has no effect with %<-fpack-struct%>"
with this patch GCC is able to automatically linkify the "#pragma pack"
text to
https://gcc.gnu.org/onlinedocs/gcc/Structure-Layout-Pragmas.html
and the "-fpack-struct" text to:
https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#index-fpack-struct
and we don't have to modify the format string itself.
This is only done for the pp_format within
diagnostic_context::report_diagnostic i.e. just for the primary message
in each diagnostics, and not for other places within GCC that use pp
format internally.
"urlifier" is an abstract base class, with a GCC-specific subclass
implementing the logic for generating URLs into GCC's HTML
documentation via binary search in a data table. This patch implements
the gcc_urlifier with a small table generated by hand; the data table in
this patch only covers various pragmas and the option referenced by the
above pragma message.
I have a followup patch that scripts the creation of this data by
directly scraping the output of "make html", thus automating all this,
and (I hope) minimizing the work of ensuring that documentation URLs
emitted by GCC match the generated documentation.
gcc/ChangeLog:
* Makefile.in (GCC_OBJS): Add gcc-urlifier.o.
(OBJS): Likewise.
gcc/c-family/ChangeLog:
* c-pragma.cc:: (handle_pragma_push_options): Fix missing "GCC" in
name of pragma in "junk" message.
(handle_pragma_pop_options): Likewise.
gcc/ChangeLog:
* diagnostic.cc: Include "pretty-print-urlifier.h".
(diagnostic_context::initialize): Initialize m_urlifier.
(diagnostic_context::finish): Clean up m_urlifier
(diagnostic_report::diagnostic): m_urlifier to pp_format.
* diagnostic.h (diagnostic_context::m_urlifier): New field.
* gcc-urlifier.cc: New file.
* gcc-urlifier.def: New file.
* gcc-urlifier.h: New file.
* gcc.cc: Include "gcc-urlifier.h".
(driver::global_initializations): Initialize global_dc->m_urlifier.
* pretty-print-urlifier.h: New file.
* pretty-print.cc: Include "pretty-print-urlifier.h".
(obstack_append_string): New.
(urlify_quoted_string): New.
(pp_format): Add "urlifier" param and use it to implement optional
urlification of quoted text strings.
(pp_output_formatted_text): Make buffer a const pointer.
(selftest::pp_printf_with_urlifier): New.
(selftest::test_urlification): New.
(selftest::pretty_print_cc_tests): Call it.
* pretty-print.h (class urlifier): New forward declaration.
(pp_format): Add optional urlifier param.
* selftest-run-tests.cc (selftest::run_tests): Call
selftest::gcc_urlifier_cc_tests .
* selftest.h (selftest::gcc_urlifier_cc_tests): New decl.
* toplev.cc: Include "gcc-urlifier.h".
(general_init): Initialize global_dc->m_urlifier.
Signed-off-by: David Malcolm <dmalcolm@redhat.com>
|
