rules: Allow all false values to disable DEBUG

While activating DEBUG requires setting it to a non-empty map,
providing information on whether and how debugg fission should be
used, we should still allow any logically false value (rather than
just null) to disable a debug build in order to make it easier for
the user to explicitly disable debugging.

Also adopt and fix the documentation strings.

2 files changed, 39 insertions, 35 deletions

diff --git a/CC/RULES b/CC/RULES
index a6c775c..a8cce27 100644
--- a/CC/RULES
+++ b/CC/RULES
@@ -110,21 +110,8 @@
       ["The architecture on which the build actions are carried out."]
     , "TARGET_ARCH": ["The architecture for which to build."]
     , "DEBUG":
-      [ "Map configuring the debug-stage, needed for local debugging."
-      , "If non-empty, debug mode is enabled."
-      , ""
-      , "The key \"USE_DEBUG_FISSION\" expects a flag which enables the debug"
-      , "fission mode, but does not add any flags. Explicitly setting it to a"
-      , "false value is needed to enable regular debug mode."
-      , "The key \"FISSION_CONFIG\" expects a map configuring debug fission."
-      , " - subkey \"USE_SPLIT_DWARF\" expects a flag that, if true, adds the"
-      , "-gsplit-dwarf compile flag."
-      , " - subkey \"DWARF_VERSION\" expects a string that adds the"
-      , "-gdwarf-<value> compile flag."
-      , " - subkey \"USE_GDB_INDEX\" expects a flag that, if true, adds the"
-      , "-Wl,--gdb-index linker flag."
-      , " - subkey \"USE_DEBUG_TYPES_SECTION\" expects a flag that, if true,"
-      , "adds the -fdebug-types-section compile flag."
+      [ "If logically true (typically, a non-empty map), use debug-related"
+      , "options, otherwise not."
       ]
     }
   , "imports":
@@ -604,8 +591,9 @@
       ]
     , "ENV": ["The environment for any action generated."]
     , "DEBUG":
-      [ "Map configuring the debug-stage, needed for local debugging."
-      , "If non-empty, debug mode is enabled."
+      [ "Either a logically false value to disable debugging, or a non-empty"
+      , "map to enable debugging. If debugging is enabled, the following values"
+      , "of the map are used."
       , ""
       , "The key \"USE_DEBUG_FISSION\" expects a flag which enables the debug"
       , "fission mode, but does not add any flags. Explicitly setting it to a"
@@ -663,6 +651,13 @@
     { "type": "let*"
     , "bindings":
       [ ["name", {"type": "join", "$1": {"type": "FIELD", "name": "name"}}]
+      , [ "DEBUG"
+        , { "type": "if"
+          , "cond": {"type": "var", "name": "DEBUG"}
+          , "then": {"type": "var", "name": "DEBUG"}
+          , "else": {"type": "empty_map"}
+          }
+        ]
       , ["pure C", {"type": "FIELD", "name": "pure C"}]
       , [ "cflags"
         , { "type": "++"
@@ -780,7 +775,7 @@
       , "with \"/\"."
       ]
     , "pure C":
-      [ "If non-empty, compile as C sources rathter than C++ sources."
+      [ "If non-empty, compile as C sources rather than C++ sources."
       , "In particular, CC is used to compile rather than CXX"
       ]
     , "private-defines":
@@ -828,8 +823,9 @@
       ]
     , "ENV": ["The environment for any action generated."]
     , "DEBUG":
-      [ "Map configuring the debug-stage, needed for local debugging."
-      , "If non-empty, debug mode is enabled."
+      [ "Either a logically false value to disable debugging, or a non-empty"
+      , "map to enable debugging. If debugging is enabled, the following values"
+      , "of the map are used."
       , ""
       , "The key \"USE_DEBUG_FISSION\" expects a flag which enables the debug"
       , "fission mode, but does not add any flags. Explicitly setting it to a"
@@ -879,6 +875,13 @@
           , "$1": {"type": "join", "$1": {"type": "FIELD", "name": "name"}}
           }
         ]
+      , [ "DEBUG"
+        , { "type": "if"
+          , "cond": {"type": "var", "name": "DEBUG"}
+          , "then": {"type": "var", "name": "DEBUG"}
+          , "else": {"type": "empty_map"}
+          }
+        ]
       , ["pure C", {"type": "FIELD", "name": "pure C"}]
       , [ "stage"
         , { "type": "join"
diff --git a/CC/proto/RULES b/CC/proto/RULES
index dc9d66c..10739d7 100644
--- a/CC/proto/RULES
+++ b/CC/proto/RULES
@@ -77,21 +77,8 @@
     , "HOST_ARCH":
       ["The architecture on which the build actions are carried out."]
     , "DEBUG":
-      [ "Map configuring the debug-stage, needed for local debugging."
-      , "If non-empty, debug mode is enabled."
-      , ""
-      , "The key \"USE_DEBUG_FISSION\" expects a flag which enables debug"
-      , "fission, but does not add any flags. Explicitly setting it to a false"
-      , "value is needed to enable regular debug mode."
-      , "The key \"FISSION_CONFIG\" expects a map configuring debug fission."
-      , " - subkey \"USE_SPLIT_DWARF\" expects a flag that, if true, adds the"
-      , "-gsplit-dwarf compile flag."
-      , " - subkey \"DWARF_VERSION\" expects a string that adds the"
-      , "-gdwarf-<value> compile flag."
-      , " - subkey \"USE_GDB_INDEX\" expects a flag that, if true, adds the"
-      , "-Wl,--gdb-index linker flag."
-      , " - subkey \"USE_DEBUG_TYPES_SECTION\" expects a flag that, if true,"
-      , "adds the -fdebug-types-section compile flag."
+      [ "If logically true (typically, a non-empty map), use debug-related"
+      , "options, otherwise not."
       ]
     }
   , "imports":
@@ -332,6 +319,13 @@
     { "type": "let*"
     , "bindings":
       [ ["name", {"type": "join", "$1": {"type": "FIELD", "name": "name"}}]
+      , [ "DEBUG"
+        , { "type": "if"
+          , "cond": {"type": "var", "name": "DEBUG"}
+          , "then": {"type": "var", "name": "DEBUG"}
+          , "else": {"type": "empty_map"}
+          }
+        ]
       , [ "stage"
         , { "type": "join"
           , "separator": "/"
@@ -364,6 +358,13 @@
     , "bindings":
       [ ["service support", true]
       , ["name", {"type": "join", "$1": {"type": "FIELD", "name": "name"}}]
+      , [ "DEBUG"
+        , { "type": "if"
+          , "cond": {"type": "var", "name": "DEBUG"}
+          , "then": {"type": "var", "name": "DEBUG"}
+          , "else": {"type": "empty_map"}
+          }
+        ]
       , [ "stage"
         , { "type": "join"
           , "separator": "/"