Nabble - Gnu - Coding Standards

Re: path vs. file name

2009-11-18T14:32:40Z

Thanks, the usage of path/pathname is sadly to scattered around for me
to spend time fixing the issue by my self. Do we have any list of
volunteers that where one could ask for help?

Just post on gnu-prog-discuss.

Re: path vs. file name

2009-11-18T10:56:24Z

Thanks, the usage of path/pathname is sadly to scattered around for me
to spend time fixing the issue by my self. Do we have any list of
volunteers that where one could ask for help?

Re: path vs. file name

2009-11-16T15:36:37Z

Date: Mon, 16 Nov 2009 04:06:37 -0500
From: Richard Stallman <rms@...>
To: karl@... (Karl Berry)
Subject: Re: [ams@...: path vs. file name]

AMS wrote:

Would it be possible to change the following to allow for both `path'
and `file name' to be suggested and remove the discouragement for
using `path' to refer to file names? It is infact incorrect, since we
use the term path for file names in many GNU programs already.

This is no reason to change a good decision.
Can you find those programs, and ask their maintainers to fix the usage?

Re: path vs. file name

2009-11-15T14:36:56Z

Would it be possible to change the following to allow for both `path'
and `file name'

I asked rms.

path vs. file name

2009-11-14T02:10:38Z

Would it be possible to change the following to allow for both `path'
and `file name' to be suggested and remove the discouragement for
using `path' to refer to file names? It is infact incorrect, since we
use the term path for file names in many GNU programs already.

| Please do not use the term "pathname" that is used in Unix
| documentation; use "file name" (two words) instead. We use the term
| "path" only for search paths, which are lists of directory names.

Re: 'tar' in the GNU Coding Standards

2009-11-02T22:20:21Z

* Dr. David Kirkby wrote on Sun, Nov 01, 2009 at 10:38:51PM CET:
>
> The best way IMHO would be for GNU tar to default to a more portable
> format rather than its own 'standard'.

I'm not sure whether that will happen: the more portable format has more
limitations, such as the 99 character path length limit.

> Reading http://www.gnu.org/software/automake/manual/tar/Formats.html
>
> it implies this will happen. The sooner the better I feel. I do not
> know how well Sun's tar will handle the tar format of GNU tar then.

I'm not sure what the text is meant to imply will happen, but I find it
weird if the GNU tar manual were to imply what direction GNU Automake
will evolve towards in the future.

> I know there is one package in the Sage project which will not
> extract with Sun's tar. But if one uses Sun's tar to create the
> tarball, GNU tar can extract it ok.

Well, can the tarball be created ok with the v7 format, and no symlinks?

> >The 'Releases' node of the GCS describes some of the precautions to use
> >when creating package tarballs. If possible, I think it would be
> >prudent to advise the tarball creator to use the most portable archive
> >format possible. The GNU tar manual has `Portability' and `Formats'
> >sections about this, and the GNU Automake manual node `Options' shows
> >how to apply them to your package, should you use automake. Automake
> >uses old v7 archive format by default for `make dist'.
>
> That sounds sensible. I'm not sure why GNU tar does not default to
> something sensible like that.

I'm afraid you'll have to ask on a tar mailing list, or read its manual
for a rationale.

> >>hence it's better the user was able to write:
> >>
> >>$ TAR=/usr/local/bin/gtar
> >>$ export TAR
> >
> >How would you set $(TAR) if not supplied by the user though?
>
> I'm not a wizard on Makefiles, but is it not possible to write them
> in such a way that if the environment variable 'TAR' is unset, then
> $TAR gets set to 'tar', otherwise it is whatever the TAR is set to?

Well. The make part of the answer is: Yes, with GNU make you can just
write
TAR ?= tar

and with portable make, we can of course still default TAR to tar in
configure.ac:
: ${TAR=tar}
AC_SUBST([TAR])

But that's not the real knack. If plain 'tar' is not sufficient, as you
imply, then the user must choose something different, or we need to have
a macro that automatically selects a better alternative. So, either we
need to amend installation instructions, which we're fairly reluctant to
do, or we need a good kind of test to distinguish good 'tar' from bad
'tar', which I wouldn't really know how to do well.

> Jöerg Schilling's 'star' is one other implementation I am aware of.
> He seems to have the knack of writing extremely portable code.

That's fairly irrelevant for the issue at hand though; the question is
not whether there exists a portable tar program (GNU tar would be a
candidate as well), but which kind of functionality you can expect to
be *already installed* on your users' systems.

> >BTW, I agree that egrep and fgrep should be fixed, as you noted
> >somewhere in this thread.
>
> Can you personally do something about the fgrep and egrep? Or do you
> know who to handle the issue to?

I'll handle it.

Thanks,
Ralf

Re: 'tar' in the GNU Coding Standards

2009-11-01T13:38:51Z

Ralf Wildenhues wrote:

> Hello David,
>
> sorry about the delay.
>
> * Dr. David Kirkby wrote on Sat, Oct 24, 2009 at 04:35:36PM CEST:
>> ----------------------------------------------------------
>> The configure script and the Makefile rules for building and
>> installation should not use any utilities directly except these:
>>
>> awk cat cmp cp diff echo egrep expr false grep install-info
>> ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch tr true
>>
>> ----------------------------------------------------------
>
>> I believe 'tar' should removed from that list, but allow someone to
>> select a variable for 'tar'. On Solaris for instance, Sun's tar can
>> not extract all tar files programs written with GNU tar, though it
>> does manage most of them. (It's not simply the fact some options
>> just as z and j are not supported, but more fundamental issues.
>
> I agree that there are problems with non-portable tarballs. That brings
> up a couple of points:

The best way IMHO would be for GNU tar to default to a more portable format
rather than its own 'standard'.

Reading http://www.gnu.org/software/automake/manual/tar/Formats.html

it implies this will happen. The sooner the better I feel. I do not know how
well Sun's tar will handle the tar format of GNU tar then.

> The typical user downloading a tarball from the net and extracting it
> does not use the $(TAR) in the makefile inside the tarball; he uses tar
> on the command line, before the makefile is used for the first time, and
> he doesn't need `make dist' or similar which would use tar again from
> within the makefile.

> If tar is not sufficient to extract some package tarball, then this
> ought to be clear from the installation instructions. However,
> requiring, say, GNU tar in general, would be quite some move; we don't
> usually any other GNU tools to be preinstalled, if only for
> bootstrapping reasons.

A much easier move would be to get GNU tar to write by default in a more
portable format.

I know there is one package in the Sage project which will not extract with
Sun's tar. But if one uses Sun's tar to create the tarball, GNU tar can extract
it ok.

> The 'Releases' node of the GCS describes some of the precautions to use
> when creating package tarballs. If possible, I think it would be
> prudent to advise the tarball creator to use the most portable archive
> format possible. The GNU tar manual has `Portability' and `Formats'
> sections about this, and the GNU Automake manual node `Options' shows
> how to apply them to your package, should you use automake. Automake
> uses old v7 archive format by default for `make dist'.

That sounds sensible. I'm not sure why GNU tar does not default to something
sensible like that.

> I'm unsure of how wide-spread installation of a more capable tar program
> is on systems with a limited vendor tar.

>> Issues with non-GNU versions of tar are common on lots of non-linux
>> platforms when using GNU tools.
>>
>> hence it's better the user was able to write:
>>
>> $ TAR=/usr/local/bin/gtar
>> $ export TAR
>
> How would you set $(TAR) if not supplied by the user though?

I'm not a wizard on Makefiles, but is it not possible to write them in such a
way that if the environment variable 'TAR' is unset, then $TAR gets set to
'tar', otherwise it is whatever the TAR is set to?

> I haven't
> yet seen a good Autoconf test for a capable tar, besides one that
> wouldn't select GNU tar only; writing such a macro would probably be a
> good thing to do before changing GCS. Requiring the user to select a
> tar program manually seems a bit awkward. Note that one alternative to
> choosing a tar program is to use something like the `missing' program
> that Automake selects for some tools that may not be present. OTOH I
> don't see how packages can ignore or replace tar's functionality in that
> case, unlike, say, makeinfo, where the info files are typically
> distributed in the tarball.

Jöerg Schilling's 'star' is one other implementation I am aware of. He seems to
have the knack of writing extremely portable code.

> BTW, I agree that egrep and fgrep should be fixed, as you noted
> somewhere in this thread.

Can you personally do something about the fgrep and egrep? Or do you know who to
handle the issue to?

> Thanks,
> Ralf
>

Dave

Re: 'tar' in the GNU Coding Standards

2009-11-01T01:42:13Z

Hello David,

sorry about the delay.

* Dr. David Kirkby wrote on Sat, Oct 24, 2009 at 04:35:36PM CEST:
> ----------------------------------------------------------
> The configure script and the Makefile rules for building and
> installation should not use any utilities directly except these:
>
> awk cat cmp cp diff echo egrep expr false grep install-info
> ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch tr true
>
> ----------------------------------------------------------

> I believe 'tar' should removed from that list, but allow someone to
> select a variable for 'tar'. On Solaris for instance, Sun's tar can
> not extract all tar files programs written with GNU tar, though it
> does manage most of them. (It's not simply the fact some options
> just as z and j are not supported, but more fundamental issues.

I agree that there are problems with non-portable tarballs. That brings
up a couple of points:

The typical user downloading a tarball from the net and extracting it
does not use the $(TAR) in the makefile inside the tarball; he uses tar
on the command line, before the makefile is used for the first time, and
he doesn't need `make dist' or similar which would use tar again from
within the makefile.

If tar is not sufficient to extract some package tarball, then this
ought to be clear from the installation instructions. However,
requiring, say, GNU tar in general, would be quite some move; we don't
usually any other GNU tools to be preinstalled, if only for
bootstrapping reasons.

The 'Releases' node of the GCS describes some of the precautions to use
when creating package tarballs. If possible, I think it would be
prudent to advise the tarball creator to use the most portable archive
format possible. The GNU tar manual has `Portability' and `Formats'
sections about this, and the GNU Automake manual node `Options' shows
how to apply them to your package, should you use automake. Automake
uses old v7 archive format by default for `make dist'.

I'm unsure of how wide-spread installation of a more capable tar program
is on systems with a limited vendor tar.

> Issues with non-GNU versions of tar are common on lots of non-linux
> platforms when using GNU tools.
>
> hence it's better the user was able to write:
>
> $ TAR=/usr/local/bin/gtar
> $ export TAR

How would you set $(TAR) if not supplied by the user though? I haven't
yet seen a good Autoconf test for a capable tar, besides one that
wouldn't select GNU tar only; writing such a macro would probably be a
good thing to do before changing GCS. Requiring the user to select a
tar program manually seems a bit awkward. Note that one alternative to
choosing a tar program is to use something like the `missing' program
that Automake selects for some tools that may not be present. OTOH I
don't see how packages can ignore or replace tar's functionality in that
case, unlike, say, makeinfo, where the info files are typically
distributed in the tarball.

BTW, I agree that egrep and fgrep should be fixed, as you noted
somewhere in this thread.

Thanks,
Ralf

Re: 'tar' in the GNU Coding Standards

2009-10-25T01:49:09Z

Karl Berry wrote:

> Hi David,
>
> Thanks for writing.
>
> I believe 'tar' should removed from that list, but allow someone to
> select a variable for 'tar'.
>
> In typical Makefiles tar is already a variable, as are others in that
> list. I'm not sure that we need to standardize the variable names for
> them ...
>
> Ralf, wdyt?
>
> Thanks,
> Karl
>

The piece above this says:

"The configure script and the Makefile rules for building and installation
should not use any utilities directly except these: "

so this is not only Makefiles, but configure scripts too.

I've seen several makefiles and scripts over the years where 'tar' is hard-coded
in, which will cause problems in some cases.

It should also be noted that egrep is not required to be installed on any system
conforming to POSIX 2004.

http://www.opengroup.org/onlinepubs/009695399/

If the intension is to write portable programs, one can't rely on using the
latest standards, but even the 2008 POSIX specification

http://www.opengroup.org/onlinepubs/9699919799/

does not require egrep. I learned that from reading the autoconf manual!

grep -E is supposed to support extended regular expressions (and GNU's grep
does), though according to the autoconf manual, not all greps conform to POSIX
and so therefore they do not all support grep -E.

Dave

Re: 'tar' in the GNU Coding Standards

2009-10-24T15:11:05Z

Hi David,

Thanks for writing.

I believe 'tar' should removed from that list, but allow someone to
select a variable for 'tar'.

In typical Makefiles tar is already a variable, as are others in that
list. I'm not sure that we need to standardize the variable names for
them ...

Ralf, wdyt?

Thanks,
Karl

'tar' in the GNU Coding Standards

2009-10-24T07:35:36Z

At: http://www.gnu.org/prep/standards/standards.html#Names

it says:
----------------------------------------------------------
The configure script and the Makefile rules for building and installation should
not use any utilities directly except these:

awk cat cmp cp diff echo egrep expr false grep install-info
ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch tr true

----------------------------------------------------------

Sorry, I can't give you a diff against standards.texi or make-stds.texi but here
are my thoughts, and a way to word it.

I believe 'tar' should removed from that list, but allow someone to select a
variable for 'tar'. On Solaris for instance, Sun's tar can not extract all tar
files programs written with GNU tar, though it does manage most of them. (It's
not simply the fact some options just as z and j are not supported, but more
fundamental issues.

Issues with non-GNU versions of tar are common on lots of non-linux platforms
when using GNU tools.

hence it's better the user was able to write:

$ TAR=/usr/local/bin/gtar
$ export TAR

Hence I suggest a revised wording of:

--------------SUGGESTED VERSION---------------------------
The configure script and the Makefile rules for building and installation should
not use any utilities directly except these:

awk cat cmp cp diff echo egrep expr false grep install-info
ln ls mkdir mv pwd rm rmdir sed sleep sort test touch tr true

----------------------------------------------------------

Further down, the GNU coding standards say:

------------------------------------------------------
The Makefile rules for building and installation can also use compilers and
related programs, but should do so via make variables so that the user can
substitute alternatives. Here are some of the programs we mean:

ar bison cc flex install ld ldconfig lex
make makeinfo ranlib texi2dvi yacc

Use the following make variables to run those programs:

$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
----------------------------------------------------------

Given the above, I would suggest tar is added to those lists.

Hence I would suggest that the following

------------------- CURRENT VERSION ------------------------------
The Makefile rules for building and installation can also use compilers and
related programs, but should do so via make variables so that the user can
substitute alternatives. Here are some of the programs we mean:

ar bison cc flex install ld ldconfig lex
make makeinfo ranlib texi2dvi yacc

Use the following make variables to run those programs:

$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
-------------------------------------------------------------------

is changed to

------------------SUGGESTED VERSION ---------------
The Makefile rules for building and installation can also use compilers and
related programs, but should do so via make variables so that the user can
substitute alternatives. Here are some of the programs we mean:

ar bison cc flex install ld ldconfig lex
makeinfo ranlib tar texi2dvi yacc

Use the following make variables to run those programs:

$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TAR) $(TEXI2DVI) $(YACC)
-------------------------------------------------------------------

Re: error messages with ranges

2009-10-18T19:39:05Z

Is :: starting a new line? If so, I think emacs does not parse more
than one line of GCC's output at a time. Would that change with this
proposal?

Parsing either of these formats will require specialized code for sure.

At the risk of complicating the decision, another idea just occurred to me:
output a separate error message for each argument, like this:

foo.c:47:5-10: First argument of erroneous operation
foo.c:47:14-250: Second argument of erroneous operation

The IDE could recognize these two error messages
and process them specially however it wishes.

Re: error messages with ranges

2009-10-17T20:10:20Z

FWIW, clang uses ranges for a lot of things other than arguments.

We already support ranges in error messages. The issue here is to
include more than one range. These two examples need only one:

$ clang -fsyntax-only t.c
t.c:12:8: error: called object type 'int' is not a function or function pointer
(P-Q)();
~~~~~^
$ clang t.c
t.c:5:28: warning: use of GNU old-style field designator extension
struct point origin = { x: 0.0, y: 0.0 };
~~ ^
.x =

However, my proposal is not limited to indicating the arguments.
It could be used to convey multiple ranges for any purpose.

Re: error messages with ranges

2009-10-17T20:09:59Z

"Argument locations" because they need to handle translations to other
languages as well. With the specific phrase not being significant, it is
of course possible to put other phrases there if it's felt useful to
attach a natural language name to the other locations in that way.

Yes. However, we could also publish a list of the phrases that GCC
puts there, with a description of what the ranges mean. Then an IDE
could optionally recognize some of these phrases and do something
special for them.

Re: error messages with ranges

2009-10-17T03:56:12Z

2009/10/16 Richard Stallman <rms@...>:
> How about something like this:
>
> exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
> ::Argument locations: 47:8-47:14, 47:17-47:24
>
> If the brace notation you've proposed becomes a de facto standard,
> we may as well go along with it. But I think this proposal
> is better intrinsically, since it is less clutter and no harder to parse.

Is :: starting a new line? If so, I think emacs does not parse more
than one line of GCC's output at a time. Would that change with this
proposal?

Do numbers may appear in the message between :: and : ?

Cheers,

Manuel.

Re: error messages with ranges

2009-10-17T03:25:58Z

However, I would like you clarify the '::Argument locations:' marker.
Do you intend the double colons '::' as token to introduce
some form of meta data for tools? (In this case, it is to introduce
locus, but is it an escape for more general tags?)

Yes, exactly.

I don't insist on using ::. It was the first thing that occurred to me.
If someone has a better idea, let's use it.

Re: error messages with ranges

2009-10-16T14:31:21Z

On Fri, Oct 16, 2009 at 4:24 PM, Joseph S. Myers
<joseph@...> wrote:

> I was presuming that in the above the initial "::" is the signal to IDEs
> or other diagnostic parsers, meaning that "Argument locations" is to be
> taken as English text that should be translated to the user's language,
> and so IDEs should not ascribe any significance to the specific phrase
> "Argument locations" because they need to handle translations to other
> languages as well. With the specific phrase not being significant, it is
> of course possible to put other phrases there if it's felt useful to
> attach a natural language name to the other locations in that way.

Thanks, this is what I was looking for.

In that case, I think I agree with the suggestion made by RMS.

-- Gaby

Re: error messages with ranges

2009-10-16T14:24:23Z

On Fri, 16 Oct 2009, Chris Lattner wrote:

> On Oct 16, 2009, at 9:51 AM, Gabriel Dos Reis wrote:
>
> > On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
> > > How about something like this:
> > >
> > > exprs.c:47:15: error: invalid operands to binary expression ('int *' and
> > > '_Complex float')
> > > ::Argument locations: 47:8-47:14, 47:17-47:24
> > >
> > > If the brace notation you've proposed becomes a de facto standard,
> > > we may as well go along with it. But I think this proposal
> > > is better intrinsically, since it is less clutter and no harder to parse.
> >
> > I like the non-braced version.
> >
> > However, I would like you clarify the '::Argument locations:' marker.
> > Do you intend the double colons '::' as token to introduce
> > some form of meta data for tools? (In this case, it is to introduce
> > locus, but is it an escape for more general tags?)
>
> FWIW, clang uses ranges for a lot of things other than arguments.

I was presuming that in the above the initial "::" is the signal to IDEs
or other diagnostic parsers, meaning that "Argument locations" is to be
taken as English text that should be translated to the user's language,
and so IDEs should not ascribe any significance to the specific phrase
"Argument locations" because they need to handle translations to other
languages as well. With the specific phrase not being significant, it is
of course possible to put other phrases there if it's felt useful to
attach a natural language name to the other locations in that way.

--
Joseph S. Myers
joseph@...

Re: error messages with ranges

2009-10-16T13:43:53Z

On Oct 16, 2009, at 9:51 AM, Gabriel Dos Reis wrote:

> On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
>> How about something like this:
>>
>> exprs.c:47:15: error: invalid operands to binary expression
>> ('int *' and '_Complex float')
>> ::Argument locations: 47:8-47:14, 47:17-47:24
>>
>> If the brace notation you've proposed becomes a de facto standard,
>> we may as well go along with it. But I think this proposal
>> is better intrinsically, since it is less clutter and no harder to
>> parse.
>
> I like the non-braced version.
>
> However, I would like you clarify the '::Argument locations:' marker.
> Do you intend the double colons '::' as token to introduce
> some form of meta data for tools? (In this case, it is to introduce
> locus, but is it an escape for more general tags?)

FWIW, clang uses ranges for a lot of things other than arguments.

Here are some other examples:

$ clang -fsyntax-only t.c
t.c:12:8: error: called object type 'int' is not a function or
function pointer
(P-Q)();
~~~~~^
$ clang t.c
t.c:5:28: warning: use of GNU old-style field designator extension
struct point origin = { x: 0.0, y: 0.0 };
~~ ^
.x =

This is probably mangled by my email client, but you can see examples
as intended here:
http://clang.llvm.org/diagnostics.html

The brace sequence is not normally seen by humans, only by IDEs and
tools. It being terse and simple is important, but beauty is not very
important.

-Chris

Re: error messages with ranges

2009-10-16T09:51:52Z

On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
> How about something like this:
>
> exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
> ::Argument locations: 47:8-47:14, 47:17-47:24
>
> If the brace notation you've proposed becomes a de facto standard,
> we may as well go along with it. But I think this proposal
> is better intrinsically, since it is less clutter and no harder to parse.

I like the non-braced version.

However, I would like you clarify the '::Argument locations:' marker.
Do you intend the double colons '::' as token to introduce
some form of meta data for tools? (In this case, it is to introduce
locus, but is it an escape for more general tags?)

>
>

Re: error messages with ranges

2009-10-16T01:47:58Z

How about something like this:

exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
::Argument locations: 47:8-47:14, 47:17-47:24

If the brace notation you've proposed becomes a de facto standard,
we may as well go along with it. But I think this proposal
is better intrinsically, since it is less clutter and no harder to parse.

Re: error messages with ranges

2009-10-15T08:32:03Z

2009/10/15 Richard Stallman <rms@...>:

> In principle the location range information would be only internal for
> GCC. The option that enables it to be shown in the output would allow
> external programs (like emacs, IDEs, a custom wrapper, or GCC's
> regression tester) to parse the output of GCC. In fact, what such
> programs would do is to turn OFF the caret information and turn ON the
> location range information, in order to provide their own custom caret
> information.
>
> Given that plan, why not output the arg location information
> in separate lines distinguished by some special prefix?

Could you provide an example of what you have in mind? For example, to
represent this:

exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
to binary expression ('int *' and '_Complex float')

Please bear in mind that the format should be easily parsable by
machines, in order to be able to associate the ranges with the
appropriate error message, and not parse it as multiple independent
messages.

> > How exactly do people propose to use that location range information?
>
> As far as I know, at least one IDE is using it to parse the output of
> Clang and provide custom caret information in the IDE interface.
>
> Are you saying that clang already outputs the argument range information
> in this format?

Yes, it does if this is enabled usng the appropriate option.

Cheers,

Manuel.

Re: error messages with ranges

2009-10-14T21:17:44Z

In principle the location range information would be only internal for
GCC. The option that enables it to be shown in the output would allow
external programs (like emacs, IDEs, a custom wrapper, or GCC's
regression tester) to parse the output of GCC. In fact, what such
programs would do is to turn OFF the caret information and turn ON the
location range information, in order to provide their own custom caret
information.

Given that plan, why not output the arg location information
in separate lines distinguished by some special prefix?

Standardizing its format could be useful at some point,
but it need not be part of the error message standard.

> How exactly do people propose to use that location range information?

As far as I know, at least one IDE is using it to parse the output of
Clang and provide custom caret information in the IDE interface.

Are you saying that clang already outputs the argument range information
in this format?

Re: error messages with ranges

2009-10-14T03:47:54Z

2009/10/14 Richard Stallman <rms@...>:
> The goal here is to work towards supporting caret information in GCC
>
> What is "caret information"?

I would say that it is the ability to print, in diagnostic messages,
parts of the original source code indicating exactly which parts of
the source code the diagnostic is referring to.

>
> exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
> to binary expression ('int *' and '_Complex float')
> P = (P-42) + Gamma*4;
> ~~~~~~ ^ ~~~~~~~
>
> Is that what "caret information" means?

The line of code with the '~~' and '^' below is the caret information.
The {47:8-47:14}{47:17-47:24} would be the "location range" information.

>
> I can see how this
>
> P = (P-42) + Gamma*4;
> ~~~~~~ ^ ~~~~~~~
>
> is useful for humans, and making GCC output that information
> seems like a good feature. But why is it useful to include
> the location range information for the operands?

In principle the location range information would be only internal for
GCC. The option that enables it to be shown in the output would allow
external programs (like emacs, IDEs, a custom wrapper, or GCC's
regression tester) to parse the output of GCC. In fact, what such
programs would do is to turn OFF the caret information and turn ON the
location range information, in order to provide their own custom caret
information.

I really do not know if this format actually needs documenting in
Coding Standards, since it is not really meant for humans. I can also
update the patch to mention that this format is to be parsed by
machines, and it should not be used for output meant to be read by
humans (unless requested).

> How exactly do people propose to use that location range information?

As far as I know, at least one IDE is using it to parse the output of
Clang and provide custom caret information in the IDE interface.

Cheers,

Manuel.

Re: error messages with ranges

2009-10-13T17:43:58Z

The goal here is to work towards supporting caret information in GCC

What is "caret information"?

exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
to binary expression ('int *' and '_Complex float')
P = (P-42) + Gamma*4;
~~~~~~ ^ ~~~~~~~

Is that what "caret information" means?

I can see how this

P = (P-42) + Gamma*4;
~~~~~~ ^ ~~~~~~~

is useful for humans, and making GCC output that information
seems like a good feature. But why is it useful to include
the location range information for the operands?

How exactly do people propose to use that location range information?

Re: error messages with ranges

2009-10-13T04:09:47Z

> Date: Sun, 11 Oct 2009 23:44:45 -0400
> From: Richard Stallman <rms@...>
> To: karl@... (Karl Berry)
> Subject: Re: [lopezibanez@...: error messages with ranges]
>
> I think this is not a good idea.
> Putting multiple locations in one error message is not helpful
> and makes it harder to read.
> There are situations where GCC needs to mention two different
> places in the source -- for instance, two conflicting declarations
> for one symbol. It does this by issuing two error messages, one
> with each location. The text states how they are related.

This is a different situation that is orthogonal to mentioning two
different places.

First, this option will be default to off. Second, this information
will be primarily parsed by programs not humans.

The goal here is to work towards supporting caret information in GCC
(as Clang and other compilers currently support and use as a major
selling point).

An example from Clang's webpage [1]:

$ gcc-4.2 -fsyntax-only t.c
t.c:7: error: invalid operands to binary + (have 'int' and 'struct A')
$ clang -fsyntax-only t.c
t.c:7:39: error: invalid operands to binary expression ('int' and 'struct A')
return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);
~~~~~~~~~~~~~~ ^ ~~~~~

The caret '^' and the ranges shown by ~~~~~ are generated the
compiler (clang in this case). A fist step towards implementing this
is to have an option that prints range information in the location
line. This allows programs to parse gcc output and generate a wrapper
around gcc that provides caret diagnostics. This is already done by at
least one IDE to provide caret diagnostics using Clang. This also
allows developers to debug the range information in case the ranges
are not printed where they are expected.

In short, the goal is to implement in GCC, this option from Clang:

-f[no-]diagnostics-print-source-range-info: Print machine parsable
information about source ranges.
This option, which defaults to off, controls whether or not Clang
prints information about source ranges in a machine parsable format
after the file/line/column number information. The information is a
simple sequence of brace enclosed ranges, where each range lists the
start and end line/column locations. For example, in this output:

exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
to binary expression ('int *' and '_Complex float')
P = (P-42) + Gamma*4;
~~~~~~ ^ ~~~~~~~

The {}'s are generated by -fdiagnostics-print-source-range-info.

I can certainly update the patch to mention that this format should be
avoided for output that is meant to be read mainly by humans, and in
such case a single location or multiple errors are preferred.

Cheers,

Manuel.

[1] http://clang.llvm.org/diagnostics.html
[2] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics

Re: error messages with ranges

2009-10-12T16:14:00Z

Hi Manuel,

This is a patch to standards.texi to specify error messages with
multiple ranges.

Here is rms's response:

Date: Sun, 11 Oct 2009 23:44:45 -0400
From: Richard Stallman <rms@...>
To: karl@... (Karl Berry)
Subject: Re: [lopezibanez@...: error messages with ranges]

I think this is not a good idea.
Putting multiple locations in one error message is not helpful
and makes it harder to read.

There are situations where GCC needs to mention two different
places in the source -- for instance, two conflicting declarations
for one symbol. It does this by issuing two error messages, one
with each location. The text states how they are related.

In practice this is perfectly clear and convenient. Putting them in a
single error message would make it harder to read.

Please ask the Clang and GCC developers to state the practical
advantages they see in this new format.

You might as well send your replies directly to him. I don't need to be
in this loop (and I'll be offline the rest of this week).

Re: error messages with ranges

2009-10-11T15:26:55Z

This is a patch to standards.texi to specify error messages with
multiple ranges.

Thanks, fine by me. I have forwarded it to rms for approval.

error messages with ranges

2009-10-11T05:48:48Z

Hi,

This is a patch to standards.texi to specify error messages with
multiple ranges. Currently, Clang implements this [1] and GCC would
like to implement it too [2].

Cheers,

Manuel.

[1] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics (option
-f[no-]diagnostics-print-source-range-info)

[2] http://gcc.gnu.org/ml/gcc-patches/2009-08/msg00201.html

2009-10-10 Manuel López-Ibáñez <manu@...>

* standard.texi (Error Messages): Describe error ranges.

[ranges.patch]

diff -Naurp standards-orig/standards.texi standards/standards.texi --- standards-orig/standards.texi 2009-04-17 00:46:07.000000000 +0200 +++ standards/standards.texi 2009-10-10 13:35:31.000000000 +0200 @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate April 16, 2009 +@set lastupdate October 10, 2009 @c %**end of header @dircategory GNU organization @@ -760,6 +760,16 @@ When an error is spread over several fil @var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message} @end example +@noindent +When an error message mentions several ranges of positions within one +file, you can specify each range within braces. For example, the +following specifies one error position and two ranges within the same +file: + +@example +@var{file-1}:@var{lineno-1}:@var{column-1}:@{@var{lineno-2}:@var{column-2}-@var{lineno-3}:@var{column-3}@}@{@var{lineno-4}:@var{column-4}-@var{lineno-5}:@var{column-5}@}: @var{message} +@end example + Error messages from other noninteractive programs should look like this: @example

error messages with ranges

2009-10-10T04:43:19Z

Hi,

This is a patch to standards.texi to specify error messages with
multiple ranges. Currently, Clang implements this [1] and GCC would
like to implement it too [2].

[1] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics (option
-f[no-]diagnostics-print-source-range-info)

[2] http://gcc.gnu.org/ml/gcc-patches/2009-08/msg00201.html

2009-10-10 Manuel López-Ibáñez <manu@...>

* standard.texi (Error Messages): Describe error ranges.

Cheers,

Manuel.

[ranges.patch]

Re: $(datarootdir) should be $(datadir)

2009-07-04T01:23:57Z

Hello,

* Karl Berry wrote on Fri, Jul 03, 2009 at 11:56:42PM CEST:
> In section 7.2.5, when the 'datadir' directory is discussed, this
> sentence appears:
>
> "This should normally be /usr/local/share, but write it as
> $(datarootdir). (If you are using Autoconf, write it as '@datadir@')"
>
> $(datarootdir) should be $(datadir), given the section it's in.
>
> Thanks for the report. I think you are right,

No, I don't think he is right. Going through the other descriptions:
bindir should be written as $(exec_prefix)/bin,
datarootdir as $(prefix)/share,
datadir as $(datarootdir),

which is at least consistent.

Cheers,
Ralf

Re: $(datarootdir) should be $(datadir)

2009-07-03T14:56:42Z

In section 7.2.5, when the 'datadir' directory is discussed, this
sentence appears:

"This should normally be /usr/local/share, but write it as
$(datarootdir). (If you are using Autoconf, write it as '@datadir@')"

$(datarootdir) should be $(datadir), given the section it's in.

Thanks for the report. I think you are right, although given the
always-confusing situation datadir and datarootdir, I can't say I'm 100%
sure. Can anyone else here confirm/deny?

I'll think about it and either make the change or insert an explanation.

Best,
Karl

$(datarootdir) should be $(datadir)

2009-07-03T08:17:00Z

Re: COPYING.LIB vs COPYING.LESSER

2009-04-16T15:54:44Z

Standards states in section 7.3 that it should be in a file called
COPYING.LIB. Suggest changing this to COPYING.LESSER

Right. Fixed. Thanks for the patch :).

karl

COPYING.LIB vs COPYING.LESSER

2009-04-15T13:57:53Z

The GPL Howto and the maintain manual both suggest use of COPYING.LESSER
in a project for software licensed under the LGPL, while the GNU Coding
Standards states in section 7.3 that it should be in a file called
COPYING.LIB. Suggest changing this to COPYING.LESSER in line with the
other documents and to reflect the name change from GNU Library GPL to
GNU Lesser GPL. (Very small ☺) patch attached.

Simon Ward
--
A complex system that works is invariably found to have evolved from a
simple system that works.—John Gall

Index: standards.texi =================================================================== RCS file: /sources/gnustandards/gnustandards/standards.texi,v retrieving revision 1.185 diff -u -r1.185 standards.texi --- standards.texi 14 Feb 2009 15:23:01 -0000 1.185 +++ standards.texi 15 Apr 2009 20:50:17 -0000 @@ -4041,7 +4041,7 @@ The @file{README} file should also refer to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called @file{COPYING}. If the GNU LGPL is used, it should be in a file called -@file{COPYING.LIB}. +@file{COPYING.LESSER}. Naturally, all the source files must be in the distribution. It is okay to include non-source files in the distribution, provided they are

signature.asc (204 bytes) Download Attachment

A complex system that works is invariably found to have evolved from a simple system that works.—John Gall