[Qemu-devel] [PATCH v2] HACKING: document #include order

[Qemu-devel] [PATCH v2] HACKING: document #include order

[Stefan Hajnoczi]

It was not obvious to me why "qemu/osdep.h" must be the first #include.
This documents the rationale and the overall #include order.

Cc: Fam Zheng <famz@redhat.com>
Cc: Markus Armbruster <armbru@redhat.com>
Cc: Eric Blake <eblake@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 HACKING | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/HACKING b/HACKING
index 20a9101..4125c97 100644
--- a/HACKING
+++ b/HACKING
@@ -1,10 +1,28 @@
 1. Preprocessor
 
+1.1. Variadic macros
+
 For variadic macros, stick with this C99-like syntax:
 
 #define DPRINTF(fmt, ...)                                       \
     do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0)
 
+1.2. Include directives
+
+Order include directives as follows:
+
+#include "qemu/osdep.h"  /* Always first... */
+#include <...>           /* then system headers... */
+#include "..."           /* and finally QEMU headers. */
+
+The "qemu/osdep.h" header contains preprocessor macros that affect the behavior
+of core system headers like <stdint.h>.  It must be the first include so that
+core system headers included by external libraries get the preprocessor macros
+that QEMU depends on.
+
+Do not include "qemu/osdep.h" from header files since the .c file will have
+already included it.
+
 2. C types
 
 It should be common sense to use the right type, but we have collected
-- 
2.7.4

Re: [Qemu-devel] [PATCH v2] HACKING: document #include order

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 603 bytes --]

On 11/16/2016 08:39 AM, Stefan Hajnoczi wrote:
> It was not obvious to me why "qemu/osdep.h" must be the first #include.
> This documents the rationale and the overall #include order.
> 
> Cc: Fam Zheng <famz@redhat.com>
> Cc: Markus Armbruster <armbru@redhat.com>
> Cc: Eric Blake <eblake@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  HACKING | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH v2] HACKING: document #include order

[Markus Armbruster]

Stefan Hajnoczi <stefanha@redhat.com> writes:

> It was not obvious to me why "qemu/osdep.h" must be the first #include.
> This documents the rationale and the overall #include order.
>
> Cc: Fam Zheng <famz@redhat.com>
> Cc: Markus Armbruster <armbru@redhat.com>
> Cc: Eric Blake <eblake@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  HACKING | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>
> diff --git a/HACKING b/HACKING
> index 20a9101..4125c97 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -1,10 +1,28 @@
>  1. Preprocessor
>  
> +1.1. Variadic macros
> +
>  For variadic macros, stick with this C99-like syntax:
>  
>  #define DPRINTF(fmt, ...)                                       \
>      do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0)
>  
> +1.2. Include directives
> +
> +Order include directives as follows:
> +
> +#include "qemu/osdep.h"  /* Always first... */
> +#include <...>           /* then system headers... */
> +#include "..."           /* and finally QEMU headers. */
> +
> +The "qemu/osdep.h" header contains preprocessor macros that affect the behavior
> +of core system headers like <stdint.h>.  It must be the first include so that
> +core system headers included by external libraries get the preprocessor macros
> +that QEMU depends on.
> +
> +Do not include "qemu/osdep.h" from header files since the .c file will have
> +already included it.
> +
>  2. C types
>  
>  It should be common sense to use the right type, but we have collected

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [Qemu-devel] [PATCH v2] HACKING: document #include order

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 644 bytes --]

On Wed, Nov 16, 2016 at 02:39:21PM +0000, Stefan Hajnoczi wrote:
> It was not obvious to me why "qemu/osdep.h" must be the first #include.
> This documents the rationale and the overall #include order.
> 
> Cc: Fam Zheng <famz@redhat.com>
> Cc: Markus Armbruster <armbru@redhat.com>
> Cc: Eric Blake <eblake@redhat.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  HACKING | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)

Thanks, applied to my block-next tree:
https://github.com/stefanha/qemu/commits/block-next

(Not sure there is a better home for this but it will go into QEMU 2.9.)

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]