From 44512e7c952f798c9912476ac5fc2132493f9af7 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut
Date: Wed, 15 Jan 2025 18:57:53 +0100
Subject: 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
---
 src/tools/pginclude/README | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'src/tools')

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
 ============
 
-- 
cgit v1.2.3