iwyu: Document or remove some `pragma: export` and other improvements

hebasto commented at 5:54 pm on February 20, 2026: member

This PR is a prerequisite for #34448. It was split into a separate PR to limit the scope and minimize potential merge conflicts.

The first commit improves the accuracy of IWYU suggestions within our heavily templated code. Note that, for now, the serialize.h header itself is excluded from IWYU inspection because it lacks a corresponding source file.

The remaining commits follow the Developer Notes guidance:

Use IWYU pragma: export very sparingly, as this enforces transitive inclusion of headers and undermines the specific purpose of IWYU.

hebasto added the label Refactoring on Feb 20, 2026

DrahtBot commented at 5:54 pm on February 20, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#34448 (ci, iwyu: Fix warnings in src/util and treat them as errors by hebasto)
#34038 (logging: replace -loglevel with -trace, various API improvements by ajtowns)
#30343 (wallet, logging: Replace WalletLogPrintf() with LogInfo() by ryanofsky)
#29256 (log, refactor: Allow log macros to accept context arguments by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

DrahtBot added the label CI failed on Feb 20, 2026

DrahtBot removed the label CI failed on Feb 20, 2026

in src/sync.h:13 in e61ec118ef outdated

 9@@ -10,7 +10,7 @@
10 #include <logging/timer.h>
11 #endif
12 
13-#include <threadsafety.h> // IWYU pragma: export
14+#include <threadsafety.h>

maflcko commented at 7:34 am on February 27, 2026:

this was added in fa02591edff0255c5120b5acb2366542a61c251f, because there is only one single case (src/logging.h) that does not need sync.h.

So I think it is fine to keep as-is, or add a comment why this export exists?

hebasto commented at 11:04 am on February 27, 2026:

It seems there are opposing views here.

this was added in fa02591…

Right. Its message states: “All places that include sync.h will likely need threadsafety annotations, so export them.” This essentially reads as using the IWYU pragma: export as a convenient way to save one line in header inclusions.

I prefer to reserve this pragma for two specific scenarios: (1) providing symbols from headers that are an implementation of the main header, or (2) in facade headers such as compat.h.

I believe that the consistency gained by explicitly including used headers is more valuable than trying to avoid inclusion noise.

So I think it is fine to keep as-is, or add a comment why this export exists?

What wording did you have in mind for that comment?

maflcko commented at 2:06 pm on February 27, 2026:

0// Export, as `threadsafety.h` is practically not used stand-alone.

hebasto commented at 2:11 pm on February 27, 2026:

@fanquake

Given your previous comment, would you agree on that?

in src/util/time.h:9 in 4306f57170 outdated

 5@@ -6,7 +6,7 @@
 6 #ifndef BITCOIN_UTIL_TIME_H
 7 #define BITCOIN_UTIL_TIME_H
 8 
 9-#include <chrono> // IWYU pragma: export
10+#include <chrono>

maflcko commented at 7:36 am on February 27, 2026:

for reference, this was added, so that this serves as a drop-in replacement for chrono, and that the using namespace std::chrono_literals; a few lines below is put into basically all places.

Though, this is just my personal preference, and I can see this to be changed.

hebasto commented at 11:12 am on February 27, 2026:

for reference, this was added, so that this serves as a drop-in replacement for chrono, and that the using namespace std::chrono_literals; a few lines below is put into basically all places.

If that is the intention, it would be better expressed as an IWYU mapping instead:

0  { "include": [ "<chrono>", "public", "<util/time.h>", "public" ] },

maflcko commented at 11:24 am on February 27, 2026:

Yeah, I don’t feel strongly about his one. I think anything is fine here.

hebasto commented at 2:03 pm on February 27, 2026:

for reference, this was added, so that this serves as a drop-in replacement for chrono, and that the using namespace std::chrono_literals; a few lines below is put into basically all places.

If that is the intention, it would be better expressed as an IWYU mapping instead:
0  { "include": [ "<chrono>", "public", "<util/time.h>", "public" ] },

Actually, this works for private headers only.

Added an explanatory comment instead.

in src/util/log.h:8 in 952662a6fa outdated

4@@ -5,7 +5,7 @@
5 #ifndef BITCOIN_UTIL_LOG_H
6 #define BITCOIN_UTIL_LOG_H
7 
8-#include <logging/categories.h> // IWYU pragma: export
9+#include <logging/categories.h>

maflcko commented at 7:41 am on February 27, 2026:

Same here. Is there a use-case to include logging/categories.h without either one of util/log.h or logging.h?

hebasto commented at 11:07 am on February 27, 2026:

Mind suggesting a comment for these cases?

maflcko commented at 11:24 am on February 27, 2026:

0// Export, as `logging/categories.h` is practically not used stand-alone.

hebasto commented at 2:04 pm on February 27, 2026:

Thanks! Taken.

maflcko commented at 7:44 am on February 27, 2026: member

Personally I think it is fine to use export for headers that are always (possibly with a single exception) simply forwarded via another header.

I think this applies to all cases here, except for the chrono one?

serialize: Add missing `<span>` header

Including the missing `<span>` header in `serialize.h` allows IWYU to
correctly evaluate its redundancy elsewhere.

1db861845f

iwyu, doc: Document `IWYU pragma: export` for `<chrono>` abca6024c9

iwyu, doc: Document `IWYU pragma: export` for `<logging/categories.h>` 5fdf1da22e

iwyu: Remove `pragma: export` for `<threadsafety.h>` de4c286f1b

hebasto force-pushed on Feb 27, 2026

hebasto commented at 2:05 pm on February 27, 2026: member

@maflcko

Thank you for the review! Your feedback has been addressed.

hebasto renamed this:
~~iwyu: Remove some `pragma: export` and other improvements~~
iwyu: Document or remove some `pragma: export` and other improvements
on Feb 27, 2026

iwyu: Document or remove some pragma: export and other improvements #34639

Reviews

Conflicts

iwyu: Document or remove some `pragma: export` and other improvements #34639