Compile time enforce developers don't include BigHeader.h inside .h files

Question

I am working on a large project and there is a BigHeader.h which is very costly to include compile time wise, and a BigHeaderFwd.h. I want to enforce that users don't do this:

// SomeRandomFile.h
#include "BigHeader.h"

void useFunc(const BigHeader& bh);

How can I write a compile time / preprocessor time logic inside BigHeader.h to the effect of

#if included in .h file
# error, with message "please include BigHeaderFwd instead"
# else
 // no errror

I want to avoid external scripts if possible

Thanks

Answer 1

How can I write a compile time / preprocessor time logic inside BigHeader.h to the effect of

Create a macro that will have to be added every time big header is included.

// BigHeader.h
#ifndef I_KNOW_WHAT_I_AM_DOING_AND_WANT_TO_INCLUDE_BIG_HEADER_H
#error "please include BigHeaderFwd instead"
#endif

// SomeRandomFile.h
#include "BigHeader.h" //error

// SomeRandomApprovedFile.h
#define I_KNOW_WHAT_I_AM_DOING_AND_WANT_TO_INCLUDE_BIG_HEADER_H
#include "BigHeader.h"

You may be interested in feature_test_macros . Similar method is used in glibc bits headers directory.

Answer 2

1. Allow including only with a special definition

This solution has already been proposed by @KamilCuk. In essence, error if the header was included without some I_KNOW_WHAT_I_AM_DOING_AND_WANT_TO_INCLUDE_BIG_HEADER_H definition prior to the #include.

Of course, an incredibly stupid, or malicious developer can bypass this restriction and still include the header.

2. Hide the header as well as possible

You can locate the header inside a secret folder in your include/ directory, or just outside of it. If the headers of your library are located in mylib/include, you can put the header in:

• mylib/include/mylib/implementation_secrets/BigHeader.h, which makes it possible for your headers to include it, but would make it less convenient for other developers to do it
• mylib/secret_include/BigHeader.h, in which case you can include it via relative paths from other headers, e.g. #include "../../secret_include/BigHeader.h"

Of course, a malicious developer can still include it, even if it's in a weird place.

3. Force linker errors

You can exploit the fact that external symbols can only be defined in one translation unit, unless they are inline:

// BigHeader.h
int YOU_MUST_NOT_INCLUDE_ME_YOU_FOOL = 0;

The result is that if BigHeader.h is included in more than one place, you will get a linker error. Obviously, this is only somewhat useful, because it also breaks you own code if you include it more than once.

4. Whitelist source files

You can use GCC's __BASE_FILE__ macro which expands to the name of the cpp file which is currently compiled. Force a compiler error if this is not what you expect.

// BigHeader.h

constexpr std::string_view includer = __BASE_FILE__ ;
static_assert(includer == "blessed_file.cpp",
              "Cannot include BigHeader.h from " __BASE_FILE__);

However, even with this method, a malicious or stupid developer can rename their source file to blessed_file.cpp and bypass this restriction.

5. Count includes

Perhaps the most over-engineered solution yet:

// BigHeader.h

inline int count_include() {
    constexpr int max_includes = 3;
    static int counter = 0;

   if (++counter > max_includes) {
       throw ":("; // TODO: throw an exception, call std::terminate, etc.
   }
   return counter;
}

// dynamic initialization, one function call per including TU
static const int call_count_include = count_include();

In every cpp file which includes BigHeader.h, the definition of count_include() is always the same, and the same counter is incremented. However, the definition of call_count_include is unique for each cpp file, and count_include() will be called once for each.

Answer 3

If your goal is to avoid long compilation times, then simply don't merge commits that increase compilation time over a certain threshold. Otherwise read on.

You can create a C++ header file that is difficult to include in an .h file by mistake. One major downside is that you need additional syntax. There are other downsides as well.

#ifndef BigHeader_H
#define BigHeader_H

#include <source_location>

// some declarations

// a constexpr version of strlen
constexpr size_t ce_strlen(const char* s)
{
  std::size_t l = 0;
  while(*s++) l++;
  return l;
}

#define CONCAT(A,B) CONCAT2(A,B)
#define CONCAT2(A,B) A##B

#define VALIDATE_BIG_HEADER \
  namespace CONCAT(bigheader_detail_, __LINE__) { \
  static constexpr std::source_location loc = std::source_location::current(); \
  static constexpr char const * const f = loc.file_name(); \
  static constexpr std::size_t len = ce_strlen(loc.file_name()); \
  static_assert(len > 2 && !(f[len-1] == 'h' && f[len-2] == '.'), \
                 "BigHeader.h cannot be included from .h files"); \
  }

#define CLOSE_BIG_HEADER \
  } VALIDATE_BIG_HEADER

#endif
// note this comes AFTER the final #endif
// It's cheap insurance against forgetting to type CLOSE_BIG_HEADER 

namespace bigheader_cheap_insurance {

Your users must do this:

#include <BigHeader.h>
CLOSE_BIG_HEADER

If they forget CLOSE_BIG_HEADER, their code will most probably not compile. If CLOSE_BIG_HEADER occurs in a file with an .h suffix, a static assertion is triggered.

Of course a malicious developer can redefine CLOSE_BIG_HEADER and abuse it with reckless abandon, but I don't think it is possible to protect against that.

I would not recommend such things in production code.