Converting from #ifndef/#define include guards to #pragma once globally

GNU Radio
1

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello community,

after finding a minor mistake in a header include file this week, I’ve
wanted to make sure that the GR header files have proper,
non-conflicting include guards.

So I want to open the discussion whether GR would want to change from
#ifndef-based include guards to #pragma once.

What I noticed is:

  • there were 881 files that contained the classical
    #ifdef MACRO_WHATEVER
    #define MACRO_WHATEVER
    …
    #endif /maybe some comment/
    scheme in current master
  • replacing these with #pragma once has not damaged anything (as far
    as one simple make test can tell)
  • one minor mis-#define was found only which I believe is very
    reassuring for our overall code quality (1) (2).

I’ve created a script (3) that checks (4) whether c++ files follow the
classical include guard methodology, and replaces that with a #pragma
once. cmake && make && make test worked fine on the first run :slight_smile: which
made me confident enough to push everything (changed headers and the
script) to a branch:

https://github.com/marcusmueller/gnuradio/tree/convert_to_pragma_once

It would be great if people running other toolchains than I do
(gcc4.8.2/x86_64) would check if it breaks stuff.

If there is enough interest and consensus that we might want to switch
over to #pragma once (instead of just doing this “for testing purposes
only”), I think it’d be worthwhile to tackle things that stayed
untouched during automatic conversion:

  • .t templates
  • the newmod architecture

Greetings,
Marcus

(1) see my pull request against master
(2) however, vocoder/gsm/config.h uses #ifndef CONFIG_H, which I think
is a little bit asking for trouble
(3)
https://github.com/marcusmueller/gnuradio/blob/convert_to_pragma_once/dtools/bin/convert_ifndef_to_pragma_once
(4) checking is done by running it through the C preprocessor once to
get rid of comments and check the first line against an #ifndef macro,
and a second time to check whether defining that macro causes the file
to semantically disappear.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTCR4wAAoJEAFxB7BbsDrLj3oH/0NJi0qUT1Pj5FKMISU31tay
glCG1TG1j9Bj0r/NgaOook0pOgZrv2q5ZCDAJWgEnbxm8iI8NCiyYEorOhmoK5k7
GzACT4OTfQdISEq90zuvRelVxyFcRavxemI3d4hPTad3DHMIxLDzMtdYYROdCG2+
SUNuKzw9CiYPeXPuUNgChUAYxHDZSqCD+MpUBgOCeOtn9wa5eM7bJv8nuITsf0+h
13wW/EdEfQGkVuRyUIQySD2O8zvqNXobmzYRpmYnUkYg2tPxG5Kv6YAqhrFZY9El
hhJrmfI7Z6UK+zbq8Kt6qWHeXMglOGQVwFU1cZ0jZAvpZRiwJTzSeNBpF6LKcbE=
=WNPJ
-----END PGP SIGNATURE-----

2

Hi Marcus,

some quick Google research found several contradictory sources. [1]
calls it ‘non standard but widely supported’.
Since we build on weird platforms I think we should make absolutely
sure that this is the way things should be done ^{TM}.
Some other sources listed this as a potential speedup for compilation
on Visual Studio. Discuss.

Personally I don’t have an issue with header guards because there
exist plenty of plugins for {vim,emacs, whatever},
to do it for you.

Happy hacking,

Moritz

[1] pragma once - Wikipedia

3

I’ll second what Moritz wrote: Since this pragma is “non standard but
widely supported”, let’s stick with the header guards since they are
guaranteed to work even with very old C / C++ compilers … if someone
wants to -also- use this pragma that’s fine; having both should not
hurt. I’d prefer to not rely on just the pragma … my US$0.02 worth,
if even that much :wink: - MLD

4

Oh #pragma once - that old chesnut: if you have a few hours you can
follow
the various discussions on stackoverflow on it. I think it is at least
enlightening to read through this answer on why it is not part of the
ISO
C/C++ standards: Why isn't C/C++'s "#pragma once" an ISO standard? - Stack Overflow

I will note that on MSVC people have found compile-time improvements by
using #pragma once - although it tends to only be noticeable in
pathological cases. Still - an important feature for people going
through
the edit/compile/debug cycle.

My personal opinion on this is if there is a change to be made, it
should
be to use both: prepend #pragma once to header, and still include the
#ifndef/#endifs that are present: it takes advantage of the speedup for
compilers that don’t automagically recognize #ifndef/#endif header
guards
(e.g. non-GCC compilers), while simultaneously it doesn’t rely on
non-standard compliant compiler features (which I’ll argue we don’t want
to
introduce new non-standard things into the codebase).

I’m all for doing things that decrease bugs due to bad copy/paste errors
(especially since I seem to make those types of mistakes all the time),
but
relying on any compiler feature that is not part of the standard should
be
be very carefully considered. We support too many
platform/compiler-combinations to take such things lightly.

Doug

On Sun, Feb 23, 2014 at 2:52 PM, Michael D.

5

On Sun, Feb 23, 2014 at 3:22 PM, Marcus M. [email protected]
wrote:

approach.
in gcc < 3.4 (3.2 being the oldest gcc I’ve actually witnessed in the
for GR be? I don’t have a raging clue what people use on their
(2) GCC 3.4 Release Series — Changes, New Features, and Fixes - GNU Project, search for #pragma once

-----BEGIN PGP SIGNATURE-----
-----END PGP SIGNATURE-----
Ok, I wanted to wait until the conversation died down on this to see
what everyone’s thoughts were. From my perspective, because it’s
non-standard behavior, we aren’t going to switch to using #pragma
once. Because we are working on embedded systems, trying to use
co-processors like DSPs, FGPAs, and GPUs, we don’t want to find
ourselves in a situation where a compiler or tool messes us up because
we aren’t using a standards-define way of handling these things. It’s
unlikely that will actually be a problem, but I don’t want to add
another potential problem for us to deal with.

The #ifdefs aren’t perfect, obviously, but it’s easy to fix them if a
problem occurs. So I don’t find this to be broken behavior.

On the other hand, I won’t discourage the use of both. But until the
standard changes, we’ll continue with the #ifdef method of doing
things.

Thanks for the great discussion and feedback, though!

Tom

P.S. is compile time really that much of an issue? What are we talking
about shaving off? Seconds over the course of the entire build? If the
pragma method reduced our swig build times, now that would suddenly be
a compelling argument…

6

Hi Tom, hi fellow GR crowd,

thanks for your feedback and being so considerate :slight_smile:
Ok, I see all your points and in fact, by now, agree to them.
By the way, to add to your argumentative advantage here:
I didn’t expect any compile time decrease; in fact, GCC documentation
says that iff the #ifndef is the first and the #endif the last statement
or preprocessor directive, then the preparse/compile time is identical
to using #pragma once*, and my only indication for it improving compile
speed is boost using it conditionally only when compiled with MSVC. To
be honest, I did not benchmark gcc/cmake build times yet, but “they felt
the same” before and after.

As I see things now, I’d just not convert the files to #pragma once.
However, I do see usefulness in the possibility to analyze headers to
find ‘convertible’ include guards, because it is a feasible method of
ensuring that files don’t have erroneous include guards.
Basically, with a little tweaking my conversion script could be used to
do some QA on header files (and generate a report, or be run in a
post-receive hook etc)

  • checking for include guards (are there any headers that shouldn’t have
    'em?)
  • checking for unique include guard names
  • checking if include guards GCC-optimizable.

Greetings,
Marcus

*because the fact that the file is include-protected then is noted, and
the file is never read again

7

On 02/27/2014 11:42 PM, Marcus M. wrote:

  • checking if include guards GCC-optimizable.
    I think we’re already putting more energy into this than it deserves :slight_smile:
    At least for blocks, gr_modtool creates header guards that consist of
    the module- and the block name, which you should choose wisely anyway.
    Little chance of collisions here.

A script that would check for unique header guards wouldn’t hurt. But
what are “optimizable guards”? I think we have much bigger cookies to
bake right now.

M

8

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Moritz,

thanks :slight_smile: I agree on the “let’s not break builds for the pure beauty
of #pragma once” approach. I tried this only to find existing bugs,
and actually found very little; however, they could be completely
avoided by #pragma once, and therefore I do see value in using it. So
I humbly and slightly disagree with the “my editor does that for me”
approach.

Since I couldn’t find info on which compilers are minimally necessary
to build GR, I tried to figure out on my own(0). So far, I’ve not
quite come to any useful point. Boost uses the classical include
guards, but adds a #pragma once only for MSVC compilers(1) so those
might really profit from that. Reading the gcc 3.4 release notes (2)
suggests that prior to 3.4, #pragma once was but deprecated – showing
a few warnings in an ancient compiler doesn’t seem to be too bad :wink:

So I read on (3) and found out that in fact, #pragma once had problems
in gcc < 3.4 (3.2 being the oldest gcc I’ve actually witnessed in the
wild, these are not many) due to it not dealing with hard- and
symlinks properly. However, with our current source tree and build
methodology, this will not be critical. The only versions that would
actually produce warnings were some early gcc 3.3, after the problem
was found and before the pragma was un-deprecated again, so I think
you will hardly find someone using a compiler where this would do as
much as warn you that there is an deprecated pragma in use in the GNU
toolchain world.

So. The question stays the same: just how weird can build platforms
for GR be? I don’t have a raging clue what people use on their
embedded devices where they’d actually try to compile GR 3.7 for, so I
can’t really make a stand here.

Greetings,
Marcus

(0) If anyone knows how to get a non-interfering but working gcc3.2 on
a current fedora, let me know.
(1) o.O
(2) GCC 3.4 Release Series — Changes, New Features, and Fixes - GNU Project, search for #pragma once
(3) 11569 – there's no substitute for #pragma once
(4) 11569 – there's no substitute for #pragma once
On 23.02.2014 20:03, Moritz Fischer wrote:

you.

Happy hacking,

Moritz

[1] pragma once - Wikipedia

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTCliDAAoJEAFxB7BbsDrLieEH/1a76Tckl2wxu7Km8C3pwT5q
MkKlL0x9/z7NnxpKsiehHG3dQvE6w2Gt4VfS/CICDsVcU7jxYfVJHnOx7l+RLJ5w
ipU9ICKImQa+2Hn5L/2PYvwpW0JrkivGntJeiCt2UGP+Z/rBNLwuHUtSs8BR0FHO
uDCC8kvMIx9qUOBvNYwYAkRuXlFlxZHzpkNFfzzIK6gIMhN5mjRvKb93x3mJtfkd
dJR85OtxaKVFAz8kD9LEeKDLPa6DQtatfp2m07ghAlhdhyPbX+vyzqEfHhVq2p0Z
uDa3a5GqrWaA4hRn+Ypx6kB0gBN4nSycdM8cT3A5ad7cKf8jtarNOm1vYUhC/Ac=
=/8RU
-----END PGP SIGNATURE-----

9

Hi Martin,

“optimizable guards”: #ifndef at start, matching #endif at semantic
end-of-file; sorry to be unclear on that.
These are the include guards gcc cpp recognizes as such, which
suppresses repeated opening & parsing of that header. Agreeing, though,
that this is least priority. Also, almost all our include guards are
like this.

I think you’re right on the “enough energy put into this” – maybe I
should’ve been more careful when explicitely asking for discussion…
I guess this kind of ends the discussion, then :slight_smile: I’ll put up a github
repo for the tools I’ve generated so far, and leave the GR tree alone
(as long as I don’t find anything wildly disturbing).

Thank you all for your thought, extensive feedback and time!

Greetings,
Marcus

10

Hi Martin,
do not worry:
No discouragement took place, and I’ve just added a few lines of doc to
GitHub - marcusmueller/include-guard-convert: Converts C/C++ preprocessor #include guards from the #ifndef XY_H #define XY_H to the #pragma once paradigm,
and I’m totally happy about how much constructive feedback I’ve got from
everyone!
I really just agree with you that we shouldn’t put to much energy in the
dead-end discussion whether to migrate to #pragma once, since there are
none in favour anymore :slight_smile:

Marcus

11

On 02/28/2014 10:02 AM, Marcus M. wrote:

should’ve been more careful when explicitely asking for discussion…
I guess this kind of ends the discussion, then :slight_smile: I’ll put up a github
repo for the tools I’ve generated so far, and leave the GR tree alone
(as long as I don’t find anything wildly disturbing).

Hey, I don’t want to discourage discussions of any kind! Nothing wrong
at all with bringing things like this up.

M