From d210590d4d8d859d1cd0960c0573391a9bf5d9a5 Mon Sep 17 00:00:00 2001
From: Stefan Kerkmann <karlk90@pm.me>
Date: Sun, 1 Sep 2024 19:54:53 +0200
Subject: [PATCH] [Maintenance] builddefs: common_rules: overhaul debug
 information generation (#24352)

builddefs: common_rules: overhaul debug information generation

Debug information is always generated while compiling a binary, but
debugging is not the main use-case for the majority of users. Thus the
new default is to explicitly require them with `DEBUG_ENABLE=yes`. The
same is true for linker map files which are gated by the same flag.

As we target the gcc compiler and debug with the gdb debugger we can
specify the ggdb3 flag in the most verbose to get macro expansion.

Signed-off-by: Stefan Kerkmann <karlk90@pm.me>
---
 builddefs/common_rules.mk | 39 ++++++++++++++++-----------------------
 docs/other_vscode.md      |  5 +++--
 2 files changed, 19 insertions(+), 25 deletions(-)

diff --git a/builddefs/common_rules.mk b/builddefs/common_rules.mk
index cfd261737c0..cc7d5a76d3f 100644
--- a/builddefs/common_rules.mk
+++ b/builddefs/common_rules.mk
@@ -43,6 +43,18 @@ ifneq ($(USE_CCACHE),no)
     CC_PREFIX ?= ccache
 endif
 
+#---------------- Debug Options ----------------
+
+DEBUG_ENABLE ?= no
+ifeq ($(strip $(DEBUG_ENABLE)),yes)
+	CFLAGS 	 += -ggdb3
+	CXXFLAGS += -ggdb3
+	ASFLAGS  += -ggdb3
+# Create a map file when debugging
+	LDFLAGS  += -Wl,-Map=$(BUILD_DIR)/$(TARGET).map,--cref
+endif
+
+
 #---------------- C Compiler Options ----------------
 
 ifeq ($(strip $(LTO_ENABLE)), yes)
@@ -54,14 +66,6 @@ ifeq ($(strip $(LTO_ENABLE)), yes)
     CDEFS += -DLTO_ENABLE
 endif
 
-DEBUG_ENABLE ?= yes
-ifeq ($(strip $(SKIP_DEBUG_INFO)),yes)
-  DEBUG_ENABLE=no
-endif
-
-ifeq ($(strip $(DEBUG_ENABLE)),yes)
-  CFLAGS += -g$(DEBUG)
-endif
 CFLAGS += $(CDEFS)
 CFLAGS += -O$(OPT)
 # add color
@@ -83,9 +87,6 @@ CFLAGS += -fcommon
 
 #---------------- C++ Compiler Options ----------------
 
-ifeq ($(strip $(DEBUG_ENABLE)),yes)
-  CXXFLAGS += -g$(DEBUG)
-endif
 CXXFLAGS += $(CXXDEFS)
 CXXFLAGS += -O$(OPT)
 # to suppress "warning: only initialized variables can be placed into program memory area"
@@ -106,14 +107,10 @@ endif
 
 #---------------- Linker Options ----------------
 
-CREATE_MAP ?= yes
-ifeq ($(CREATE_MAP),yes)
-	LDFLAGS += -Wl,-Map=$(BUILD_DIR)/$(TARGET).map,--cref
-endif
 ifeq ($(VERBOSE_LD_CMD),yes)
 	LDFLAGS += -v
 endif
-#LDFLAGS += -Wl,--relax
+
 LDFLAGS += $(EXTMEMOPTS)
 LDFLAGS += $(patsubst %,-L%,$(EXTRALIBDIRS))
 LDFLAGS += -lm
@@ -126,15 +123,11 @@ ADHLNS_ENABLE ?= no
 ifeq ($(ADHLNS_ENABLE),yes)
   # Avoid "Options to '-Xassembler' do not match" - only specify assembler options at LTO link time
   ifeq ($(strip $(LTO_ENABLE)), yes)
-    LDFLAGS += -Wa,-adhlns=$(BUILD_DIR)/$(TARGET).lst
+    LDFLAGS  += -Wa,-adhlns=$(BUILD_DIR)/$(TARGET).lst
   else
-    CFLAGS += -Wa,-adhlns=$(@:%.o=%.lst)
+    CFLAGS   += -Wa,-adhlns=$(@:%.o=%.lst)
     CXXFLAGS += -Wa,-adhlns=$(@:%.o=%.lst)
-    ifeq ($(strip $(DEBUG_ENABLE)),yes)
-      ASFLAGS = -Wa,-adhlns=$(@:%.o=%.lst),-gstabs,--listing-cont-lines=100
-    else
-      ASFLAGS = -Wa,-adhlns=$(@:%.o=%.lst),--listing-cont-lines=100
-    endif
+	ASFLAGS  += -Wa,-adhlns=$(@:%.o=%.lst),--listing-cont-lines=100
   endif
 endif
 
diff --git a/docs/other_vscode.md b/docs/other_vscode.md
index 31208d8f3bf..ab2b23e96b4 100644
--- a/docs/other_vscode.md
+++ b/docs/other_vscode.md
@@ -177,12 +177,13 @@ You'll need to perform some modifications to the file above in order to target y
 Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings: ![VSCode Settings](https://i.imgur.com/EGrPM1L.png)
 :::
 
-Optionally, the following modifications should also be made to the keyboard's `rules.mk` file to disable optimisations -- not strictly required but will ensure breakpoints and variable viewing works correctly:
+The following modifications must be made to the keyboard's `rules.mk` file to enable debug information and disable optimisations -- this will ensure breakpoints and variable viewing works correctly:
 ```makefile
+# Enable debug information in the final binaries
+DEBUG_ENABLE = yes
 # Disable optimisations for debugging purposes
 LTO_ENABLE = no
 OPT = g
-DEBUG = 3
 ```
 
 At this point, you should build and flash your firmware through normal methods (`qmk compile ...` and `qmk flash ...`).