Replace include guards with #pragma once

[antoinevg]

Depends on #1701

---

This PR removes include guards in the style of:

#ifndef __SOME_FILE_H__
#define __SOME_FILE_H__

...

#endif // __SOME_FILE_H__

…and replaces them with:

#pragma once 

...

[gullradriel]

#pragma once tells the compiler "only include this file once", but the compiler has to figure out what "this file" means. It typically does that using the file's path or inode.
If the same header is reachable via two paths (a symlink, a bind mount, a copied include directory), the compiler may see them as two different files and include it twice, defeating the whole point.
Header guards don't have this problem because they work purely in the preprocessor's token space, the guard macro is either defined or it isn't, regardless of how you got to the file.
I would call it an unnecessary AI code bad move.

[martinling]

@gullradriel

If the same header is reachable via two paths (a symlink, a bind mount, a copied include directory), the compiler may see them as two different files and include it twice, defeating the whole point.

If you have two headers with the same name, in directories that are both in the compiler's list of include paths, like
inc/a/api.h and inc/b/api.h, with -Iinc/a -Iinc/b passed to the compiler; then #include <api.h> is only ever going to include a/api.h, because that's the api.h found first in the search path. It won't include both, regardless of whether #pragma once or traditional header guards are used.

To include both api.h headers, you'd have to make it possible to distinguish them by the paths used in the #include statements. E.g. pass -Iinc to the compiler, and then write:

#include <a/api.h>
#include <b/api.h>

In which case, it's pretty clear that you're actually intentionally including both headers.

Header guards don't have this problem because they work purely in the preprocessor's token space

That's actually exactly the problem with them. Because there's no guaranteed way to uniquely name them, it's quite likely that if a and b are unrelated projects, both a/api.h and b/api.h might choose the same guard name, such as API_H. The more generic the name of the header, the more likely this is to happen.

In fact, this is exactly the scenario that led me to ask @antoinevg for this change. I was working on our Portapack firmware project that @mossmann mentioned in portapack-mayhem/mayhem-firmware#2957 (comment), and I ended up needing to include both gpio.h from the HackRF source, and gpio.hpp from the PortaPack source. Both of them used the same guard name, __GPIO_H__, making it impossible to use both at once. At that point the only option was to modify one of the projects to prevent the clash.

This is where #pragma once is a better solution, precisely because it doesn't depend on choosing unique names. It also avoids a lot of other mistakes that are common with traditional guards, like:

• clashes with system headers (officially, all identifiers starting with __ are reserved to the C implementation!)
• inconsistency about how to name guards within the project (e.g. we have a mix of __NAME_H and __NAME_H__)
• forgetting to change a guard name when renaming a file, or copying code from one file to another
• mismatching the #ifndef and the #define, (as I fixed recently in our libopencm3 submodule).

The main issue with #pragma once was that it wasn't always supported by all compilers, but that hasn't been the case for a very long time now - it's been in GCC since 3.4 in 2004, in clang from the start, and in everything else for ages too by now.

[mossmann]

Excellent! Thank you!

[mossmann]

nice catch

[gullradriel]

@gullradriel

If the same header is reachable via two paths (a symlink, a bind mount, a copied include directory), the compiler may see them as two different files and include it twice, defeating the whole point.

If you have two headers with the same name, in directories that are both in the compiler's list of include paths, like inc/a/api.h and inc/b/api.h, with -Iinc/a -Iinc/b passed to the compiler; then #include <api.h> is only ever going to include a/api.h, because that's the api.h found first in the search path. It won't include both, regardless of whether #pragma once or traditional header guards are used.

To include both api.h headers, you'd have to make it possible to distinguish them by the paths used in the #include statements. E.g. pass -Iinc to the compiler, and then write:

#include <a/api.h>
#include <b/api.h>

In which case, it's pretty clear that you're actually intentionally including both headers.

Header guards don't have this problem because they work purely in the preprocessor's token space

That's actually exactly the problem with them. Because there's no guaranteed way to uniquely name them, it's quite likely that if a and b are unrelated projects, both a/api.h and b/api.h might choose the same guard name, such as API_H. The more generic the name of the header, the more likely this is to happen.

In fact, this is exactly the scenario that led me to ask @antoinevg for this change. I was working on our Portapack firmware project that @mossmann mentioned in portapack-mayhem/mayhem-firmware#2957 (comment), and I ended up needing to include both gpio.h from the HackRF source, and gpio.hpp from the PortaPack source. Both of them used the same guard name, __GPIO_H__, making it impossible to use both at once. At that point the only option was to modify one of the projects to prevent the clash.

This is where #pragma once is a better solution, precisely because it doesn't depend on choosing unique names. It also avoids a lot of other mistakes that are common with traditional guards, like:

• clashes with system headers (officially, all identifiers starting with __ are reserved to the C implementation!)
• inconsistency about how to name guards within the project (e.g. we have a mix of __NAME_H and __NAME_H__)
• forgetting to change a guard name when renaming a file, or copying code from one file to another
• mismatching the #ifndef and the #define, (as I fixed recently in our libopencm3 submodule).

The main issue with #pragma once was that it wasn't always supported by all compilers, but that hasn't been the case for a very long time now - it's been in GCC since 3.4 in 2004, in clang from the start, and in everything else for ages too by now.

No offenses intended. But, from the very same article you are mentioning, carefully read the caveats section. Maybe my case is not everyone's case, I'm working on legacies code bases on servers, with lots of symlinks and source files copies. I did not choose that, I inherited that and fix as I can. And pragma got our asses more than one time. I guess for hackRF code it's ok, but it's not the best move ever, from my point of view. I'm surely getting old, at least for code opinions and view points....

[martinling]

This is missing the same change in the recently-added da7219.h.

[antoinevg]

This is missing the same change in the recently-added da7219.h.

Whoopsie tx! Fixed and force-pushed.

[martinling]

No offenses intended.

None taken!

But, from the very same article you are mentioning, carefully read the caveats section. Maybe my case is not everyone's case, I'm working on legacies code bases on servers, with lots of symlinks and source files copies. I did not choose that, I inherited that and fix as I can. And pragma got our asses more than one time. I guess for hackRF code it's ok, but it's not the best move ever, from my point of view.

I have read that, and the claim that #pragma once "can do the wrong thing" is marked with [citation needed]

Are you able to describe a specific scenario that may cause a problem - with compilers from the last 20 years?

I've been doing a bit of research about this, because it's been feeling to me like "#pragma once is unreliable" might have become one of those bits of folk wisdom that us older folks remember, but for reasons that are no longer quite so clear.

What I've found is that support for it was first added to GCC in 2001 in the venerable 2.95 release, but with a buggy implementation which would sometimes get confused and include things twice. In 2003, it was deprecated and slated for removal, both due to that bug, and the fact it was not yet standardised.

However, the implementation was then fixed in 2004, released in version 3.4 and the deprecation removed.

I've yet to find anything definitive that suggests it's been an actual problem since!