Add MacOS error note on user guide

flow-storm · Nov 15, 2023 · 0d99ef0 · 0d99ef0
1 parent 0e3f5fd
commit 0d99ef0
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 1 deletion.
diff --git a/docs/user_guide.adoc b/docs/user_guide.adoc
@@ -65,6 +65,13 @@ but it will be cached unless you run with -Sforce.
 It is much safer to just write the latest versions. Check out  the https://github.com/flow-storm/flow-storm-debugger/[github page] for the latest stable releases.
 ====
 
+[IMPORTANT]
+.On using MacOS
+====
+There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <<#_ui_doesnt_work_on_macos,here>>.
+====
+
 
 Pasting that command on your terminal will bring up a repl with _FlowStorm_ and the compiler swapped by _ClojureStorm_. When the repl comes up just
 evaluate the `:tut/basics` keyword on it for a tour of the basics.
@@ -154,6 +161,13 @@ user> (require '[flow-storm.api :as fs-api]) ;; the only namespace you need to r
 user> (fs-api/local-connect) ;; will run the debugger GUI and get everything ready
 ----
 
+[IMPORTANT]
+.On using MacOS
+====
+There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <<#_ui_doesnt_work_on_macos,here>>.
+====
+
 You should now see a empty debugger window.
 
 Lets debug something :
@@ -278,6 +292,13 @@ when your need it, run the debugger ui with your shadow-cljs.edn data :
 clj -Sforce -Sdeps '{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "RELEASE"}}}' -X flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-app
 ----
 
+[IMPORTANT]
+.On using MacOS
+====
+There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <<#_ui_doesnt_work_on_macos,here>>.
+====
+
 Now since we started the app with `flowstorm.startRecording=false` you will have to click on the record button once to start recording.
 Whenever recording is enable and something executes under an instrumented namespace you should see the recordings appear in the debugger
 under the main thread.

diff --git a/docs/user_guide.html b/docs/user_guide.html
@@ -888,6 +888,22 @@ <h5 id="_clojurestorm"><a class="anchor" href="#_clojurestorm"></a><a class="lin
 </tr>
 </table>
 </div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Important</div>
+</td>
+<td class="content">
+<div class="title">On using MacOS</div>
+<div class="paragraph">
+<p>There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <a href="#_ui_doesnt_work_on_macos">here</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
 <div class="paragraph">
 <p>Pasting that command on your terminal will bring up a repl with <em>FlowStorm</em> and the compiler swapped by <em>ClojureStorm</em>. When the repl comes up just
 evaluate the <code>:tut/basics</code> keyword on it for a tour of the basics.</p>
@@ -1018,6 +1034,22 @@ <h5 id="_vanilla_flowstorm"><a class="anchor" href="#_vanilla_flowstorm"></a><a
 </span><span class="n">user&gt;</span><span class="w"> </span><span class="p">(</span><span class="nf">fs-api/local-connect</span><span class="p">)</span><span class="w"> </span><span class="c1">;; will run the debugger GUI and get everything ready</span></code></pre>
 </div>
 </div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Important</div>
+</td>
+<td class="content">
+<div class="title">On using MacOS</div>
+<div class="paragraph">
+<p>There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <a href="#_ui_doesnt_work_on_macos">here</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
 <div class="paragraph">
 <p>You should now see a empty debugger window.</p>
 </div>
@@ -1206,6 +1238,22 @@ <h5 id="_clojurescriptstorm_with_shadow_cljs"><a class="anchor" href="#_clojures
 <pre class="rouge highlight"><code data-lang="bash">clj <span class="nt">-Sforce</span> <span class="nt">-Sdeps</span> <span class="s1">'{:deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "RELEASE"}}}'</span> <span class="nt">-X</span> flow-storm.debugger.main/start-debugger :port 9000 :repl-type :shadow :build-id :my-app</code></pre>
 </div>
 </div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Important</div>
+</td>
+<td class="content">
+<div class="title">On using MacOS</div>
+<div class="paragraph">
+<p>There is a known issue that makes the UI crash when starting on some versions of MacOS, due to JavaFx/OpenJDK/MacOS incompatibilities.
+Luckly there is a fix for it <a href="#_ui_doesnt_work_on_macos">here</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
 <div class="paragraph">
 <p>Now since we started the app with <code>flowstorm.startRecording=false</code> you will have to click on the record button once to start recording.
 Whenever recording is enable and something executes under an instrumented namespace you should see the recordings appear in the debugger
@@ -3352,7 +3400,7 @@ <h3 id="_internals_diagrams_and_documentation"><a class="anchor" href="#_interna
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-11-15 10:58:15 -0300
+Last updated 2023-11-15 11:33:57 -0300
 </div>
 </div>
 </body>