IWYU widely useful pragmas

petere · petere · commit 74938d132093 · 2025-01-15T18:57:53.000+01:00
Add various widely useful "IWYU pragma" annotations, such as - Common header files such as c.h, postgres.h should be "always_keep". - System headers included in c.h, postgres.h etc. should be considered "export". - Some portability headers such as getopt_long.h should be "always_keep", so they are not considered superfluous on some platforms. - Certain system headers included from portability headers should be considered "export" because the purpose of the portability header is to wrap them. - Superfluous includes marked as "for backward compatibility" get a formal IWYU annotation. - Generated header included in utils/syscache.h is marked exported. This is a very commonly used include and this avoids lots of complaints. Discussion: https://www.postgresql.org/message-id/flat/9395d484-eff4-47c2-b276-8e228526c8ae@eisentraut.org
diff --git a/src/include/c.h b/src/include/c.h
@@ -16,6 +16,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 /*
  *----------------------------------------------------------------
  *	 TABLE OF CONTENTS
@@ -46,6 +47,8 @@
 #ifndef C_H
 #define C_H
 
+/* IWYU pragma: begin_exports */
+
 /*
  * These headers must be included before any system headers, because on some
  * platforms they affect the behavior of the system headers (for example, by
@@ -1327,4 +1330,6 @@ typedef intptr_t sigjmp_buf[5];
 /* /port compatibility functions */
 #include "port.h"
 
+/* IWYU pragma: end_exports */
+
 #endif							/* C_H */
diff --git a/src/include/getopt_long.h b/src/include/getopt_long.h
@@ -6,10 +6,11 @@
  *
  * src/include/getopt_long.h
  */
+/* IWYU pragma: always_keep */
 #ifndef GETOPT_LONG_H
 #define GETOPT_LONG_H
 
-#include "pg_getopt.h"
+#include "pg_getopt.h"			/* IWYU pragma: export */
 
 #ifndef HAVE_STRUCT_OPTION
 
diff --git a/src/include/pg_getopt.h b/src/include/pg_getopt.h
@@ -15,15 +15,16 @@
  *
  * src/include/pg_getopt.h
  */
+/* IWYU pragma: always_keep */
 #ifndef PG_GETOPT_H
 #define PG_GETOPT_H
 
 /* POSIX says getopt() is provided by unistd.h */
-#include <unistd.h>
+#include <unistd.h>				/* IWYU pragma: export */
 
 /* rely on the system's getopt.h if present */
 #ifdef HAVE_GETOPT_H
-#include <getopt.h>
+#include <getopt.h>				/* IWYU pragma: export */
 #endif
 
 /*
diff --git a/src/include/pg_trace.h b/src/include/pg_trace.h
@@ -12,6 +12,6 @@
 #ifndef PG_TRACE_H
 #define PG_TRACE_H
 
-#include "utils/probes.h"
+#include "utils/probes.h"		/* IWYU pragma: export */
 
 #endif							/* PG_TRACE_H */
diff --git a/src/include/pgstat.h b/src/include/pgstat.h
@@ -16,11 +16,11 @@
 #include "portability/instr_time.h"
 #include "postmaster/pgarch.h"	/* for MAX_XFN_CHARS */
 #include "replication/conflict.h"
-#include "utils/backend_progress.h" /* for backward compatibility */
-#include "utils/backend_status.h"	/* for backward compatibility */
+#include "utils/backend_progress.h" /* for backward compatibility */	/* IWYU pragma: export */
+#include "utils/backend_status.h"	/* for backward compatibility */	/* IWYU pragma: export */
 #include "utils/pgstat_kind.h"
 #include "utils/relcache.h"
-#include "utils/wait_event.h"	/* for backward compatibility */
+#include "utils/wait_event.h"	/* for backward compatibility */	/* IWYU pragma: export */
 
 
 /* ----------
diff --git a/src/include/port/pg_iovec.h b/src/include/port/pg_iovec.h
@@ -16,7 +16,7 @@
 #ifndef WIN32
 
 #include <limits.h>
-#include <sys/uio.h>
+#include <sys/uio.h>			/* IWYU pragma: export */
 #include <unistd.h>
 
 #else
diff --git a/src/include/port/pg_pthread.h b/src/include/port/pg_pthread.h
@@ -13,7 +13,7 @@
 #ifndef PG_PTHREAD_H
 #define PG_PTHREAD_H
 
-#include <pthread.h>
+#include <pthread.h>			/* IWYU pragma: export */
 
 #ifndef HAVE_PTHREAD_BARRIER_WAIT
 
diff --git a/src/include/postgres.h b/src/include/postgres.h
@@ -14,6 +14,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 /*
  *----------------------------------------------------------------
  *	 TABLE OF CONTENTS
@@ -42,10 +43,14 @@
 #ifndef POSTGRES_H
 #define POSTGRES_H
 
+/* IWYU pragma: begin_exports */
+
 #include "c.h"
 #include "utils/elog.h"
 #include "utils/palloc.h"
 
+/* IWYU pragma: end_exports */
+
 /* ----------------------------------------------------------------
  *				Section 1:	Datum type + support functions
  * ----------------------------------------------------------------
diff --git a/src/include/postgres_ext.h b/src/include/postgres_ext.h
@@ -19,6 +19,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 
 #ifndef POSTGRES_EXT_H
 #define POSTGRES_EXT_H
diff --git a/src/include/postgres_fe.h b/src/include/postgres_fe.h
@@ -15,15 +15,20 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 #ifndef POSTGRES_FE_H
 #define POSTGRES_FE_H
 
 #ifndef FRONTEND
 #define FRONTEND 1
 #endif
 
+/* IWYU pragma: begin_exports */
+
 #include "c.h"
 
 #include "common/fe_memutils.h"
 
+/* IWYU pragma: end_exports */
+
 #endif							/* POSTGRES_FE_H */
diff --git a/src/include/utils/syscache.h b/src/include/utils/syscache.h
@@ -20,7 +20,7 @@
 #include "access/htup.h"
 /* we intentionally do not include utils/catcache.h here */
 
-#include "catalog/syscache_ids.h"
+#include "catalog/syscache_ids.h"	/* IWYU pragma: export */
 
 extern void InitCatalogCache(void);
 extern void InitCatalogCachePhase2(void);
diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h
@@ -44,13 +44,15 @@
 #include "fe-auth-sasl.h"
 #include "pqexpbuffer.h"
 
+/* IWYU pragma: begin_exports */
 #ifdef ENABLE_GSS
 #if defined(HAVE_GSSAPI_H)
 #include <gssapi.h>
 #else
 #include <gssapi/gssapi.h>
 #endif
 #endif
+/* IWYU pragma: end_exports */
 
 #ifdef ENABLE_SSPI
 #define SECURITY_WIN32

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`*`
`20`	`20`	`*-------------------------------------------------------------------------`
`21`	`21`	`*/`
	`22`	`+/* IWYU pragma: always_keep */`
`22`	`23`
`23`	`24`	`#ifndef POSTGRES_EXT_H`
`24`	`25`	`#define POSTGRES_EXT_H`