Re: [PATCH] gcc/doc: list what version each attribute was introduced in

["Daniel P. Berrange" <berrange@redhat.com>]

On Fri, Jul 07, 2017 at 11:01:51AM -0600, Jeff Law wrote:
> On 07/06/2017 07:25 AM, Daniel P. Berrange wrote:
> > There are several hundred named attribute keys that have been
> > introduced over many GCC releases. Applications typically need
> > to be compilable with multiple GCC versions, so it is important
> > for developers to know when GCC introduced support for each
> > attribute.
> > 
> > This augments the texi docs that list attribute keys with
> > a note of what version introduced the feature. The version
> > information was obtained through archaeology of the GCC source
> > repository release tags, back to gcc-4_0_0-release. For
> > attributes added in 4.0.0 or later, an explicit version will
> > be noted. Any attribute that predates 4.0.0 will simply note
> > that it has existed prior to 4.0.0. It is thought there is
> > little need to go further back in time than 4.0.0 since few,
> > if any, apps will still be using such old compiler versions.
> > 
> > Where a named attribute can be used in many contexts (ie the
> > 'visibility' attribute can be used for both functions or
> > variables), it was assumed that the attribute was supported
> > in all use contexts at the same time.
> > 
> > Future patches that add new attributes to GCC should be
> > required to follow this new practice, by documenting the
> > version.
> Keying on version #s is generally a terrible way to make your code
> portable.  It's easy to get wrong and due to backporting there's not
> always a strong tie between a version number and the existence of a
> particular feature.
> 
> It's far better to actually *test* what your particular compiler
> compiler supports.  I suspect autoconf, for example, probably has some
> infrastructure for testing if specific attributes are supported by the
> compiler.

That could be done if the attributes are used for internal code, as you can
rely on having run autoconf before using the header file. If you are adding
attributes to public header files of a library, the usage has to be
self-contained to that applications can simply include your library's headers
without having to perform a bunch of extra checks. Keying off version appears
to be the only viable approach here, and is widely used for wrapping the
attribute usage, so I think this documentation still has value.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|