[RFC PATCH] docs: add some details about compilation units to coding style

[Alex Bennée]

The build-system documentation remains the canonical description of
how the whole build system goes together. However we should at least
reference the fact that we use conditional compilation in the coding
style document which I assume is the first document a potential
contributor actually reads (if at all).

[AJB: should we make more explicit reference to NEED_CPU?]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Philippe Mathieu-Daudé <philmd@linaro.org>
Cc: Alessandro Di Federico <ale@rev.ng>
---
 docs/devel/build-system.rst |  1 +
 docs/devel/style.rst        | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 1894721743..eb50578f8b 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -107,6 +107,7 @@ developers in checking for system features:
    Run pkg-config passing it $ARGS. If QEMU is doing a static build,
    then --static will be automatically added to $ARGS
 
+.. _meson:
 
 Stage 2: Meson
 ==============
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 7ddd42b6c2..36c7868854 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -607,6 +607,42 @@ are still some caveats to beware of
 QEMU Specific Idioms
 ********************
 
+Module and file layout
+======================
+
+The QEMU project is a large and complex one where individual files can
+be re-built multiple times for various final binaries. This is often
+accomplished through heavy use of #define values to control
+conditional compilation. However care should be taken to avoid
+introducing files that are compiled for every target for trivial
+differences.
+
+Some general rules of thumb:
+
+  * CONFIG_* flags come from either host or target specific defines.
+    You can see where they come from by comparing config-host.h and
+    $TARGET-config.target.h
+
+  * #ifdef CONFIG_USER_ONLY/CONFIG_SOFTMMU should only be added to
+    files that already use them to compile multiple versions.
+
+  * Try and avoid target_* specific typedefs in common code
+
+See the build system :ref:`meson<meson>` documentation for the details of how
+the various compilation units are handled.
+
+"Templates" and generated code
+==============================
+
+We make heavy use of C's macro facilities combined with multiple
+inclusion to generate code. This tends to use header files (usually
+with the .inc suffix) with different #define'd constants. While the
+use of C11's _Generic keyword has improved things a bit this technique
+is still best suited to repetitive boiler plate code. If more complex
+code generation is required consider using a script to generate it,
+see for example the decodetree and qapi header scripts.
+
+
 Error handling and reporting
 ============================
 
-- 
2.34.1