From ee3d760e45d7aaeb9c97522878b9ac891f423d22 Mon Sep 17 00:00:00 2001
From: Karl Wiberg <kwiberg@webrtc.org>
Date: Mon, 4 Sep 2017 14:46:47 +0200
Subject: [PATCH] Style guide: Add guideline for conditional compilation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BUG=none
NOTRY=true

Change-Id: Ibcc05462a25216e8a2f30c9fd252239ba21693d4
Reviewed-on: https://chromium-review.googlesource.com/647551
Commit-Queue: Karl Wiberg <kwiberg@webrtc.org>
Reviewed-by: Niels Möller <nisse@chromium.org>
Reviewed-by: Danil Chapovalov <danilchap@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#19704}
---
 style-guide.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/style-guide.md b/style-guide.md
index 17e9fe9797..e10b1a8ead 100644
--- a/style-guide.md
+++ b/style-guide.md
@@ -34,3 +34,35 @@ pre-dates the use of the current C++ style guide for this code base.
   surrounding code.
 * If making large changes to C code, consider converting the whole
   thing to C++ first.
+
+## Build files
+
+### Conditional compilation with the C preprocessor
+
+Avoid using the C preprocessor to conditionally enable or disable
+pieces of code. But if you can’t avoid it, introduce a gn variable,
+and then set a preprocessor constant to either 0 or 1 in the build
+targets that need it:
+
+```
+if (apm_debug_dump) {
+  defines = [ "WEBRTC_APM_DEBUG_DUMP=1" ]
+} else {
+  defines = [ "WEBRTC_APM_DEBUG_DUMP=0" ]
+}
+```
+
+In the C, C++, or Objective-C files, use `#if` when testing the flag,
+not `#ifdef` or `#if defined()`:
+
+```
+#if WEBRTC_APM_DEBUG_DUMP
+// One way.
+#else
+// Or another.
+#endif
+```
+
+When combined with the `-Wundef` compiler option, this produces
+compile time warnings if preprocessor symbols are misspelled, or used
+without corresponding build rules to set them.