Software is Crap

Crappy g++ documentation on template instantiation


The g++ documentation says on template instantiation:

G++ has extended the template instantiation syntax given in the ISO standard to allow forward declaration of explicit instantiations (with extern), instantiation of the compiler support data for a template class (i.e. the vtable) without instantiating any of its members (with inline), and instantiation of only the static data members of a template class, without the support data or member functions (with (static):

extern template int max (int, int);
inline template class Foo<int>;
static template class Foo<int>;

The one I’m interested in is “extern”. The docs as quoted above say that it “allows forward declaration of explicit instantiations”, but that’s useless; explicit template instantiations don’t need forward declarations, you may as well just do the instantiation. Of course, the documentation is actually incorrect by omission: the “extern” keyword in front of an explicit template instantiation (as in the example above) actually causes gcc not to emit the instantiated template (even when it would otherwise do so because of implicit instantiation). This means that we can use this syntax to avoid emitting a template instantiation which we know is already emitted in another module.

Avoiding the emission of a template instantiation in many cases has only limited practical value – it might reduce compilation and linkage time ever so slightly, and likewise reduce the disk space used by object files ever so slightly. It would also allow for removing the emitted instantiation from a shared library or executable if the same instantiation was known to be present in another library that we were linking against.

The point is, there’s a potentially useful feature which isn’t documented, yet the syntax is documented – with an incorrect description of what it does.