| 1 |
src/tools/pginclude/README |
| 2 |
|
| 3 |
This directory contains some scripts and information for managing |
| 4 |
header files and includes in PostgreSQL source code. |
| 5 |
|
| 6 |
|
| 7 |
include-what-you-use |
| 8 |
==================== |
| 9 |
|
| 10 |
include-what-you-use (IWYU) (<https://include-what-you-use.org/>) is a |
| 11 |
tool for finding missing or superfluous includes in C source files. |
| 12 |
|
| 13 |
With a compilation database (compile_commands.json, produced by |
| 14 |
meson), it can be run like this, over the whole source tree: |
| 15 |
|
| 16 |
iwyu_tool.py -p build . |
| 17 |
|
| 18 |
(this will likely be very noisy) or for individual files: |
| 19 |
|
| 20 |
iwyu_tool.py -p build src/bin/psql/startup.c |
| 21 |
|
| 22 |
Various other invocation options are available. |
| 23 |
|
| 24 |
It is recommended to use at least version 0.23. Earlier versions give |
| 25 |
advice that is incompatible with the compiler warning option |
| 26 |
-Wmissing-variable-declarations. |
| 27 |
|
| 28 |
clangd (the language server) can automatically give IWYU-style advice; |
| 29 |
see <https://clangd.llvm.org/guides/include-cleaner>. |
| 30 |
|
| 31 |
The source code contains some "IWYU pragma" comments to tell IWYU |
| 32 |
about some PostgreSQL include file conventions (such as that a header |
| 33 |
such as "postgres.h" should always be included, even if it doesn't |
| 34 |
contribute any symbols used by the particular source file) and to |
| 35 |
silence a few warnings that are difficult to fix. See |
| 36 |
<https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md> |
| 37 |
for documentation about those. |
| 38 |
|
| 39 |
Of course, any include changes suggested by this or other tools should |
| 40 |
be checked and verified carefully. Note that some includes are only |
| 41 |
used on some platforms or with some compilation options, so blindly |
| 42 |
following the produced advice is not recommended. |
| 43 |
|
| 44 |
|
| 45 |
headerscheck |
| 46 |
============ |
| 47 |
|
| 48 |
This script can be run to verify that all Postgres include files meet |
| 49 |
the project convention that they will compile "standalone", that is |
| 50 |
with no prerequisite headers other than postgres.h (or postgres_fe.h |
| 51 |
or c.h, as appropriate). |
| 52 |
|
| 53 |
A small number of header files are exempted from this requirement, |
| 54 |
and are skipped by the headerscheck script. |
| 55 |
|
| 56 |
The easy way to run the script is to say "make -s headerscheck" in |
| 57 |
the top-level build directory after completing a build. You should |
| 58 |
have included "--with-perl --with-python" in your configure options, |
| 59 |
else you're likely to get errors about related headers not being found. |
| 60 |
|
| 61 |
A limitation of the current script is that it doesn't know exactly which |
| 62 |
headers are for frontend or backend; when in doubt it uses postgres.h as |
| 63 |
prerequisite, even if postgres_fe.h or c.h would be more appropriate. |
| 64 |
Also note that the contents of macros are not checked; this is intentional. |
| 65 |
|
| 66 |
|
| 67 |
headerscheck --cplusplus |
| 68 |
======================== |
| 69 |
|
| 70 |
The headerscheck in --cplusplus mode can be run to verify that all |
| 71 |
Postgres include files meet the project convention that they will |
| 72 |
compile as C++ code. Although the project's coding language is C, |
| 73 |
some people write extensions in C++, so it's helpful for include files |
| 74 |
to be C++-clean. |
| 75 |
|
| 76 |
A small number of header files are exempted from this requirement, |
| 77 |
and are skipped by the script in the --cplusplus mode. |
| 78 |
|
| 79 |
The easy way to run the script is to say "make -s cpluspluscheck" in |
| 80 |
the top-level build directory after completing a build. You should |
| 81 |
have included "--with-perl --with-python" in your configure options, |
| 82 |
else you're likely to get errors about related headers not being found. |
| 83 |
|
| 84 |
If you are using a non-g++-compatible C++ compiler, you may need to |
| 85 |
override the script's CXXFLAGS setting by setting a suitable environment |
| 86 |
value. |
| 87 |
|
| 88 |
A limitation of the current script is that it doesn't know exactly which |
| 89 |
headers are for frontend or backend; when in doubt it uses postgres.h as |
| 90 |
prerequisite, even if postgres_fe.h or c.h would be more appropriate. |
| 91 |
Also note that the contents of macros are not checked; this is intentional. |