Add FlowStorm, a tracing debugger for Clojure(Script)

.gitignore

@@ -83,6 +83,9 @@ shim.js
 figwheel_server.log
 .nrepl-port
 
+# FlowStorm (Clojure debugger)
+repl-client-debug
+
 # Lein
 #
 .lein-failures

Makefile

@@ -401,6 +401,17 @@ test-component: ##@test Run component tests once in NodeJS
 	yarn shadow-cljs compile component-test && \
 	jest --clearCache && jest --config=test/jest/jest.config.js --testEnvironment node
 
+# Reference: https://flow-storm.github.io/flow-storm-debugger/user_guide.html#_debugging_react_native_applications
+run-flow-storm: export SHADOW_CLJS_BUILD_ID := :mobile
+run-flow-storm: export TARGET := clojure
+run-flow-storm: export GDK_DPI_SCALE := 1.0
+run-flow-storm: ##@run Start FlowStorm debugger
+	clj -Sforce -Sdeps '{:deps {com.github.jpmonettas/flow-storm-dbg {:mvn/version "3.7.5"}}}' \
+		-X flow-storm.debugger.main/start-debugger \
+		:port 7888 \
+		:repl-type :shadow \
+		:build-id $(SHADOW_CLJS_BUILD_ID)
+
 #--------------
 # Other
 #--------------
@@ -423,11 +434,13 @@ android-clean: ##@prepare Clean Gradle state
 	rm -rf ~/.gradle
 
 
+android-ports: export FLOWSTORM_PORT := 7722
 android-ports: export TARGET := android-sdk
 android-ports: ##@other Add proxies to Android Device/Simulator
 	adb reverse tcp:8081 tcp:8081 && \
 	adb reverse tcp:3449 tcp:3449 && \
 	adb reverse tcp:4567 tcp:4567 && \
+	adb reverse tcp:$(FLOWSTORM_PORT) tcp:$(FLOWSTORM_PORT) && \
 	adb forward tcp:5561 tcp:5561
 
 android-devices: export TARGET := android-sdk

doc/debugging.md

@@ -20,6 +20,39 @@ A server will be started at http://localhost:4567. It might show "not connected"
 
 More details about re-frisk are on the [project page](https://github.com/flexsurfer/re-frisk).
 
+## Debugging with FlowStorm
+
+[FlowStorm](http://www.flow-storm.org/) is a free and open-source time-travel
+debugger for Clojure and ClojureScript. It is capable of recording almost any
+code execution path in the Status' mobile app.
+
+FlowStorm is independent of editor/IDE, but a tighter [integration with
+Emacs](https://github.com/jpmonettas/cider-storm) is available.
+
+If you are developing with Android, run `make android-ports` first. If you are
+behind a firewall, allow TCP traffic on port `7722`, then:
+
+```bash
+make run-flow-storm
+```
+
+You will know FlowStorm is correctly running if you see the status bar with
+green `REPL` and `RUNTIME` indicators.
+
+With FlowStorm running, you can now add `#trace` on any top-level form, reload
+the code, or evaluate the traced form in the REPL, and FlowStorm will start
+recording data. Avoid `#rtrace` (with `r`) because it can cause massive spikes
+in CPU which will make the app hang and you might need to forcefully kill
+processes.
+
+```clojure
+#trace ; => Add this line to tell FlowStorm to instrument the function.
+(defn say-hello []
+  (str "Hello world"))
+```
+
+There are other ways to debug, but this is a good start.
+
 ## Enabling debug logs
 Calls to `log/debug` will not be printed to the console by default. It can be enabled under "Advanced settings" in the app: