doc/extensions: document C extension use in the X server

1 files changed, 32 insertions, 0 deletions

diff --git a/doc/extensions b/doc/extensions
new file mode 100644
index 000000000..db2ba7d77
--- /dev/null
+++ b/doc/extensions
@@ -0,0 +1,32 @@
+Use of extensions throughout the X server tree
+----------------------------------------------
+
+Optional extensions:
+The server will still build if your toolchain does not support these
+extensions, although the results may not be optimal.
+
+    * _X_SENTINEL(x): member x of the passed structure must be NULL, e.g.:
+                      void parseOptions(Option *options _X_SENTINEL(0));
+                      parseOptions("foo", "bar", NULL); /* this is OK */
+                      parseOptions("foo", "bar", "baz"); /* this is not */
+                      This definition comes from Xfuncproto.h in the core
+                      protocol headers.
+    * _X_ATTRIBUTE_PRINTF(x, y): This function has printf-like semantics;
+                                 check the format string when built with
+                                 -Wformat (gcc) or similar.
+    * _X_EXPORT: this function should appear in symbol tables.
+    * _X_HIDDEN: this function should not appear in the _dynamic_ symbol
+                 table.
+    * _X_INTERNAL: like _X_HIDDEN, but attempt to ensure that this function
+                   is never called from another module.
+    * _X_INLINE: inline this functon if possible (generally obeyed unless
+                 disabling optimisations).
+    * _X_DEPRECATED: warn on use of this function.
+
+Mandatory extensions:
+The server will not build if your toolchain does not support these extensions.
+
+    * named initialisers: explicitly initialising structure members, e.g.:
+                          struct foo bar = { .baz = quux, .brian = "dog" };
+    * variadic macros: macros with a variable number of arguments, e.g.:
+                       #define DebugF(x, ...) /**/