[Bug driver/37786] New: Documentation for `-symbolic' needs fixing

[Bug driver/37786] New: Documentation for `-symbolic' needs fixing

[martinrb at google dot com]

gcc has flags -Bsymbolic and -Bsymbolic-functions
which are documented in the usage message.

 $ gcc -v --help 2>&1 | grep symbolic
  -Bsymbolic                  Bind global references locally
  -Bsymbolic-functions        Bind global function references locally

However, the info pages are incorrect and incomplete.

`-symbolic'
     Bind references to global symbols when building a shared object.
     Warn about any unresolved references (unless overridden by the
     link editor option `-Xlinker -z -Xlinker defs').  Only a few
     systems support this option.

In fact, gcc does not appear to support any such flag `-symbolic'.
`-symbolic' should probably be changed to `-Bsymbolic'.

Also, please add info documentation for `-Bsymbolic-functions'.

A motivating example for these options would be nice as well.
(or maybe a link to any corresponding binutils documentation)


-- 
           Summary: Documentation for `-symbolic' needs fixing
           Product: gcc
           Version: 4.2.3
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: driver
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: martinrb at google dot com
GCC target triplet: x86_64-linux-gnu


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[pinskia at gcc dot gnu dot org]

------- Comment #1 from pinskia at gcc dot gnu dot org  2008-10-09 18:57 -------
The -Bsymbolic* options are linker options so they don't get documented in
GCC's documentation at all.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[pinskia at gcc dot gnu dot org]

------- Comment #2 from pinskia at gcc dot gnu dot org  2008-10-09 19:00 -------
"Only a few      systems support this option."

x86-linux-gnu is one of those targets that don't support this option :).

There is no changes needed here for the documentation as far as I can tell so
closing as invalid.


-- 

pinskia at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
         Resolution|                            |INVALID


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[martinrb at google dot com]

------- Comment #3 from martinrb at google dot com  2008-10-09 19:26 -------
(In reply to comment #2)
> "Only a few      systems support this option."
> 
> x86-linux-gnu is one of those targets that don't support this option :).
> 
> There is no changes needed here for the documentation as far as I can tell so
> closing as invalid.

Dear bugmeister,

At the very least the documentation could be made less confusing.
The documentation for GNU ld gives:

`-Bsymbolic'
     When creating a shared library, bind references to global symbols
     to the definition within the shared library, if any.  Normally, it
     is possible for a program linked against a shared library to
     override the definition within the shared library.  This option is
     only meaningful on ELF platforms which support shared libraries.

The wording is sufficiently similar that one might think
`-symbolic' and `-Bsymbolic' have the same meaning.
Yet on x86-linux-gnu, the first fails, while the second appears to succeed.

$ gcc -symbolic main.c; echo --; gcc -Bsymbolic main.c
gcc: unrecognized option '-symbolic'
--

Also, gcc has a documented `-B' flag with a completely different meaning.

All in all, I think there is at least scope for improved clarity
in the documentation.  I've used gcc for decades, but am still confused.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[pinskia at gcc dot gnu dot org]

------- Comment #4 from pinskia at gcc dot gnu dot org  2008-10-09 20:34 -------
If you want to use a specific linker option, use -Wl,XYZ or -Xlinker XYZ . 
Since those are the documented way to pass a linker option via gcc.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[martinrb at google dot com]

------- Comment #5 from martinrb at google dot com  2008-10-09 23:10 -------
(In reply to comment #4)
> If you want to use a specific linker option, use -Wl,XYZ or -Xlinker XYZ . 
> Since those are the documented way to pass a linker option via gcc.

I know about -Wl, and -Xlinker.

I am trying to reduce confusion,
for myself in part, but mostly for others.

The flag `-Bsymbolic' works (or at least is accepted)
despite the fact that it is not documented that such a
flag is passed to the linker.  This appears to be an
undocumented use of `-B'.  And on the other hand,
the documented flag `-symbolic', which appears to
have the same meaning, is rejected.

Does this not seem disturbingly confusing?


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[pinskia at gcc dot gnu dot org]

------- Comment #6 from pinskia at gcc dot gnu dot org  2008-10-09 23:15 -------
-B is documented on
http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Directory-Options.html:

-Bprefix
This option specifies where to find the executables, libraries, include files,
and data files of the compiler itself.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786

[Bug driver/37786] Documentation for `-symbolic' needs fixing

[martinrb at google dot com]

------- Comment #7 from martinrb at google dot com  2008-10-09 23:16 -------
> The flag `-Bsymbolic' works (or at least is accepted)
> despite the fact that it is not documented that such a
> flag is passed to the linker. 

Ooooops.....

Please ignore my previous msg.  
I have misunderstood for years that
`-Bsymbolic' is passed directly to the linker.
Now I understand you need to do -Wl,-Bsymbolic


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37786