Add debug support for build.opt (#8637)

Add support to have different build option comment blocks
for debug and production builds.

Updated example esp8266/HwdtStackDump to use build.opt

Author: mhightower83

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");

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,
+adding ``mkbuildoptglobals.extra_flags={build.debug_port}`` to
+``platform.local.txt`` will create separate build option groups for
+debugging and production. For the production build option group, the “C”
+block comment starts with ``/*@create-file:build.opt@``, as previously
+defined. For the debugging group, the new “C” block comment starts with
+``/*@create-file:build.opt:debug@``. You make your group selection
+through “Arduino->Tools->Debug port” by selecting or disabling the
+“Debug port.”
+
+Options common to both debug and production builds must be included in
+both groups. Neither of the groups is required. You may also omit either
+or both.
+
+Reminder with this change, any old “sketch” with only a “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" may fill
+   // in some gaps in the stack decoder report. Preserves the 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 DEBUG_ESP_PORT
+   // Global Debug defines
+   // ...
+   #else
+   // Global Production defines
+   // ...
+   #endif
+
+   #endif
+
 Aggressively cache compiled core
 ================================
 

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

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
+*/

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.