From 5418c93c56ae6e56a5058b0be7e88cdc818f9fbf Mon Sep 17 00:00:00 2001
From: geotre <georgetrevill@gmail.com>
Date: Thu, 2 Mar 2023 12:56:27 +0000
Subject: [PATCH] Add new flag; update readme (#244)

---
 karax/karax.nim |  4 ++--
 readme.md       | 16 ++++++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/karax/karax.nim b/karax/karax.nim
index cd7fc3b..e9dc6c9 100644
--- a/karax/karax.nim
+++ b/karax/karax.nim
@@ -665,7 +665,7 @@ proc dodraw(kxi: KaraxInstance) =
     let asdom = toDom(newtree, useAttachedNode = true, kxi)
     replaceById(kxi.rootId, asdom)
   else:
-    when not defined(release):
+    when not defined(debugKaraxSame):
       doAssert same(kxi.currentTree, document.getElementById(kxi.rootId))
     let olddom = document.getElementById(kxi.rootId)
     diff(newtree, kxi.currentTree, nil, olddom, kxi)
@@ -679,7 +679,7 @@ proc dodraw(kxi: KaraxInstance) =
     echo ">>>>>>>>>>>>>>"
   applyPatch(kxi)
   kxi.currentTree = newtree
-  when not defined(release):
+  when not defined(debugKaraxSame):
     doAssert same(kxi.currentTree, document.getElementById(kxi.rootId))
 
   if not kxi.postRenderCallback.isNil:
diff --git a/readme.md b/readme.md
index 4affb80..559c6e4 100644
--- a/readme.md
+++ b/readme.md
@@ -406,5 +406,21 @@ let
             option: text name
 ```
 
+## Debugging
+
+Karax will accept various compile time flags to add additional checks and debug info.
+
+e.g. `nim js -d:debugKaraxDsl myapp.nim`
+
+| flag name       | description |
+| --------------- | ----------- |
+| debugKaraxDsl   | prints the Nim code produced by the `buildHtml` macro to the terminal at compile time |
+| debugKaraxSame  | Ensures that the rendered html dom matches the expected output from the vdom. Note that some browser extensions will modify the page and cause false positives |
+| karaxDebug*     | prints debug info when checking the dom output and applying component state |
+| stats*          | track statistics about recursion depth when rendering |
+| profileKarax*   | track statistics about why nodes differ |
+
+_* = used when debugging karax itself, not karax apps_
+
 ## License
 MIT License. See [here](https://github.com/karaxnim/karax/blob/master/LICENSE.txt).