diff mbox

[doc] Move -pthread documentation to linker options

Message ID 584DA72F.6090800@codesourcery.com
State New
Headers show

Commit Message

Sandra Loosemore Dec. 11, 2016, 7:21 p.m. UTC
PR 16519 notes that -pthread has only ever been documented as an RS6000 
and Solaris 2 option.  In fact it's supported by most/all(?) 
POSIX-flavored targets, including GNU/Linux, BSD variants, Darwin, etc. 
  It's probably best to document it as a generic option, with the 
expectation that GCC supports -pthread if the underlying operating 
system or C library provides an implementation of the POSIX threads API.

After scratching my head about it, it seemed that it's best categorized 
as a linker option even though it also affects the preprocessor on some 
targets.  I'll wait a day or two before committing the attached patch, 
in case anybody wants to argue that this is the wrong way to categorize it.

-Sandra

Comments

Rainer Orth Dec. 11, 2016, 8:28 p.m. UTC | #1
Hi Sandra,

> PR 16519 notes that -pthread has only ever been documented as an RS6000 and

> Solaris 2 option.  In fact it's supported by most/all(?) POSIX-flavored

> targets, including GNU/Linux, BSD variants, Darwin, etc. It's probably best

> to document it as a generic option, with the expectation that GCC supports

> -pthread if the underlying operating system or C library provides an

> implementation of the POSIX threads API.

>

> After scratching my head about it, it seemed that it's best categorized as

> a linker option even though it also affects the preprocessor on some

> targets.  I'll wait a day or two before committing the attached patch, in

> case anybody wants to argue that this is the wrong way to categorize it.


I don't like categorizing it as a linker option: as you say, it affects
the preprocessor as well (adding -D_REENTRANT on most systems), and in
the past (not completely sure about the present) there were subtle bugs
if you forgot to add -pthread during compilation.

	Rainer

-- 
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
Sandra Loosemore Dec. 11, 2016, 9:19 p.m. UTC | #2
On 12/11/2016 01:28 PM, Rainer Orth wrote:
> Hi Sandra,

>

>> PR 16519 notes that -pthread has only ever been documented as an RS6000 and

>> Solaris 2 option.  In fact it's supported by most/all(?) POSIX-flavored

>> targets, including GNU/Linux, BSD variants, Darwin, etc. It's probably best

>> to document it as a generic option, with the expectation that GCC supports

>> -pthread if the underlying operating system or C library provides an

>> implementation of the POSIX threads API.

>>

>> After scratching my head about it, it seemed that it's best categorized as

>> a linker option even though it also affects the preprocessor on some

>> targets.  I'll wait a day or two before committing the attached patch, in

>> case anybody wants to argue that this is the wrong way to categorize it.

>

> I don't like categorizing it as a linker option: as you say, it affects

> the preprocessor as well (adding -D_REENTRANT on most systems), and in

> the past (not completely sure about the present) there were subtle bugs

> if you forgot to add -pthread during compilation.


Do you have a suggestion for a better place to put it?  Preferably *one* 
place, instead of duplicating the docs in 10+ places with 
target-specific options?

-Sandra
Rainer Orth Dec. 13, 2016, 11:19 a.m. UTC | #3
Hi Sandra,

> On 12/11/2016 01:28 PM, Rainer Orth wrote:

>> Hi Sandra,

>>

>>> PR 16519 notes that -pthread has only ever been documented as an RS6000 and

>>> Solaris 2 option.  In fact it's supported by most/all(?) POSIX-flavored

>>> targets, including GNU/Linux, BSD variants, Darwin, etc. It's probably best

>>> to document it as a generic option, with the expectation that GCC supports

>>> -pthread if the underlying operating system or C library provides an

>>> implementation of the POSIX threads API.

>>>

>>> After scratching my head about it, it seemed that it's best categorized as

>>> a linker option even though it also affects the preprocessor on some

>>> targets.  I'll wait a day or two before committing the attached patch, in

>>> case anybody wants to argue that this is the wrong way to categorize it.

>>

>> I don't like categorizing it as a linker option: as you say, it affects

>> the preprocessor as well (adding -D_REENTRANT on most systems), and in

>> the past (not completely sure about the present) there were subtle bugs

>> if you forgot to add -pthread during compilation.

>

> Do you have a suggestion for a better place to put it?  Preferably *one*

> place, instead of duplicating the docs in 10+ places with target-specific

> options?


I just checked and couldn't find a really good place.  It has some
similarity to C Language Options, but doesn't fit since it doesn't
extend the language.  Unless you want to introduce a whole new section,
I think the best you can do is list it separately under Preprocessor and
Link Options.  I fully agree to not list it individually for each system
that currently supports it.  The better route would be to support it for
both compilation and linking on any system that needs either for
symmetry's sake, even if one of the two is just a no-op.  Everything
else is just a nightmarish user experience.

	Rainer

-- 
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
diff mbox

Patch

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 243520)
+++ gcc/doc/invoke.texi	(working copy)
@@ -481,7 +481,7 @@  Objective-C and Objective-C++ Dialects}.
 @item Linker Options
 @xref{Link Options,,Options for Linking}.
 @gccoptlist{@var{object-file-name}  -fuse-ld=@var{linker} -l@var{library} @gol
--nostartfiles  -nodefaultlibs  -nostdlib -pie -rdynamic @gol
+-nostartfiles  -nodefaultlibs  -nostdlib -pie -pthread -rdynamic @gol
 -s  -static -static-libgcc -static-libstdc++ @gol
 -static-libasan -static-libtsan -static-liblsan -static-libubsan @gol
 -static-libmpx -static-libmpxwrappers @gol
@@ -1012,7 +1012,7 @@  See RS/6000 and PowerPC Options.
 -mfloat-gprs=yes  -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
 -mprototype  -mno-prototype @gol
 -msim  -mmvme  -mads  -myellowknife  -memb  -msdata @gol
--msdata=@var{opt}  -mvxworks  -G @var{num}  -pthread @gol
+-msdata=@var{opt}  -mvxworks  -G @var{num} @gol
 -mrecip -mrecip=@var{opt} -mno-recip -mrecip-precision @gol
 -mno-recip-precision @gol
 -mveclibabi=@var{type} -mfriz -mno-friz @gol
@@ -1085,7 +1085,7 @@  See RS/6000 and PowerPC Options.
 
 @emph{Solaris 2 Options}
 @gccoptlist{-mclear-hwcap -mno-clear-hwcap -mimpure-text  -mno-impure-text @gol
--pthreads -pthread}
+-pthreads}
 
 @emph{SPARC Options}
 @gccoptlist{-mcpu=@var{cpu-type} @gol
@@ -11526,6 +11526,14 @@  or model suboptions) when you specify th
 @opindex no-pie
 Don't produce a position independent executable.
 
+@item -pthread
+@opindex pthread
+Link with the POSIX threads library.  This option is supported on 
+GNU/Linux targets, most other Unix derivatives, and also on 
+x86 Cygwin and MinGW targets.  On some targets this option also sets 
+flags for the preprocessor, so it should be used consistently for both
+compilation and linking.
+
 @item -rdynamic
 @opindex rdynamic
 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
@@ -22040,11 +22048,6 @@  reliably associate function call with ar
 TLS optimization, which in turn allows GCC to better schedule the
 sequence.
 
-@item -pthread
-@opindex pthread
-Adds support for multithreading with the @dfn{pthreads} library.
-This option sets flags for both the preprocessor and linker.
-
 @item -mrecip
 @itemx -mno-recip
 @opindex mrecip
@@ -23186,14 +23189,7 @@  These switches are supported in addition
 @table @gcctabopt
 @item -pthreads
 @opindex pthreads
-Add support for multithreading using the POSIX threads library.  This
-option sets flags for both the preprocessor and linker.  This option does
-not affect the thread safety of object code produced  by the compiler or
-that of libraries supplied with it.
-
-@item -pthread
-@opindex pthread
-This is a synonym for @option{-pthreads}.
+This is a synonym for @option{-pthread}.
 @end table
 
 @node SPARC Options