* [DOC Patch] symbol rename pragmas
@ 2014-05-12 21:46 David Wohlferd
2014-05-12 22:38 ` Gerald Pfeifer
2014-05-13 5:57 ` Rainer Orth
0 siblings, 2 replies; 8+ messages in thread
From: David Wohlferd @ 2014-05-12 21:46 UTC (permalink / raw)
To: gcc-patches; +Cc: Gerald Pfeifer
[-- Attachment #1: Type: text/plain, Size: 893 bytes --]
I don't have permissions to commit this patch, but I do have a release
on file with the FSF.
Problem description:
The existing docs make reference to the "two #pragma directives that
change the name used in assembly." However, the subsequent text only
describes one. It turns out, "#pragma extern_prefix" was removed in
revision 185240 (March 2012), as part of "Remove obsolete Tru64 UNIX
V5.1B support," but the surrounding text wasn't updated to reflect the
new count. Also, while the current text makes reference to
"compatibility with the Solaris system headers," the remaining pragma is
(according to the existing text) "currently on all platforms." This
makes referring to Solaris both superfluous and potentially confusing.
ChangeLog:
2014-05-12 David Wohlferd <dw@LimeGreenSocks.com>
* doc/extend.texi: Reflect current pragma count and remove
"Solaris."
dw
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 1906 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 210298)
+++ extend.texi (working copy)
@@ -16885,11 +16885,9 @@
@node Symbol-Renaming Pragmas
@subsection Symbol-Renaming Pragmas
-For compatibility with the Solaris system headers, GCC
-supports two @code{#pragma} directives that change the name used in
-assembly for a given declaration. To get this effect
-on all platforms supported by GCC, use the asm labels extension (@pxref{Asm
-Labels}).
+GCC supports a @code{#pragma} directive that changes the name used in
+assembly for a given declaration. This effect can also be achieved
+using the asm labels extension (@pxref{Asm Labels}).
@table @code
@item redefine_extname @var{oldname} @var{newname}
@@ -16901,17 +16899,17 @@
@end table
This pragma and the asm labels extension interact in a complicated
-manner. Here are some corner cases you may want to be aware of.
+manner. Here are some corner cases you may want to be aware of:
@enumerate
-@item Both pragmas silently apply only to declarations with external
+@item This pragma silently applies only to declarations with external
linkage. Asm labels do not have this restriction.
-@item In C++, both pragmas silently apply only to declarations with
+@item In C++, this pragma silently applies only to declarations with
``C'' linkage. Again, asm labels do not have this restriction.
-@item If any of the three ways of changing the assembly name of a
-declaration is applied to a declaration whose assembly name has
+@item If either of the ways of changing the assembly name of a
+declaration are applied to a declaration whose assembly name has
already been determined (either by a previous use of one of these
features, or because the compiler needed the assembly name in order to
generate code), and the new name is different, a warning issues and
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-12 21:46 [DOC Patch] symbol rename pragmas David Wohlferd
@ 2014-05-12 22:38 ` Gerald Pfeifer
2014-05-13 5:57 ` Rainer Orth
1 sibling, 0 replies; 8+ messages in thread
From: Gerald Pfeifer @ 2014-05-12 22:38 UTC (permalink / raw)
To: David Wohlferd; +Cc: gcc-patches
On Mon, 12 May 2014, David Wohlferd wrote:
> 2014-05-12 David Wohlferd <dw@LimeGreenSocks.com>
>
> * doc/extend.texi: Reflect current pragma count and remove "Solaris."
Thanks, I applied the patch with two changes to the ChangeLog:
1. Two spaces between name and e-mail address per GNU Coding Standard.
2. I rewrote the actual ChangeLog to
* doc/extend.texi: Reflect current numbers of pragmas. Remove
reference to Solaris.
(introducing a typo, "numbers" instead of "number" as I just realize.)
Gerald
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-12 21:46 [DOC Patch] symbol rename pragmas David Wohlferd
2014-05-12 22:38 ` Gerald Pfeifer
@ 2014-05-13 5:57 ` Rainer Orth
2014-05-13 11:16 ` David Wohlferd
1 sibling, 1 reply; 8+ messages in thread
From: Rainer Orth @ 2014-05-13 5:57 UTC (permalink / raw)
To: David Wohlferd; +Cc: gcc-patches, Gerald Pfeifer
David Wohlferd <dw@LimeGreenSocks.com> writes:
> I don't have permissions to commit this patch, but I do have a release on
> file with the FSF.
>
> Problem description:
> The existing docs make reference to the "two #pragma directives that change
> the name used in assembly." However, the subsequent text only describes
> one. It turns out, "#pragma extern_prefix" was removed in revision 185240
> (March 2012), as part of "Remove obsolete Tru64 UNIX V5.1B support," but
> the surrounding text wasn't updated to reflect the new count. Also, while
That's my fault, sorry.
> the current text makes reference to "compatibility with the Solaris system
> headers," the remaining pragma is (according to the existing text)
> "currently on all platforms." This makes referring to Solaris both
> superfluous and potentially confusing.
I disagree: #pragma redefine_extname does exist for Solaris
compatibility only, even if it now works on all platforms. So please
continue to state so.
> ChangeLog:
> 2014-05-12 David Wohlferd <dw@LimeGreenSocks.com>
>
> * doc/extend.texi: Reflect current pragma count and remove
> "Solaris."
The ChangeLog entry should be formatted like this:
* doc/extend.texi (Symbol-Renaming Pragmas): Refect ...
This is what Emacs' Change Log mode does for you, otherwise it's hard to
see what section your change refers to.
Thanks.
Rainer
--
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-13 5:57 ` Rainer Orth
@ 2014-05-13 11:16 ` David Wohlferd
2014-05-13 11:37 ` Rainer Orth
0 siblings, 1 reply; 8+ messages in thread
From: David Wohlferd @ 2014-05-13 11:16 UTC (permalink / raw)
To: Rainer Orth; +Cc: gcc-patches, Gerald Pfeifer
[-- Attachment #1: Type: text/plain, Size: 2619 bytes --]
Thank you for taking the time to review this.
>> the current text makes reference to "compatibility with the Solaris system
>> headers," the remaining pragma is (according to the existing text)
>> "currently on all platforms." This makes referring to Solaris both
>> superfluous and potentially confusing.
> I disagree: #pragma redefine_extname does exist for Solaris
> compatibility only, even if it now works on all platforms. So please
> continue to state so.
Hmm. Looking at the original text:
"For compatibility with the Solaris system headers, GCC supports two
#pragma directives that change the name used in assembly for a given
declaration."
As I read that, I only saw the motivation for why this pragma was
added. Even now I don't read this as *restricting* these pragmas to
Solaris. Especially when you combine that with:
- The text below which states that redefine_extname is "currently on all
platforms."
- This pragma isn't under the "Solaris Pragmas" headings, but under its
own (apparently platform-neutral) heading.
- It does in fact work on other platforms. Even the
__PRAGMA_REDEFINE_EXTNAME macro is there.
Considering all these points, someone could easily conclude this was not
Solaris-specific. While that may not have been the intent when this
text was written, that's how I read it, and others may have too. Are
you sure you want me to make this change?
I'm not trying to pick a fight here. I'm not using the pragma, so this
doesn't affect me. It's just that this has been out there for a long
time, affects platforms other than Solaris, and I'm not immediately
clear on what problems supporting other platforms creates.||
In the end I guess I'd just like to be sure some other OS Port
Maintainer (or some distraught user) isn't going to be emailing me
demanding to know why "I" dropped support for this from their platform.
That said.
If this does need to change, I'd recommend something like the attached.
Note that since the previous patch was checked in, this patch updates
from that point. It deletes the "Symbol-Renaming Pragmas" node, and
moves (most of) the redefine_extname text into the "Solaris Pragmas" node.
If reading the patch doesn't make it clear what I've done, you can see
the end result here: http://www.LimeGreenSocks.com/gcc/Solaris-Pragmas.html
I believe this makes it crystal clear that the only platform where gcc
supports this pragma is Solaris. If you approve (and I don't hear from
some other Port Maintainer or distraught user), I'll submit this as a
new patch. Be aware, I plan to put your name in the changelog.
dw
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 1864 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 210355)
+++ extend.texi (working copy)
@@ -16657,7 +16657,6 @@
* RS/6000 and PowerPC Pragmas::
* Darwin Pragmas::
* Solaris Pragmas::
-* Symbol-Renaming Pragmas::
* Structure-Packing Pragmas::
* Weak Pragmas::
* Diagnostic Pragmas::
@@ -16851,8 +16850,7 @@
@node Solaris Pragmas
@subsection Solaris Pragmas
-The Solaris target supports @code{#pragma redefine_extname}
-(@pxref{Symbol-Renaming Pragmas}). It also supports additional
+The Solaris target supports additional
@code{#pragma} directives for compatibility with the system compiler.
@table @code
@@ -16880,23 +16878,13 @@
initialization (before @code{main}) or during shared module loading, by
adding a call to the @code{.init} section.
-@end table
-
-@node Symbol-Renaming Pragmas
-@subsection Symbol-Renaming Pragmas
-
-GCC supports a @code{#pragma} directive that changes the name used in
-assembly for a given declaration. This effect can also be achieved
-using the asm labels extension (@pxref{Asm Labels}).
-
-@table @code
@item redefine_extname @var{oldname} @var{newname}
@cindex pragma, redefine_extname
This pragma gives the C function @var{oldname} the assembly symbol
@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
-is defined if this pragma is available (currently on all platforms).
-@end table
+is defined if this pragma is available. This effect can also be achieved
+using the asm labels extension (@pxref{Asm Labels}).
This pragma and the asm labels extension interact in a complicated
manner. Here are some corner cases you may want to be aware of:
@@ -16919,6 +16907,8 @@
always the C-language name.
@end enumerate
+@end table
+
@node Structure-Packing Pragmas
@subsection Structure-Packing Pragmas
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-13 11:16 ` David Wohlferd
@ 2014-05-13 11:37 ` Rainer Orth
2014-05-13 17:41 ` Joseph S. Myers
2014-05-13 22:37 ` David Wohlferd
0 siblings, 2 replies; 8+ messages in thread
From: Rainer Orth @ 2014-05-13 11:37 UTC (permalink / raw)
To: David Wohlferd; +Cc: gcc-patches, Gerald Pfeifer
Hi David,
> Thank you for taking the time to review this.
>
>>> the current text makes reference to "compatibility with the Solaris system
>>> headers," the remaining pragma is (according to the existing text)
>>> "currently on all platforms." This makes referring to Solaris both
>>> superfluous and potentially confusing.
>> I disagree: #pragma redefine_extname does exist for Solaris
>> compatibility only, even if it now works on all platforms. So please
>> continue to state so.
>
> Hmm. Looking at the original text:
>
> "For compatibility with the Solaris system headers, GCC supports two
> #pragma directives that change the name used in assembly for a given
> declaration."
>
> As I read that, I only saw the motivation for why this pragma was added.
right, and that's why I want to keep this info. If it weren't for
Solaris compatibility, this pragma wouldn't exist, and given that
heritage, I don't want to encourage its use elsewhere, even though it
does work.
> Even now I don't read this as *restricting* these pragmas to Solaris.
> Especially when you combine that with:
>
> - The text below which states that redefine_extname is "currently on all
> platforms."
> - This pragma isn't under the "Solaris Pragmas" headings, but under its own
> (apparently platform-neutral) heading.
> - It does in fact work on other platforms. Even the
> __PRAGMA_REDEFINE_EXTNAME macro is there.
I've never claimed otherwise.
> Considering all these points, someone could easily conclude this was not
> Solaris-specific. While that may not have been the intent when this text
> was written, that's how I read it, and others may have too. Are you sure
> you want me to make this change?
I am, for the reasons stated above.
> I'm not trying to pick a fight here. I'm not using the pragma, so this
> doesn't affect me. It's just that this has been out there for a long time,
> affects platforms other than Solaris, and I'm not immediately clear on what
> problems supporting other platforms creates.||
>
> In the end I guess I'd just like to be sure some other OS Port Maintainer
> (or some distraught user) isn't going to be emailing me demanding to know
> why "I" dropped support for this from their platform.
>
> That said.
>
> If this does need to change, I'd recommend something like the attached.
> Note that since the previous patch was checked in, this patch updates from
> that point. It deletes the "Symbol-Renaming Pragmas" node, and moves (most
> of) the redefine_extname text into the "Solaris Pragmas" node.
>
> If reading the patch doesn't make it clear what I've done, you can see the
> end result here: http://www.LimeGreenSocks.com/gcc/Solaris-Pragmas.html
>
> I believe this makes it crystal clear that the only platform where gcc
> supports this pragma is Solaris. If you approve (and I don't hear from
> some other Port Maintainer or distraught user), I'll submit this as a new
> patch. Be aware, I plan to put your name in the changelog.
You misunderstood completely: I'm not at all demanding to remove support
for that pragma in the cross-platform part of the docs or even in the
code, just ask to keep documenting the heritage so it's clear why it
exists and when to use it (or not).
Just restoring the first sentence you deleted describing the heritage
should be enough to do so.
Rainer
--
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-13 11:37 ` Rainer Orth
@ 2014-05-13 17:41 ` Joseph S. Myers
2014-05-13 22:37 ` David Wohlferd
1 sibling, 0 replies; 8+ messages in thread
From: Joseph S. Myers @ 2014-05-13 17:41 UTC (permalink / raw)
To: Rainer Orth; +Cc: David Wohlferd, gcc-patches, Gerald Pfeifer
On Tue, 13 May 2014, Rainer Orth wrote:
> right, and that's why I want to keep this info. If it weren't for
> Solaris compatibility, this pragma wouldn't exist, and given that
> heritage, I don't want to encourage its use elsewhere, even though it
> does work.
I can see definite cases where it could be useful in glibc headers, to
redirect functions to the appropriate version for a particular standard in
the implicitly preincluded stdc-predef.h even if the header declaring the
function in question isn't included (ISO C and POSIX allow you to declare
standard functions yourself if the standard prototype for the function
doesn't involve any type defined in a header). So, I think it's quite
right for it to be available on all platforms as a feature that can help
in implementing certain standard requirements.
--
Joseph S. Myers
joseph@codesourcery.com
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-13 11:37 ` Rainer Orth
2014-05-13 17:41 ` Joseph S. Myers
@ 2014-05-13 22:37 ` David Wohlferd
2014-05-17 1:24 ` David Wohlferd
1 sibling, 1 reply; 8+ messages in thread
From: David Wohlferd @ 2014-05-13 22:37 UTC (permalink / raw)
To: Rainer Orth; +Cc: gcc-patches, Gerald Pfeifer
> You misunderstood completely: I'm not at all demanding to remove support
> for that pragma in the cross-platform part of the docs or even in the
> code,
Whew! Ok, that's good. Sorry I went all crazy on you. When I thought
that *was* what you were asking for, I wanted to try to talk you out of it.
> just ask to keep documenting the heritage so it's clear why it
> exists and when to use it (or not).
Ok, I get this. I've written text that "discouraged" using things in
the past, even though technically they work just fine.
> Just restoring the first sentence you deleted describing the heritage
> should be enough to do so.
Speaking for myself, I didn't see the old text as favoring one course of
action over another. How would you feel about:
GCC supports a @code{#pragma} directive that changes the name used in
assembly for a given declaration. While this pragma is supported on all
platforms, it is intended primarily to provide compatibility with the
Solaris system headers. This effect can also be achieved using the asm
labels extension (@pxref{Asm Labels}).
To me, this subtly discourages using the pragma other than for Solaris,
maintains the heritage, and immediately provides a viable alternative
for other platforms.
dw
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [DOC Patch] symbol rename pragmas
2014-05-13 22:37 ` David Wohlferd
@ 2014-05-17 1:24 ` David Wohlferd
0 siblings, 0 replies; 8+ messages in thread
From: David Wohlferd @ 2014-05-17 1:24 UTC (permalink / raw)
To: Rainer Orth; +Cc: gcc-patches, Gerald Pfeifer, Joseph Myers
[-- Attachment #1: Type: text/plain, Size: 1387 bytes --]
This patch is in response to Rainer Orth's comment (below).
I have a release on file with the FSF, but don't have SVN write access.
Problem description:
The (already committed) patch at the top of this thread removed a
reference to Solaris. It has been requested that this be restored to
show the origins of the directive and clarify "when to use it (or not)."
ChangeLog:
2014-05-16 David Wohlferd <dw@LimeGreenSocks.com>
* doc/extend.texi (Symbol-Renaming Pragmas): Restore (slightly
modified) reference to Solaris.
dw
>> keep documenting the heritage so it's clear why it
>> exists and when to use it (or not).
>>
>> Just restoring the first sentence you deleted describing the heritage
>> should be enough to do so.
>
> Speaking for myself, I didn't see the old text as favoring one course
> of action over another. How would you feel about:
>
> GCC supports a @code{#pragma} directive that changes the name used in
> assembly for a given declaration. While this pragma is supported on all
> platforms, it is intended primarily to provide compatibility with the
> Solaris system headers. This effect can also be achieved using the asm
> labels extension (@pxref{Asm Labels}).
>
> To me, this subtly discourages using the pragma other than for
> Solaris, maintains the heritage, and immediately provides a viable
> alternative for other platforms.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: extend.texi.patch --]
[-- Type: text/x-patch; name="extend.texi.patch", Size: 738 bytes --]
Index: extend.texi
===================================================================
--- extend.texi (revision 210542)
+++ extend.texi (working copy)
@@ -16895,8 +16895,10 @@
@subsection Symbol-Renaming Pragmas
GCC supports a @code{#pragma} directive that changes the name used in
-assembly for a given declaration. This effect can also be achieved
-using the asm labels extension (@pxref{Asm Labels}).
+assembly for a given declaration. While this pragma is supported on all
+platforms, it is intended primarily to provide compatibility with the
+Solaris system headers. This effect can also be achieved using the asm
+labels extension (@pxref{Asm Labels}).
@table @code
@item redefine_extname @var{oldname} @var{newname}
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2014-05-17 1:24 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-05-12 21:46 [DOC Patch] symbol rename pragmas David Wohlferd
2014-05-12 22:38 ` Gerald Pfeifer
2014-05-13 5:57 ` Rainer Orth
2014-05-13 11:16 ` David Wohlferd
2014-05-13 11:37 ` Rainer Orth
2014-05-13 17:41 ` Joseph S. Myers
2014-05-13 22:37 ` David Wohlferd
2014-05-17 1:24 ` David Wohlferd
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).