[Bug c++/110092] New: Missing warning that internal header is used

[Bug c++/110092] New: Missing warning that internal header is used

[piotrwn1 at gmail dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

            Bug ID: 110092
           Summary: Missing warning that internal header is used
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: c++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: piotrwn1 at gmail dot com
  Target Milestone: ---

Developers new to C++ have sometime problems with including proper std library
header, instead, they sometimes include standard library internal headers -
since the definition is there and some IDE shows "you have this entity here".

I have tried "-Wall -Wextra -pedantic" and nothing warns me when, just for
example purposes, I included `<bits/shared_ptr.h>` whilst `<memory>` should
included.

I see in this "internal" header (bits/shared_ptr.h) the following information:

```
44      /** @file
45       *  This is an internal header file, included by other library headers.
46       *  Do not attempt to use it directly. @headername{memory}
47       */
```

So, probably it is doable to add warning like: "bist/shared_ptr.h is an
internal header file, included by other library headers. Do not attempt to use
it directly. Use <memory> instead"

[Bug c++/110092] Missing warning that internal header is used

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

--- Comment #1 from Jonathan Wakely <redi at gcc dot gnu.org> ---
This seems more like a bug in the IDE than in GCC. If you don't include the
header at all then GCC tells you the right header:

sp.cc: In function ‘int main()’:
sp.cc:2:8: error: ‘shared_ptr’ is not a member of ‘std’
    2 |   std::shared_ptr<int> s;
      |        ^~~~~~~~~~
sp.cc:1:1: note: ‘std::shared_ptr’ is defined in header ‘<memory>’; did you
forget to ‘#include <memory>’?
  +++ |+#include <memory>
    1 | int main() {

[Bug c++/110092] Missing warning that internal header is used

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Severity|normal                      |enhancement

--- Comment #2 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Piotr Nycz from comment #0)
> So, probably it is doable to add warning like: "bist/shared_ptr.h is an
> internal header file, included by other library headers. Do not attempt to
> use it directly. Use <memory> instead"

We could add this to <bits/shared_ptr.h>:

#ifndef _GLIBCXX_MEMORY
# error Do not include <bits/shared_ptr.h> directly, include <memory> instead.
#endif

But then you'd get an error when you include <regex>, or <filesystem>, or
<chrono>, or any of the other headers that use std::shared_ptr internally.

So we'd have to do:

#if !defined _GLIBCXX_MEMORY && !defined _GLIBCXX_CHRONO && !defined
_GLIBCXX_REGEX \
    && ! defined ...

And that would be a pain to maintain.

And then it would still not give an error for this, even though it's still
wrong:

#include <chrono>
#include <bits/shared_ptr.h>
std::shared_ptr<int> p;

So I don't think this can really be solved in the compiler without a lot of
work to hardcode special handling for each of those headers.

[Bug c++/110092] Missing warning that internal header is used

[piotrwn1 at gmail dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

--- Comment #3 from Piotr Nycz <piotrwn1 at gmail dot com> ---
(In reply to Jonathan Wakely from comment #2)
> (In reply to Piotr Nycz from comment #0)
> > So, probably it is doable to add warning like: "bist/shared_ptr.h is an
> > internal header file, included by other library headers. Do not attempt to
> > use it directly. Use <memory> instead"
> 
> We could add this to <bits/shared_ptr.h>:
> 
> #ifndef _GLIBCXX_MEMORY
> # error Do not include <bits/shared_ptr.h> directly, include <memory>
> instead.
> #endif
> 
> But then you'd get an error when you include <regex>, or <filesystem>, or
> <chrono>, or any of the other headers that use std::shared_ptr internally.
> 
> So we'd have to do:
> 
> #if !defined _GLIBCXX_MEMORY && !defined _GLIBCXX_CHRONO && !defined
> _GLIBCXX_REGEX \
>     && ! defined ...
> 
> And that would be a pain to maintain.
> 
> And then it would still not give an error for this, even though it's still
> wrong:
> 
> #include <chrono>
> #include <bits/shared_ptr.h>
> std::shared_ptr<int> p;
> 
> So I don't think this can really be solved in the compiler without a lot of
> work to hardcode special handling for each of those headers.

Well, I did not mean to make such a mess in compiler headers for sure. But if
it is somehow detectable that the compiler is compiling something in user
directories (not in std library, compiler stuff) then maybe it can be detected
by compiler that something internal is included in user file. I am just
guessing, I do not have any knowledge about how gcc compiler is working. 
I see that system headers have some pragma telling it is system header and
these internal headers have comment in `@file` section that it is internal. 

But of course - it could be done by some other tool like clang-tidy, if this is
a big problem. I just think it would be nice to have such warning - so it is
more "new feature request" than bug report.

[Bug c++/110092] Missing warning that internal header is used

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

--- Comment #4 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
(In reply to Jonathan Wakely from comment #1)
> This seems more like a bug in the IDE than in GCC. If you don't include the
> header at all then GCC tells you the right header:
> 
> sp.cc: In function ‘int main()’:
> sp.cc:2:8: error: ‘shared_ptr’ is not a member of ‘std’
>     2 |   std::shared_ptr<int> s;
>       |        ^~~~~~~~~~
> sp.cc:1:1: note: ‘std::shared_ptr’ is defined in header ‘<memory>’; did you
> forget to ‘#include <memory>’?
>   +++ |+#include <memory>
>     1 | int main() {

Right, the IDE trying to push folks to include the wrong header files is a bug
in the IDE; not just in this case either. There are other libraries which will
have a similar issue besides libstdc++ too. IDEs trying to be smart are not
always the best thing.

[Bug c++/110092] Missing warning that internal header is used

[piotrwn1 at gmail dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110092

--- Comment #5 from Piotr Nycz <piotrwn1 at gmail dot com> ---
(In reply to Jonathan Wakely from comment #2)
> (In reply to Piotr Nycz from comment #0)
> > So, probably it is doable to add warning like: "bist/shared_ptr.h is an
> > internal header file, included by other library headers. Do not attempt to
> > use it directly. Use <memory> instead"
> 
> We could add this to <bits/shared_ptr.h>:
> 
> #ifndef _GLIBCXX_MEMORY
> # error Do not include <bits/shared_ptr.h> directly, include <memory>
> instead.
> #endif
> 
> But then you'd get an error when you include <regex>, or <filesystem>, or
> <chrono>, or any of the other headers that use std::shared_ptr internally.
> 
> So we'd have to do:
> 
> #if !defined _GLIBCXX_MEMORY && !defined _GLIBCXX_CHRONO && !defined
> _GLIBCXX_REGEX \
>     && ! defined ...
> 
> And that would be a pain to maintain.
> 
> And then it would still not give an error for this, even though it's still
> wrong:
> 
> #include <chrono>
> #include <bits/shared_ptr.h>
> std::shared_ptr<int> p;
> 
> So I don't think this can really be solved in the compiler without a lot of
> work to hardcode special handling for each of those headers.

After few days this problem was sitting in my head - I think I found easy
solution to std library and all other libs with similar problems of how to
prevent users from including internal headers.

1. Define at the beginning of each interface header some macro/symbol, undef it
at the end of each file.
2. In every internal header - make sure this symbol is defined, otherwise
#error (I would prefer #warning in this case - just in case somebody do include
this internal header already for some reasons)

An example:

```
//@file memory

#ifndef GCC_STD_LIBRARY_HEADER
#define GCC_STD_LIBRARY_HEADER 1
#else
#define GCC_STD_LIBRARY_MEMORY_HEADER_IS_NOT_FRONT_HEADER 1
#endif

...
#include <bits/shared_ptr.h>

...

#ifdef GCC_STD_LIBRARY_MEMORY_HEADER_IS_NOT_FRONT_HEADER
#undef GCC_STD_LIBRARY_MEMORY_HEADER_IS_NOT_FRONT_HEADER
#else
#undef GCC_STD_LIBRARY_HEADER
#endif


```

```
//@file bits/shared_ptr.h

#if !defined(GCC_STD_LIBRARY_HEADER) &&
!defined(I_KNOW_INCLUDING_BITS_SHARED_PTR_H_IS_NOT_SUPPORTED_BY_STDLIB_BUT_I_NEED_TO_DO_IT)
#warning bits/shared_ptr.h is ... internal ..., include <memory> instead"
#endif

...

```