Add debug support for build.opt

Add support to have different build option comment blocks for debug and production builds. Updated example esp8266/HwdtStackDump to use build.opt
esp8266 · mcspr · Aug 4, 2022 · Jul 1, 2022 · Jul 25, 2022 · Jul 26, 2022
commit 4941e126921f7472af43ed3efe2faa14e8ca2b1c
diff --git a/cores/esp8266/hwdt_app_entry.cpp b/cores/esp8266/hwdt_app_entry.cpp
@@ -180,7 +180,9 @@
  * tool performing hardware reset and exiting, then the serial monitor
  * re-engaging. This is not an issue that needs to be addressed here.
  */
- #define DEBUG_ESP_HWDT_PRINT_GREETING
+ #ifndef DEBUG_ESP_HWDT_PRINT_GREETING
+ #define DEBUG_ESP_HWDT_PRINT_GREETING (1)
+ #endif
 
 
 /*
@@ -995,7 +997,7 @@ STATIC void IRAM_MAYBE handle_hwdt(void) {
     }
 #endif
 
-#if defined(DEBUG_ESP_HWDT_PRINT_GREETING)
+#if DEBUG_ESP_HWDT_PRINT_GREETING
     ETS_PRINTF("\n\nHardware WDT Stack Dump - enabled\n\n");
 #else
     ETS_PRINTF("\n\n");

diff --git a/doc/faq/a06-global-build-options.rst b/doc/faq/a06-global-build-options.rst
@@ -92,6 +92,72 @@ Global ``.h`` file: ``LowWatermark.ino.globals.h``
 
    #endif
 
+Separate production and debug build options
+===========================================
+
+If your production and debug build option requirements are different,
+you can specify ``mkbuildoptglobals.extra_flags={build.debug_port}`` in
+``platform.local.txt``. With this addition, you have two “C” comment
+blocks that can hold build options. One for debug options and one for
+production options. For debug build options, use a “C” block comment
+starting with ``/*@create-file:build.opt:debug@``. Make your selection
+by selecting or disabling the Arduino->Tools->Debug port.
+
+Options common to both debug and production builds must be included in
+both block comments. It is possible to have a sketch that only uses the
+debug build options, and the platform defaults for production and visa
+versa.
+
+Note, adding this change to ``platform.local.txt`` will apply to all old
+sketches. An old “sketch” with only the “C” block comment starting with
+``/*@create-file:build.opt@`` would not use a ``build.opt`` file for the
+debug case. Update old sketches as needed.
+
+Updated Global ``.h`` file: ``LowWatermark.ino.globals.h``
+
+.. code:: cpp
+
+   /*@create-file:build.opt:debug@
+   // Debug build options
+   -DMYTITLE1="\"Running on \""
+   -DUMM_STATS_FULL=1
+
+   //-fanalyzer
+
+   // Removing the optimization for "sibling and tail recursive calls"  will clear
+   // up some gaps in the stack decoder report. Preserves stack frames created at
+   // each level as you call down to the next.
+   -fno-optimize-sibling-calls
+   */
+
+   /*@create-file:build.opt@
+   // Production build options
+   -DMYTITLE1="\"Running on \""
+   -DUMM_STATS_FULL=1
+   -O3
+   */
+
+   #ifndef LOWWATERMARK_INO_GLOBALS_H
+   #define LOWWATERMARK_INO_GLOBALS_H
+
+   #if defined(__cplusplus)
+   #define MYTITLE2 "Empty"
+   #endif
+
+   #if !defined(__cplusplus) && !defined(__ASSEMBLER__)
+   #define MYTITLE2 "Full"
+   #endif
+
+   #ifdef ESP_DEBUG_PORT
+   // Global Debug defines
+   // ...
+   #else
+   // Global Production defines
+   // ...
+   #endif
+
+   #endif
+
 Aggressively cache compiled core
 ================================
 

diff --git a/libraries/esp8266/examples/HwdtStackDump/HwdtStackDump.ino b/libraries/esp8266/examples/HwdtStackDump/HwdtStackDump.ino
@@ -47,25 +47,27 @@ extern "C" {
 ////////////////////////////////////////////////////////////////////
 
 void setup(void) {
-  WiFi.persistent(false);  // w/o this a flash write occurs at every boot
-  WiFi.mode(WIFI_OFF);
   Serial.begin(115200);
   delay(20);  // This delay helps when using the 'Modified Serial monitor' otherwise it is not needed.
   Serial.println();
   Serial.println();
   Serial.println(F("The Hardware Watchdog Timer Demo is starting ..."));
   Serial.println();
 
+#ifdef DEMO_THUNK
   // This allows us to test dumping a BearSSL stack after HWDT.
   stack_thunk_add_ref();
   thunk_ets_uart_printf("Using Thunk Stack to print this line.\n\n");
+#endif
 
+#ifdef DEMO_WIFI
   // We don't need this for this example; however, starting WiFi uses a little
   // more of the SYS stack.
   WiFi.mode(WIFI_STA);
   WiFi.begin(ssid, password);
   Serial.println(F("A WiFi connection attempt has been started."));
   Serial.println();
+#endif
 
   // #define DEMO_NOEXTRA4K
 #ifdef DEMO_NOEXTRA4K

diff --git a/libraries/esp8266/examples/HwdtStackDump/HwdtStackDump.ino.globals.h b/libraries/esp8266/examples/HwdtStackDump/HwdtStackDump.ino.globals.h
@@ -0,0 +1,51 @@
+/*@create-file:build.opt:debug@
+// For this block to work, you must have
+// `mkbuildoptglobals.extra_flags={build.debug_port}` in `platform.local.txt`
+// Or move contents to the block with the signature "@create-file:build.opt@"
+
+
+// Removing the optimization for "sibling and tail recursive calls"  will clear
+// up some gaps in the stack decoder report. Preserves stack frames created at
+// each level as you call down to the next.
+-fno-optimize-sibling-calls
+
+
+// Adds a pointer toward the end of the stack frame that points to the beginning
+// of the stack frame. The stack dump will annotate the line where it occurs
+// with a `<` mark.
+-fno-omit-frame-pointer
+
+
+// Options for HWDT Stack Dump (hwdt_app_entry.cpp)
+
+// Alter the UART serial speed used for printing the Hardware WDT reset stack
+// dump. Without this option on an HWDT reset, the existing default speed of
+// 115200 bps will be used. If you are using this default speed, you can skip
+// this option. Note this option only changes the speed while the stack dump is
+// printing. Prior settings are restored.
+// -DDEBUG_ESP_HWDT_UART_SPEED=19200
+// -DDEBUG_ESP_HWDT_UART_SPEED=74880
+// -DDEBUG_ESP_HWDT_UART_SPEED=115200
+// -DDEBUG_ESP_HWDT_UART_SPEED=230400
+
+// HWDT Stack Dump defaults to print a simple introduction to let you know the
+// tool is active and in the build. At power-on, this may not be viewable on
+// some devices. Use the DEBUG_ESP_HWDT_UART_SPEED option above to improve.
+// Or uncomment line below to turn off greeting
+// -DDEBUG_ESP_HWDT_PRINT_GREETING=0
+
+// Demos
+-DDEMO_THUNK=1
+// -DDEMO_NOEXTRA4K=1
+-DDEMO_WIFI=1
+*/
+
+/*@create-file:build.opt@
+// -fno-optimize-sibling-calls
+// -fno-omit-frame-pointer
+
+// Demos
+-DDEMO_THUNK=1
+// -DDEMO_NOEXTRA4K=1
+-DDEMO_WIFI=1
+*/
diff --git a/tools/mkbuildoptglobals.py b/tools/mkbuildoptglobals.py
@@ -680,6 +680,7 @@ def parse_args():
     parser.add_argument('source_globals_h_fqfn', help="Source FQFN Sketch.ino.globals.h")
     parser.add_argument('commonhfile_fqfn', help="Core Source FQFN CommonHFile.h")
     parser.add_argument('--debug', action='store_true', required=False, default=False)
+    parser.add_argument('-DDEBUG_ESP_PORT', nargs='?', action='store', const="", default="", help='Add mkbuildoptglobals.extra_flags={build.debug_port} to platform.local.txt')
     parser.add_argument('--ci', action='store_true', required=False, default=False)
     group = parser.add_mutually_exclusive_group(required=False)
     group.add_argument('--cache_core', action='store_true', default=None, help='Assume a "compiler.cache_core" value of true')
@@ -721,6 +722,12 @@ def main():
     print_dbg(f"globals_name:           {globals_name}")
     print_dbg(f"build_path_core:        {build_path_core}")
     print_dbg(f"globals_h_fqfn:         {globals_h_fqfn}")
+    print_dbg(f"DDEBUG_ESP_PORT:        {args.DDEBUG_ESP_PORT}")
+
+    if len(args.DDEBUG_ESP_PORT):
+        build_opt_signature = build_opt_signature[:-1] + ":debug@"
+
+    print_dbg(f"build_opt_signature:    {build_opt_signature}")
 
     if args.ci:
         # Requires CommonHFile.h to never be checked in.