Re: [patch] Update template instantiation documentation

[Andrew Pinski <pinskia at gmail dot com>]

On Sat, Oct 3, 2015 at 9:44 AM, Sandra Loosemore
<sandra@codesourcery.com> wrote:
> On 10/03/2015 06:47 AM, Jonathan Wakely wrote:
>>
>> https://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html
>> currently says that using -frepo "is your best option for application
>> code written for the Borland model, as it just works."
>>
>> That was true at one point, but as can be seen from the mentions of
>> binutils 2.8 and Solaris 2, the information there is pretty old.
>>
>> Since then -frepo has bitrotted occasionally, and it's much simpler to
>> rely on implicit instantiations in COMDAT sections, controlling
>> specific instantiations with explicit instantiations if needed (using
>> 'extern template' which was standardised in C++11).
>>
>> See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51910#c2 for an
>> example of bitrot (now fixed) and people being persuaded by the docs
>> that -frepo is the best option.
>>
>> So this revises the docs, to downplay the usefulness of -frepo,
>> and to endorse the "do nothing" model (with selective explicit
>> instantations as needed).
>>
>> It also changes another mention of -frepo to use a different C++-only
>> option, to further de-emphasize -frepo.
>>
>> OK for trunk?
>
>
> Thanks for tackling this.  I remember thinking that this section looked
> bit-rotted when I was reviewing the manual earlier this year.  Your patch
> looks like a step in the right direction, but can I get you to fix a couple
> other things while you're at it?
>
> First, I think the reference to ancient ld versions is confusing, and it
> would be better to rewrite that to emphasize that this is the default
> behavior on most targets.  (I'd guess that anybody trying to use a recent
> GCC release with an ld version from 1996 is going to run into more critical
> blocking issues than this one.)  Maybe something like:
>
> "G++ implements the Borland model on targets where the linker supports it,
> including both ELF targets (such as GNU/Linux) and Microsoft Windows.
> Otherwise G++ implements neither automatic model."


Add "And Mac OS X" to that too.  So people don't use that against us
for the reason why Apple went to clang/LLVM.

Thanks,
Andrew

>
> Second, if "Do nothing" is now the recommended way to handle this, let's
> move that option to the front of the itemized list instead of the end. Also,
> I'm confused by the "pretend" here; can we just delete that sentence?
>
> -Sandra
>