diff --git a/doc/developer-notes.md b/doc/developer-notes.md index d17f8024ee4..b8a16ec0901 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -558,6 +558,21 @@ llvm-cov show \ The generated coverage report can be accessed at `build/coverage_report/index.html`. +### Using IWYU + +The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU) +helps to enforce the source code organization [policy](#source-code-organization) in this repository. + +To ensure consistency, it is recommended to run the IWYU CI job locally rather than running the tool directly. + +In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required. +For example, a macro may use a symbol that requires its own include. Another example is passing a string literal +to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the +`std::string` constructor, which makes the corresponding header required. We accept these suggestions as is. + +Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers +and undermines the specific purpose of IWYU. + ### Performance profiling with perf Profiling is a good way to get a precise idea of where time is being spent in @@ -1057,7 +1072,7 @@ Write scripts in Python or Rust rather than bash, when possible. - *Rationale*: Excluding headers because they are already indirectly included results in compilation failures when those indirect dependencies change. Furthermore, it obscures what the real code - dependencies are. + dependencies are. The [Using IWYU](#using-iwyu) section describes a tool to help enforce this. - Don't import anything into the global namespace (`using namespace ...`). Use fully specified types such as `std::string`. diff --git a/src/core_io.cpp b/src/core_io.cpp index 58989115a50..e715a329e34 100644 --- a/src/core_io.cpp +++ b/src/core_io.cpp @@ -9,6 +9,7 @@ #include #include #include +#include #include // IWYU incorrectly suggests replacing this header // with forward declarations. diff --git a/src/kernel/chainparams.cpp b/src/kernel/chainparams.cpp index c25455d0f1c..16ebffb9a98 100644 --- a/src/kernel/chainparams.cpp +++ b/src/kernel/chainparams.cpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include diff --git a/src/node/blockstorage.cpp b/src/node/blockstorage.cpp index 84b7cfec7c7..37bf1799aa4 100644 --- a/src/node/blockstorage.cpp +++ b/src/node/blockstorage.cpp @@ -7,6 +7,7 @@ #include #include #include +#include #include #include #include diff --git a/src/util/strencodings.h b/src/util/strencodings.h index 01063858047..b070e5b8c40 100644 --- a/src/util/strencodings.h +++ b/src/util/strencodings.h @@ -9,7 +9,7 @@ #ifndef BITCOIN_UTIL_STRENCODINGS_H #define BITCOIN_UTIL_STRENCODINGS_H -#include // IWYU pragma: export +#include #include #include @@ -20,8 +20,8 @@ #include #include #include -#include // IWYU pragma: export -#include // IWYU pragma: export +#include +#include #include #include #include diff --git a/src/util/string.h b/src/util/string.h index 330c2a2a61e..2578e530af5 100644 --- a/src/util/string.h +++ b/src/util/string.h @@ -12,8 +12,8 @@ #include #include #include -#include // IWYU pragma: export -#include // IWYU pragma: export +#include +#include #include namespace util {