Add new flag; update readme (#244)

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:

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).