How to dump_decl_name to a string instead to a file?
Hello, I have a function that looks at identifiers of formal parameters. I found that when I ran this function on larger projects, the compiler segfaulted. I looked into this and I found that there are some formal parameters which have NULL in their DECL_NAME and that triggered a NULL dereference. I also noticed that these parameters when printed with dump_function_to_file were displayed using their DECL_UIDs. Digging a little bit deeper, the function responsible for printing parameters names is dump_decl_name. However, I am interested not in printing the names but having them as strings. I noticed that dump_decl_name takes a pretty_printer argument. Is it possible to somehow pass a pretty_printer and get the string instead of printing it? Thanks!
Re: Using source-level annotations to help GCC detect buffer overflows
Thanks for the reply here. I've snipped a bit to save space.
On 30/06/2021 19:12, Martin Sebor wrote:
On 6/29/21 12:31 PM, David Brown wrote:
On 29/06/2021 17:50, Martin Sebor wrote:
On 6/29/21 6:27 AM, David Brown wrote:
On 28/06/2021 21:06, Martin Sebor via Gcc wrote:
I wrote an article for the Red Hat Developer blog about how
to annotate code to get the most out of GCC's access checking
warnings like -Warray-bounds, -Wformat-overflow, and
-Wstringop-overflow. The article published last week:
https://developers.redhat.com/articles/2021/06/25/use-source-level-annotations-help-gcc-detect-buffer-overflows
Could these attributes not be attached to the arguments when the
function is called, or the parameters when the function is expanded?
After all, in cases such as the "access" attribute it is not the
function as such that has the access hints, it is the parameters of the
function.
(I'm talking here based on absolutely no knowledge of how this is
implemented, but it's always possible that a different view, unbiased by
knowing the facts, can inspire new ideas.)
Attaching these attributes to function parameters is an interesting
idea that might be worth exploring. We've talked about letting
attribute access apply to variables for other reasons (detecting
attempts to modify immutable objects, as I mention in the article).
so your suggestion would be in line with that. Associating two
variables that aren't parameters might be tricky.
It has always seemed to me that some of these attributes are about the
parameters, rather than the functions. It would make more sense when
using them if the attributes worked as qualifiers for the parameter
(vaguely like "restrict") and were written before the parameter itself,
rather than as a function attribute with a parameter index. Of course,
that gets messy when you have an attribute that ties two parameters
together (readonly with a size, for example).
Certainly since first reading about the "access" attributes, I have been
considering adding them to my current project. I have also been mulling
around in my head possibilities of making variadic templates in C++ that
add access attributes in the right places for some kinds of pointers -
but now that I know the attributes will get dropped for inline
functions, and such templates would involve inline functions, there is
little point. (Maybe I will still figure a neat way to do this for
external functions - it just won't be useful in as many places.)
Unfortunately, with extensive inlining and templates, C++ support
for these attributes is less robust than it ideally would be.
Improving it is on my to do list.
I think with modern coding styles and compiler usage, you have to assume
that /everything/ is likely to get inlined somewhere. Lots of C++
coding is done with header-only libraries, full of templates and inline
functions. Even variables can be templates or inline variables with
current standards. And no matter how the code is written, once you use
LTO then pretty much anything can be inlined back and forth, or
partially inlined, or partially outlined (is that the right term?), or
cloned. The concept of "function" in C or C++ that corresponds to an
externally visible assembly label, a sequence of assembly instructions
following a strict ABI and a "return", is fast disappearing.
I don't foresee you or the other gcc developers getting bored anytime soon!
Whether an attribute has an effect depends on the compilation stage
where it's handled. warn_unused_result is handled very early (well
before inlining) so it always has the expected effect. Attribute
nonnull is handled both early (to catch the simple cases) and also
later, after inlining, to benefit from some flow analysis, so its
effect is lost if the function it attaches to is inlined. Attribute
access is handled very late and so it suffers from this problem
even more.
I suppose some attributes are not needed for inline functions, since the
compiler has the full function definition and can figure some things out
itself. That would apply to "pure" and "const" functions, I expect.
I was going to agree, but then I tested it and found out that const
(and most likely pure) do actually make a difference on inline
functions. For example in the test case below the inequality is
folded to false.
int f (int);
__attribute__ ((const))
int g (int i) { return f (i); }
void h (int i)
{
if (g (i) != g (i))
__builtin_abort ();
}
On the other hand, the equality below is not folded unless f() is
also declared with attribute malloc:
void* f (void);
static int a[1];
__attribute__ ((malloc))
void* g (void) { return f (); }
void h (void)
{
if (g () == a)
__builtin_abort ();
}
With heavy inlining (e.g., with LTO) whether a function attribute
will have an effect or not in a given caller is anyone's guess :(
And if you want a parameter to be non-null, it's possible to do a check
inside the function:
exte
Re: How to dump_decl_name to a string instead to a file?
On Thu, Jul 1, 2021 at 9:40 AM Erick Ochoa via Gcc wrote: > > Hello, > > I have a function that looks at identifiers of formal parameters. I > found that when I ran this function on larger projects, the compiler > segfaulted. I looked into this and I found that there are some formal > parameters which have NULL in their DECL_NAME and that triggered a > NULL dereference. > > I also noticed that these parameters when printed with > dump_function_to_file were displayed using their DECL_UIDs. Digging a > little bit deeper, the function responsible for printing parameters > names is dump_decl_name. However, I am interested not in printing the > names but having them as strings. > > I noticed that dump_decl_name takes a pretty_printer argument. Is it > possible to somehow pass a pretty_printer and get the string instead > of printing it? You can look at its buffer I think. Richard. > Thanks!
Re: [PATCH] Port GCC documentation to Sphinx
On 6/30/21 5:43 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
From: Martin Liška
Date: Wed, 30 Jun 2021 16:04:32 +0200
Thanks, but does that mean @var will no longer stand out in the
produced Info format? That'd be sub-optimal, I think, because a clear
reference to a meta-syntactic variable will be lost.
Yes. An alternative approach for:
Show :samp:`Samp with a {variable}.`
can be using @var{variable}, resulting with the following info output:
Show ‘Samp with a VARIABLE.’
Does it seem reasonable?
Yes, the latter sounds reasonable.
Thanks.
Good, I modified the existing pull request for it:
https://github.com/sphinx-doc/sphinx/pull/9391
Martin
Re: [PATCH] Port GCC documentation to Sphinx
On 6/30/21 3:09 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
From: Martin Liška
Date: Wed, 30 Jun 2021 12:11:03 +0200
(Admittedly, Emacs by default hides some of the text of a
cross-reference, but not hiding them in this case produces an even
less legible text.)
If I'm correct, it's exactly what's documented in Sphinx FAQ here:
https://www.sphinx-doc.org/en/master/faq.html#displaying-links
and there's a suggested Emacs code snippet that should help with links.
Does it help?
It helps some, but not all of the issues disappear. For example,
stuff like this is still hard to read:
To select this standard in GCC, use one of the options -ansi
-
-std.‘=c90’ or -std.‘=iso9899:1990’
If I understand the notes correct, the '.' should be also hidden by e.g. Emacs.
About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by
default.
The quotes around the option values don't help.
Also, using the method proposed by Sphinx FAQ would need a change in
Emacs, which will take time to propagate. So my suggestion is to
minimize the use of such "inline" hyperlinks.
‘@`file'’
Read command-line options from ‘`file'’. The options read are
inserted in place of the original ‘@`file'’ option. If ‘`file'’
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
I can confirm that, so e.g.
Show :samp:`Samp with a {variable}.`
is transformed into:
Show @code{Samp with a @emph{variable}.}
Default info formatting is selected as:
@definfoenclose strong,`,'
@definfoenclose emph,`,'
We can adjust 'emph' formatting to nil, what do you think?
Something like that, yes. But the problem is: how will you format it
instead? The known alternatives, _foo_ and *foo* both use punctuation
characters, which will get in the way similarly to the quotes. Can
you format those in caps, like makeinfo does?
You are fully right, info is very simple format and it uses wrapping for the
formatting
purpose (by default * and _). So, I don't have any elegant solution.
4. Menus lost the short descriptions of the sub-sections. Example:
* Designated Initializers
* Case Ranges
* Cast to a Union Type
* Mixed Declarations, Labels and Code
* Declaring Attributes of Functions
vs
* Designated Inits::Labeling elements of initializers.
* Case Ranges:: 'case 1 ... 9' and such.
* Cast to Union:: Casting to union type from any member of the union.
* Mixed Declarations:: Mixing declarations and code.
* Function Attributes:: Declaring that functions have no side effects,
or that they can never return.
Looks like some bug to me.
Note also that nodes are now called by the same name as the section,
which means node names generally got much longer. Is that really a
good idea?
Well, I intentionally removed these and used simple TOC tree links
which take display text for a section title.
I would suggest to discuss these decisions first, perhaps on the
Texinfo mailing list? I'm accustomed to these short descriptions, but
I'm not sure how important they are for others.
Well, it was decision done during the transition of texinfo files into Sphinx.
I don't see why it should be discussed in Texinfo community.
Cheers,
Martin
Re: [PATCH] Port GCC documentation to Sphinx
> Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
> From: Martin Liška
> Date: Thu, 1 Jul 2021 14:44:10 +0200
>
> > It helps some, but not all of the issues disappear. For example,
> > stuff like this is still hard to read:
> >
> >To select this standard in GCC, use one of the options -ansi
> > -
> >-std.‘=c90’ or -std.‘=iso9899:1990’
> >
>
> If I understand the notes correct, the '.' should be also hidden by e.g.
> Emacs.
No, it doesn't. The actual text in the Info file is:
*note -std: f.‘=iso9899:1990’
and the period after " f" isn't hidden. Where does that "f" come from
and what is its purpose here? can it be removed (together with the
period)?
> About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by
> default.
Why is it a separate :samp:? IMO, the correct markup is to make the
entire string -std=iso9899:1990 have the same typeface. In Texinfo,
I'd use
@option{-std=iso9899:1990}
> >> We can adjust 'emph' formatting to nil, what do you think?
> >
> > Something like that, yes. But the problem is: how will you format it
> > instead? The known alternatives, _foo_ and *foo* both use punctuation
> > characters, which will get in the way similarly to the quotes. Can
> > you format those in caps, like makeinfo does?
>
> You are fully right, info is very simple format and it uses wrapping for the
> formatting
> purpose (by default * and _). So, I don't have any elegant solution.
Well, it sounds from another mail that you did find a solution: to
up-case the string in @var.
> >>> Note also that nodes are now called by the same name as the section,
> >>> which means node names generally got much longer. Is that really a
> >>> good idea?
> >>
> >> Well, I intentionally removed these and used simple TOC tree links
> >> which take display text for a section title.
> >
> > I would suggest to discuss these decisions first, perhaps on the
> > Texinfo mailing list? I'm accustomed to these short descriptions, but
> > I'm not sure how important they are for others.
>
> Well, it was decision done during the transition of texinfo files into Sphinx.
> I don't see why it should be discussed in Texinfo community.
This actually raises a more general issue with this Sphinx porting
initiative: what will be the canonical style guide for maintaining the
GCC manual in Sphinx, or more generally for writing GNU manuals in
Sphinx? For Texinfo, we have the Texinfo manual, which both documents
the language and provides style guidelines for how to use Texinfo for
producing good manuals. Contributors to GNU manuals are using those
guidelines for many years. Is there, or will there be, an equivalent
style guide for Sphinx? If not, how will the future contributors to
the GCC manuals know what are the writing and style conventions?
That is why I recommended to discuss this on the Texinfo list: that's
the place where such guidelines are discussed, and where we have
experts who understand the effects and consequences of using this or
that style. The current style in GNU manuals is to have the menus as
we see them in the existing GCC manuals: with a short description.
Maybe there are good reasons to deviate from that style, but
shouldn't this be at least presented and discussed, before the
decision is made? GCC developers are not the only ones who will be
reading the future GCC manuals.
Re: [PATCH] Port GCC documentation to Sphinx
On 7/1/21 3:33 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
From: Martin Liška
Date: Thu, 1 Jul 2021 14:44:10 +0200
It helps some, but not all of the issues disappear. For example,
stuff like this is still hard to read:
To select this standard in GCC, use one of the options -ansi
-
-std.‘=c90’ or -std.‘=iso9899:1990’
If I understand the notes correct, the '.' should be also hidden by e.g. Emacs.
No, it doesn't. The actual text in the Info file is:
*note -std: f.‘=iso9899:1990’
and the period after " f" isn't hidden. Where does that "f" come from
and what is its purpose here? can it be removed (together with the
period)?
It's name of the anchor used for the @ref. The names are automatically generated
by makeinfo. So there's an example:
This is the warning level of @ref{e,,-Wshift-overflow3} and …
becomes in info:
This is the warning level of *note -Wshift-overflow3: e. and …
I can ask the question at Sphinx, the Emacs script should hide that.
About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by
default.
Why is it a separate :samp:? IMO, the correct markup is to make the
entire string -std=iso9899:1990 have the same typeface. In Texinfo,
I'd use
@option{-std=iso9899:1990}
We can adjust 'emph' formatting to nil, what do you think?
Something like that, yes. But the problem is: how will you format it
instead? The known alternatives, _foo_ and *foo* both use punctuation
characters, which will get in the way similarly to the quotes. Can
you format those in caps, like makeinfo does?
You are fully right, info is very simple format and it uses wrapping for the
formatting
purpose (by default * and _). So, I don't have any elegant solution.
Well, it sounds from another mail that you did find a solution: to
up-case the string in @var.
I don't know. Some of them can be e.g. keywords and using upper-case does not
seem
to me feasible.
Note also that nodes are now called by the same name as the section,
which means node names generally got much longer. Is that really a
good idea?
Well, I intentionally removed these and used simple TOC tree links
which take display text for a section title.
I would suggest to discuss these decisions first, perhaps on the
Texinfo mailing list? I'm accustomed to these short descriptions, but
I'm not sure how important they are for others.
Well, it was decision done during the transition of texinfo files into Sphinx.
I don't see why it should be discussed in Texinfo community.
This actually raises a more general issue with this Sphinx porting
initiative: what will be the canonical style guide for maintaining the
GCC manual in Sphinx, or more generally for writing GNU manuals in
Sphinx? For Texinfo, we have the Texinfo manual, which both documents
the language and provides style guidelines for how to use Texinfo for
producing good manuals. Contributors to GNU manuals are using those
guidelines for many years. Is there, or will there be, an equivalent
style guide for Sphinx? If not, how will the future contributors to
the GCC manuals know what are the writing and style conventions?
No, I'm not planning any extra style guide. We will you standard Sphinx RST
manual and one can find many tutorials about how to do it.
That is why I recommended to discuss this on the Texinfo list: that's
the place where such guidelines are discussed, and where we have
experts who understand the effects and consequences of using this or
that style. The current style in GNU manuals is to have the menus as
we see them in the existing GCC manuals: with a short description.
Maybe there are good reasons to deviate from that style, but
shouldn't this be at least presented and discussed, before the
decision is made? GCC developers are not the only ones who will be
reading the future GCC manuals.
That seems to me a subtle adjustment and it's standard way how people generate
TOC in Sphinx. See e.g. the Linux kernel documentation:
https://www.kernel.org/doc/html/latest/
Martin
Buying an item on your site
"Hi, We need an advertising space with do-follow links on your blog savannah.gnu.org. • We provide 500+ words • no copy article • the duration will be a minimum of 1 year Can you please write to us if possible to place an article with a link leading to betting related site and how much it will cost? Please let me know if you are interested. Stay safe and healthy. Regards, "
Re: [PATCH] Port GCC documentation to Sphinx
Hello,
On Thu, 1 Jul 2021, Martin Liška wrote:
> On 7/1/21 3:33 PM, Eli Zaretskii wrote:
> > > Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
> > > From: Martin Liška
> > > Date: Thu, 1 Jul 2021 14:44:10 +0200
> > >
> > > > It helps some, but not all of the issues disappear. For example,
> > > > stuff like this is still hard to read:
> > > >
> > > > To select this standard in GCC, use one of the options -ansi
> > > >-
> > > > -std.‘=c90’ or -std.‘=iso9899:1990’
> > > >
> > >
> > > If I understand the notes correct, the '.' should be also hidden by e.g.
> > > Emacs.
> >
> > No, it doesn't. The actual text in the Info file is:
> >
> > *note -std: f.‘=iso9899:1990’
> >
> > and the period after " f" isn't hidden. Where does that "f" come from
> > and what is its purpose here? can it be removed (together with the
> > period)?
>
> It's name of the anchor used for the @ref. The names are automatically
> generated
> by makeinfo. So there's an example:
>
> This is the warning level of @ref{e,,-Wshift-overflow3} and …
>
> becomes in info:
> This is the warning level of *note -Wshift-overflow3: e. and …
>
> I can ask the question at Sphinx, the Emacs script should hide that.
Not everyone reads info within Emacs; even if there's an emacs solution to
postprocess info pages to make them nicer we can't rely on that. It must
look sensible without that. In this case it seems that already the
generated .texinfo input to makeinfo is bad, where does the 'e' (or 'f')
come from? The original texinfo file simply contains:
@option{-std=iso9899:1990}
so that's what perhaps should be generated, or maybe the anchor in @ref is
optional and could be left out if it doesn't provide any info (a single
character as anchor doesn't seem very useful)?
> > > > > We can adjust 'emph' formatting to nil, what do you think?
> > > >
> > > > Something like that, yes. But the problem is: how will you format it
> > > > instead? The known alternatives, _foo_ and *foo* both use punctuation
> > > > characters, which will get in the way similarly to the quotes. Can
> > > > you format those in caps, like makeinfo does?
> > >
> > > You are fully right, info is very simple format and it uses wrapping for
> > > the formatting
> > > purpose (by default * and _). So, I don't have any elegant solution.
> >
> > Well, it sounds from another mail that you did find a solution: to
> > up-case the string in @var.
>
> I don't know. Some of them can be e.g. keywords and using upper-case
> does not seem to me feasible.
Then that needs to be different already in the input, so that the
directive that (in info) capitalizes is only used in contexts where that
makes sense. People reading info pages will know that an all-caps word
often means a syntactic variable/placeholder, so that should be preserved.
Ciao,
Michael.
Re: [PATCH] Port GCC documentation to Sphinx
> Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
> From: Martin Liška
> Date: Thu, 1 Jul 2021 16:14:30 +0200
>
> >> If I understand the notes correct, the '.' should be also hidden by e.g.
> >> Emacs.
> >
> > No, it doesn't. The actual text in the Info file is:
> >
> > *note -std: f.‘=iso9899:1990’
> >
> > and the period after " f" isn't hidden. Where does that "f" come from
> > and what is its purpose here? can it be removed (together with the
> > period)?
>
> It's name of the anchor used for the @ref. The names are automatically
> generated
> by makeinfo. So there's an example:
>
> This is the warning level of @ref{e,,-Wshift-overflow3} and …
>
> becomes in info:
> This is the warning level of *note -Wshift-overflow3: e. and …
>
> I can ask the question at Sphinx, the Emacs script should hide that.
Emacs doesn't hide the period. But there shouldn't be a period to
begin with, since it's the middle of a sentence. The correct way of
writing this in Texinfo is to have some punctuation: a comma or a
semi-colon, after the closing brace, like this:
This is the warning level of @ref{e,,-Wshift-overflow3}, and …
Does Sphinx somehow generate the period if there's no comma, or does
it do it unconditionally, i.e. even if there is a punctuation after
the closing brace?
> > This actually raises a more general issue with this Sphinx porting
> > initiative: what will be the canonical style guide for maintaining the
> > GCC manual in Sphinx, or more generally for writing GNU manuals in
> > Sphinx? For Texinfo, we have the Texinfo manual, which both documents
> > the language and provides style guidelines for how to use Texinfo for
> > producing good manuals. Contributors to GNU manuals are using those
> > guidelines for many years. Is there, or will there be, an equivalent
> > style guide for Sphinx? If not, how will the future contributors to
> > the GCC manuals know what are the writing and style conventions?
>
> No, I'm not planning any extra style guide. We will you standard Sphinx RST
> manual and one can find many tutorials about how to do it.
Are you sure everything there is good for our manuals? Did you
compare the style conventions there with what we have in the Texinfo
manual?
Moreover, this means people who contribute to other manuals will now
have to learn two different styles, no? And that's in addition to
learning one more language.
> > That is why I recommended to discuss this on the Texinfo list: that's
> > the place where such guidelines are discussed, and where we have
> > experts who understand the effects and consequences of using this or
> > that style. The current style in GNU manuals is to have the menus as
> > we see them in the existing GCC manuals: with a short description.
> > Maybe there are good reasons to deviate from that style, but
> > shouldn't this be at least presented and discussed, before the
> > decision is made? GCC developers are not the only ones who will be
> > reading the future GCC manuals.
> >
>
> That seems to me a subtle adjustment and it's standard way how people generate
> TOC in Sphinx. See e.g. the Linux kernel documentation:
> https://www.kernel.org/doc/html/latest/
I don't think the GCC manuals should necessarily be bound by the
Sphinx standards. Where those standards are sub-optimal, it is
perfectly okay for GCC (and other projects) to deviate. GCC and other
GNU manuals used a certain style and convention for decades, so
there's more than enough experience and tradition to build on.
I will no longer pursue this point, but let me just say that I
consider it a mistake to throw away all the experience collected using
Texinfo just because Sphinx folks have other traditions and
conventions. It might be throwing the baby with the bathwater.
Re: [PATCH] Port GCC documentation to Sphinx
On 7/1/21 5:44 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
From: Martin Liška
Date: Thu, 1 Jul 2021 16:14:30 +0200
If I understand the notes correct, the '.' should be also hidden by e.g. Emacs.
No, it doesn't. The actual text in the Info file is:
*note -std: f.‘=iso9899:1990’
and the period after " f" isn't hidden. Where does that "f" come from
and what is its purpose here? can it be removed (together with the
period)?
It's name of the anchor used for the @ref. The names are automatically generated
by makeinfo. So there's an example:
This is the warning level of @ref{e,,-Wshift-overflow3} and …
becomes in info:
This is the warning level of *note -Wshift-overflow3: e. and …
I can ask the question at Sphinx, the Emacs script should hide that.
Emacs doesn't hide the period. But there shouldn't be a period to
begin with, since it's the middle of a sentence. The correct way of
writing this in Texinfo is to have some punctuation: a comma or a
semi-colon, after the closing brace, like this:
This is the warning level of @ref{e,,-Wshift-overflow3}, and …
I don't see why we should put a comma after an option reference.
Does Sphinx somehow generate the period if there's no comma, or does
it do it unconditionally, i.e. even if there is a punctuation after
the closing brace?
It's all related to Texinfo. Sphinx generates e.g.
Enabled by @ref{7,,-Wall} and something else.
as documented here:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ref.html
Then it ends with the following info output:
Enabled by *note -Wall: 7. and something else.
So the period is added by Texinfo. If I put comma after a reference, then
the period is not added there.
This actually raises a more general issue with this Sphinx porting
initiative: what will be the canonical style guide for maintaining the
GCC manual in Sphinx, or more generally for writing GNU manuals in
Sphinx? For Texinfo, we have the Texinfo manual, which both documents
the language and provides style guidelines for how to use Texinfo for
producing good manuals. Contributors to GNU manuals are using those
guidelines for many years. Is there, or will there be, an equivalent
style guide for Sphinx? If not, how will the future contributors to
the GCC manuals know what are the writing and style conventions?
No, I'm not planning any extra style guide. We will you standard Sphinx RST
manual and one can find many tutorials about how to do it.
Are you sure everything there is good for our manuals? Did you
compare the style conventions there with what we have in the Texinfo
manual?
I'm not sure, but I made the conversion from Texinfo as close as possible to
RST files.
I see the documentation markup natural and it matches with we write
documentation
in Texinfo.
Moreover, this means people who contribute to other manuals will now
have to learn two different styles, no? And that's in addition to
learning one more language.
Yes, people will have to learn RST. Similarly to git conversion, people also
had to learn another version control system (we used svn).
That is why I recommended to discuss this on the Texinfo list: that's
the place where such guidelines are discussed, and where we have
experts who understand the effects and consequences of using this or
that style. The current style in GNU manuals is to have the menus as
we see them in the existing GCC manuals: with a short description.
Maybe there are good reasons to deviate from that style, but
shouldn't this be at least presented and discussed, before the
decision is made? GCC developers are not the only ones who will be
reading the future GCC manuals.
That seems to me a subtle adjustment and it's standard way how people generate
TOC in Sphinx. See e.g. the Linux kernel documentation:
https://www.kernel.org/doc/html/latest/
I don't think the GCC manuals should necessarily be bound by the
Sphinx standards. Where those standards are sub-optimal, it is
perfectly okay for GCC (and other projects) to deviate. GCC and other
GNU manuals used a certain style and convention for decades, so
there's more than enough experience and tradition to build on.
What type of conversions and style are going to change with conversion to
Sphinx?
Do you see any of them worse than what we have now?
I will no longer pursue this point, but let me just say that I
consider it a mistake to throw away all the experience collected using
Texinfo just because Sphinx folks have other traditions and
conventions. It might be throwing the baby with the bathwater.
Again, please show up concrete examples. What you describe is very theoretical.
Thanks,
Martin
Re: [PATCH] Port GCC documentation to Sphinx
> Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
> From: Martin Liška
> Date: Thu, 1 Jul 2021 18:04:24 +0200
>
> > Emacs doesn't hide the period. But there shouldn't be a period to
> > begin with, since it's the middle of a sentence. The correct way of
> > writing this in Texinfo is to have some punctuation: a comma or a
> > semi-colon, after the closing brace, like this:
> >
> >This is the warning level of @ref{e,,-Wshift-overflow3}, and …
>
> I don't see why we should put a comma after an option reference.
You explained it yourself later on:
> It's all related to Texinfo. Sphinx generates e.g.
> Enabled by @ref{7,,-Wall} and something else.
>
> as documented here:
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ref.html
>
> Then it ends with the following info output:
>
> Enabled by *note -Wall: 7. and something else.
>
> So the period is added by Texinfo. If I put comma after a reference, then
> the period is not added there.
^
So the purpose of having the comma there is to avoid having a period
in the middle of a sentence, which is added by makeinfo (because the
Info readers need that). Having a comma there may seem a bit
redundant, but having a period will definitely look like a typo, if
not confuse the heck out of the reader, especially if you want to use
these inline cross-references so massively.
> > I don't think the GCC manuals should necessarily be bound by the
> > Sphinx standards. Where those standards are sub-optimal, it is
> > perfectly okay for GCC (and other projects) to deviate. GCC and other
> > GNU manuals used a certain style and convention for decades, so
> > there's more than enough experience and tradition to build on.
>
> What type of conversions and style are going to change with conversion to
> Sphinx?
Anything that is different from the style conventions described in the
Texinfo manual. We have many such conventions.
> Do you see any of them worse than what we have now?
I didn't bother reading the Sphinx guidelines yet, and don't know when
(and if) I will have time for that. I do think the comparison should
be part of the job or moving to Sphinx.
> > I will no longer pursue this point, but let me just say that I
> > consider it a mistake to throw away all the experience collected using
> > Texinfo just because Sphinx folks have other traditions and
> > conventions. It might be throwing the baby with the bathwater.
> >
>
> Again, please show up concrete examples. What you describe is very
> theoretical.
We've already seen one: the style of writing inline cross-references
with the equivalent of @ref. We also saw another: the way you
converted the menus. It is quite clear to me that there will be
others. So I'm not sure why you need more evidence that this could be
a real issue.
But maybe all of this is intentional: maybe the GCC project
consciously and deliberately decided to move away of the GNU
documentation style and conventions, and replace them with whatever
the Sphinx and RST conventions are? In that case, there's no reason
for me to even mention these aspects.
gcc-9-20210701 is now available
Snapshot gcc-9-20210701 is now available on https://gcc.gnu.org/pub/gcc/snapshots/9-20210701/ and on various mirrors, see http://gcc.gnu.org/mirrors.html for details. This snapshot has been generated from the GCC 9 git branch with the following options: git://gcc.gnu.org/git/gcc.git branch releases/gcc-9 revision 3686ff1a386b15ac74e371a07012202e414190ad You'll find: gcc-9-20210701.tar.xzComplete GCC SHA256=f9ed6090162589c81bea56a28e3760a1a588a94b0b1aa8bf59e56c5305cf3e5c SHA1=4de3773379c4750a52fc2997d1f6fa9efd39152c Diffs from 9-20210624 are available in the diffs/ subdirectory. When a particular snapshot is ready for public consumption the LATEST-9 link is updated and a message is sent to the gcc list. Please do not use a snapshot before it has been announced that way.
Question on tree LIM
Hi, I am investigating one degradation related to SPEC2017 exchange2_r, with loop vectorization on at -O2, it degraded by 6%. By some isolation, I found it isn't directly caused by vectorization itself, but exposed by vectorization, some stuffs for vectorization condition checks are hoisted out and they increase the register pressure, finally results in more spillings than before. If I simply disable tree lim4, I can see the gap becomes smaller (just 40%+ of the original), if further disable rtl lim, it just becomes to 30% of the original. It seems to indicate there is some room to improve in both LIMs. By quick scanning in tree LIM, I noticed that there seems no any considerations on register pressure, it looked intentional? I am wondering what's the design philosophy behind it? Is it because that it's hard to model register pressure well here? If so, it seems to put the burden onto late RA, which needs to have a good rematerialization support. btw, the example loop is at line 1150 from src exchange2.fppized.f90 1150 block(rnext:9, 7, i7) = block(rnext:9, 7, i7) + 10 The extra hoisted statements after the vectorization on this loop (cheap cost model btw) are: _686 = (integer(kind=8)) rnext_679; _ = (sizetype) _19; _1112 = _ * 12; _1927 = _1112 + 12; * _1895 = _1927 - _2650; _1113 = (unsigned long) rnext_679; * niters.6220_1128 = 10 - _1113; * _1021 = 9 - _1113; * bnd.6221_940 = niters.6220_1128 >> 2; * niters_vector_mult_vf.6222_939 = niters.6220_1128 & 18446744073709551612; _144 = niters_vector_mult_vf.6222_939 + _1113; tmp.6223_934 = (integer(kind=8)) _144; S.823_1004 = _1021 <= 2 ? _686 : tmp.6223_934; * ivtmp.6410_289 = (unsigned long) S.823_1004; PS: * indicates the one has a long live interval. BR, Kewen
