aboutsummaryrefslogtreecommitdiff
path: root/docs/devel
diff options
context:
space:
mode:
authorAlex Bennée <alex.bennee@linaro.org>2023-04-24 10:22:47 +0100
committerAlex Bennée <alex.bennee@linaro.org>2023-04-27 14:58:46 +0100
commit6a0057aa22fedf4d6d39b749923e1d6046803fd8 (patch)
tree7eef56b31dae76b0933b118b9054ec561b65a26f /docs/devel
parentd035fb106f9de71ad5caaa3a615104c6793107e8 (diff)
downloadqemu-6a0057aa22fedf4d6d39b749923e1d6046803fd8.zip
qemu-6a0057aa22fedf4d6d39b749923e1d6046803fd8.tar.gz
qemu-6a0057aa22fedf4d6d39b749923e1d6046803fd8.tar.bz2
docs/devel: make a statement about includes
While not explicitly disallowing header macro abuse (because that would make us hypocrites) lets at least address some things to think about. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Juan Quintela <quintela@redhat.com> Message-Id: <20230424092249.58552-17-alex.bennee@linaro.org>
Diffstat (limited to 'docs/devel')
-rw-r--r--docs/devel/style.rst14
1 files changed, 14 insertions, 0 deletions
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 68aa776..5bc6f2f 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -300,6 +300,20 @@ putting those into qemu/typedefs.h instead of including the header.
Cyclic inclusion is forbidden.
+Generative Includes
+-------------------
+
+QEMU makes fairly extensive use of the macro pre-processor to
+instantiate multiple similar functions. While such abuse of the macro
+processor isn't discouraged it can make debugging and code navigation
+harder. You should consider carefully if the same effect can be
+achieved by making it easy for the compiler to constant fold or using
+python scripting to generate grep friendly code.
+
+If you do use template header files they should be named with the
+``.c.inc`` or ``.h.inc`` suffix to make it clear they are being
+included for expansion.
+
C types
=======