diff options
| author | Peter Eisentraut <peter@eisentraut.org> | 2025-01-15 18:57:53 +0100 |
|---|---|---|
| committer | Peter Eisentraut <peter@eisentraut.org> | 2025-01-15 18:57:53 +0100 |
| commit | 44512e7c952f798c9912476ac5fc2132493f9af7 (patch) | |
| tree | e60209e1ed6fb4d4aea733016bb8cc4111a9d843 /src | |
| parent | fecc8021e1c851d2f180cc96521314a0daf2b30b (diff) | |
| download | postgresql-44512e7c952f798c9912476ac5fc2132493f9af7.tar.gz postgresql-44512e7c952f798c9912476ac5fc2132493f9af7.zip | |
Add a bit of documentation related to IWYU
Add some basic information about IWYU to src/tools/pginclude/README.
Discussion: https://www.postgresql.org/message-id/flat/9395d484-eff4-47c2-b276-8e228526c8ae@eisentraut.org
Diffstat (limited to 'src')
| -rw-r--r-- | src/tools/pginclude/README | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/src/tools/pginclude/README b/src/tools/pginclude/README index 007d0397e79..2f8fe6b78ba 100644 --- a/src/tools/pginclude/README +++ b/src/tools/pginclude/README @@ -1,5 +1,47 @@ src/tools/pginclude/README +This directory contains some scripts and information for managing +header files and includes in PostgreSQL source code. + + +include-what-you-use +==================== + +include-what-you-use (IWYU) (<https://include-what-you-use.org/>) is a +tool for finding missing or superfluous includes in C source files. + +With a compilation database (compile_commands.json, produced by +meson), it can be run like this, over the whole source tree: + + iwyu_tool.py -p build . + +(this will likely be very noisy) or for individual files: + + iwyu_tool.py -p build src/bin/psql/startup.c + +Various other invocation options are available. + +It is recommended to use at least version 0.23. Earlier versions give +advice that is incompatible with the compiler warning option +-Wmissing-variable-declarations. + +clangd (the language server) can automatically give IWYU-style advice; +see <https://clangd.llvm.org/guides/include-cleaner>. + +The source code contains some "IWYU pragma" comments to tell IWYU +about some PostgreSQL include file conventions (such as that a header +such as "postgres.h" should always be included, even if it doesn't +contribute any symbols used by the particular source file) and to +silence a few warnings that are difficult to fix. See +<https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md> +for documentation about those. + +Of course, any include changes suggested by this or other tools should +be checked and verified carefully. Note that some includes are only +used on some platforms or with some compilation options, so blindly +following the produced advice is not recommended. + + headerscheck ============ |