From 2417ef9b70713e4a2a1f1dc94273c74e0d4794ec Mon Sep 17 00:00:00 2001
From: Brian Park <brian@xparks.net>
Date: Thu, 24 Feb 2022 13:37:09 -0800
Subject: [PATCH] README.md: Add notes about debuggers, sanitizers, and
 valgrind

---
 CHANGELOG.md |  2 ++
 README.md    | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b65df0..eb1585f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@
         * This benchmark shows that `seek()` causes significant performance
           loss, even if the `seek()` offset is identical to the internal cursor,
           so might be expected to be optimized away.
+    * Add notes about [Debugging](README.md#Debugging) tools and options
+      under a Unix environment.
 * 1.2.2 (2022-02-02)
     * Add a `using Print::write` statement in `StdioSerial.h` to
       pull in all other overloaded `write()` methods from the parent `Print`
diff --git a/README.md b/README.md
index 7f6a55e..264ccb7 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,8 @@ The disadvantages are:
     * [Alternate Arduino Core](#AlternateArduinoCore)
     * [PlatformIO](#PlatformIO)
     * [Command Line Flags and Arguments](#CommandLineFlagsAndArguments)
+    * [Debugging](#Debugging)
+        * [Valgrind](#Valgrind)
 * [Supported Arduino Features](#SupportedArduinoFeatures)
     * [Arduino Functions](#ArduinoFunctions)
     * [Serial Port Emulation](#SerialPortEmulation)
@@ -646,6 +648,52 @@ Usage: ./CommandLine.out [--help|-h] [-s] [--include word] [--] [words ...]
 A more advanced example can be seen in
 [AUnit/TestRunner.cpp](https://github.com/bxparks/AUnit/blob/develop/src/aunit/TestRunner.cpp).
 
+<a name="Debugging"></a>
+### Debugging
+
+A huge benefit of compiling Arduino programs using EpoxyDuino is that all the
+debugging tools in a Unix environment become automatically available. For
+example:
+
+* External Tools
+    * [Valgrind](https://valgrind.org/docs/manual/quick-start.html)
+    * [GDB Debugger](https://www.sourceware.org/gdb/)
+* Compiler Options
+    * [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) (ASan)
+    * [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer)
+      (MSan)
+    * [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) (UBSan)
+
+I am not an expert on any of these sanitizers, and I have not enabled them by
+default in the `EpoxyDuino.mk` file. But you have the capability to add them to
+your `Makefile` through the `CXXFLAGS` variable.
+
+Below are some things that I have found useful in my own limited experience.
+
+<a name="Valgrind"></a>
+#### Valgrind
+
+I have found the [Valgrind](https://valgrind.org/docs/manual/quick-start.html)
+quite helpful in tracking down Segmentation Fault crashes. Here is a quick
+start:
+
+1. Compile your program using the `-g` flag.
+    * This is not strictly necessary but this will allow Valgrind to print line
+      numbers to the source code in the stack trace.
+    * Two ways:
+        * Pass the pass through the command line: `$ make CXXFLAGS=-g`
+        * Edit the `Makefile` and add a `CXXFLAGS += -g` directive
+          near the top of the file.
+2. Run the program under the `valgrind` program.
+    * Valgrind has tons of options and flags. Here are the flags that I use
+      (don't remember where I got them):
+        * `$ alias val='valgrind --tool=memcheck --leak-check=yes
+        --show-reachable=yes --num-callers=20 --track-fds=yes'`
+        * `$ val ./MyProgram.out`
+
+When the program crashes because of a `nullptr` dereference, Valgrind will show
+exactly where that happened in the source code.
+
 <a name="SupportedArduinoFeatures"></a>
 ## Supported Arduino Features