|
1 | | -## What is ClojureScript? ## |
| 1 | +# ClojureScriptStorm |
2 | 2 |
|
3 | | -[ClojureScript](https://clojurescript.org) is a compiler for [Clojure](https://clojure.org) that targets JavaScript. It is designed to emit JavaScript code which is compatible with the advanced compilation mode of the [Google Closure](https://developers.google.com/closure/compiler/) optimizing compiler. |
| 3 | +## Intro |
| 4 | +Welcome to the ClojureScriptStorm repository. ClojureScriptStorm is a fork of the [official ClojureScript |
| 5 | +compiler](https://github.com/clojure/clojurescript), with some extra code added to make it a dev compiler. |
| 6 | +This means a compiler with some extra capabilities tailored for development. |
4 | 7 |
|
5 | | -Official web site: https://clojurescript.org |
| 8 | +ClojureScriptStorm will add instrumentation (extra javascript) to trace everything that is happening as your programs |
| 9 | +execute. You use it by providing a bunch of callbacks that ClojureScriptStorm will call as code runs. |
6 | 10 |
|
7 | | -## Releases and dependency information ## |
| 11 | +## Starting a repl with ClojureScriptStorm |
8 | 12 |
|
9 | | -Latest stable release: 1.12.116 |
10 | 13 |
|
11 | | -* [All released versions](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22clojurescript%22) |
| 14 | +```bash |
| 15 | +clj -J-Dcljs.storm.instrumentOnlyPrefixes=dev -J-Dcljs.storm.instrumentEnable=true -Sdeps '{:paths ["src"] :deps {com.github.flow-storm/clojurescript {:mvn/version "RELEASE"}}}' -M -m cljs.main --repl |
| 16 | +``` |
12 | 17 |
|
13 | | -[Clojure deps.edn](http://clojure.org/guides/deps_and_cli) dependency information: |
| 18 | +The important bits here are : |
| 19 | + |
| 20 | +- add the ClojureScriptStorm dependency |
| 21 | +- tell ClojureScriptStorm what namespaces to instrument via `instrumentOnlyPrefixes` in this case `dev` |
| 22 | + |
| 23 | +## Hooking into ClojureScriptStorm |
| 24 | + |
| 25 | +```clojure |
| 26 | +(set! cljs.storm.tracer/trace-fn-call-fn |
| 27 | + (fn [_ fn-ns fn-name fn-args-vec form-id] |
| 28 | + (prn "fn-call " fn-ns fn-name fn-args-vec form-id))) |
| 29 | +(set! cljs.storm.tracer/trace-fn-return-fn |
| 30 | + (fn [_ ret coord form-id] |
| 31 | + (prn "fn-return" ret coord form-id))) |
| 32 | +(set! cljs.storm.tracer/trace-fn-unwind-fn |
| 33 | + (fn [_ error coord form-id] |
| 34 | + (prn "fn-unwind" error coord form-id))) |
| 35 | +(set! cljs.storm.tracer/trace-expr-fn |
| 36 | + (fn [_ val coord form-id] |
| 37 | + (prn "expr" val coord form-id))) |
| 38 | +(set! cljs.storm.tracer/trace-bind-fn |
| 39 | + (fn [_ coord sym-name bind-val] |
| 40 | + (prn "bind" coord sym-name bind-val))) |
| 41 | +(set! cljs.storm.tracer/trace-form-init-fn |
| 42 | + (fn [form-data] |
| 43 | + (prn "form-data" form-data))) |
| 44 | +``` |
14 | 45 |
|
15 | | - ``` |
16 | | - org.clojure/clojurescript {:mvn/version "1.12.116"} |
17 | | - ``` |
| 46 | +Once that is set, you could try something like this : |
18 | 47 |
|
19 | | -[Leiningen](https://github.com/technomancy/leiningen/) dependency information: |
| 48 | +```clojure |
| 49 | +user=> (ns dev) |
| 50 | +... |
| 51 | +dev=> (defn sum [a b] (+ a b)) |
20 | 52 |
|
21 | | -``` |
22 | | -[org.clojure/clojurescript "1.12.116"] |
23 | | -``` |
| 53 | +"form-data" {:form-id -133716645, :ns "dev", :form (defn sum [a b] (+ a b)), :file nil, :line nil} |
24 | 54 |
|
25 | | -[Maven](https://maven.apache.org) dependency information: |
| 55 | +dev=> (sum 4 5) |
| 56 | + |
| 57 | +"fn-call " "dev" "sum" #js {"0" 4, "1" 5} -133716645 |
| 58 | +"bind" "" "a" 4 |
| 59 | +"bind" "" "b" 5 |
| 60 | +"expr" 4 "3,1" -133716645 |
| 61 | +"expr" 5 "3,2" -133716645 |
| 62 | +"fn-return" 9 "3" -133716645 |
| 63 | +"expr" 9 "" -1067876745 |
| 64 | +"form-data" {:form-id -1067876745, :ns "dev", :form (sum 4 5), :file nil, :line nil} |
| 65 | +"expr" "9" "" nil |
| 66 | +9 |
26 | 67 |
|
27 | 68 | ``` |
28 | | -<dependency> |
29 | | - <groupId>org.clojure</groupId> |
30 | | - <artifactId>clojurescript</artifactId> |
31 | | - <version>1.12.116</version> |
32 | | -</dependency> |
| 69 | + |
| 70 | +## Forms and coordinates |
| 71 | + |
| 72 | +The example above shows your callbacks receiving form ids and coordinates, let's see how you can use them. |
| 73 | + |
| 74 | +The form-id on each fn-call, fn-return and expr corresponds with the data received by on `trace-form-init-fn`. |
| 75 | +This function will be called once, when the form is defined in the runtime. |
| 76 | + |
| 77 | +Coords are strings with the coordinates inside the form tree. |
| 78 | +In the case of our sum form, "2,1" means the third element (the `[a b]` vector), and then the first one `a`. |
| 79 | +Coordinates also work with unordered literals like sets, and maps with more than 8 keys. |
| 80 | + |
| 81 | +If you want utility funcitons to work with forms and coordinates take a look at |
| 82 | +[get-form-at-coord](https://github.com/flow-storm/hansel/blob/master/src/hansel/utils.cljc#L74-L78) for example. |
| 83 | + |
| 84 | +## Controlling instrumentation without restarting the repl |
| 85 | + |
| 86 | +You can add/remove instrumentation prefixes without restarting the repl by calling : |
| 87 | + |
| 88 | +```clojure |
| 89 | +(cljs.storm.api/add-instr-prefix "my-app") |
| 90 | +(cljs.storm.api/rm-instr-prefix "my-app") |
33 | 91 | ``` |
34 | 92 |
|
35 | | -## Getting Started ## |
36 | | - |
37 | | -* Read the [Quick Start](https://clojurescript.org/guides/quick-start) guide. |
38 | | -* Read the [Documentation](https://clojurescript.org). |
39 | | -* Try a [tutorial](https://clojurescript.org/guides). |
40 | | -* [Companies using ClojureScript](https://clojurescript.org/community/companies) |
41 | | - |
42 | | -## Questions, Feedback? ## |
43 | | - |
44 | | -Please point all of your questions and feedback to the |
45 | | -[Clojure mailing list](https://groups.google.com/group/clojure). There |
46 | | -is a community run |
47 | | -[ClojureScript user mailing list](https://groups.google.com/group/clojurescript) and |
48 | | -the IRC channel, `#clojurescript` on [freenode.net](https://freenode.net/), is quite active. |
49 | | -There is also a community run [Slack channel](https://clojurians.slack.com). The |
50 | | -Jira bug/feature tracking application is located at |
51 | | -<https://clojure.atlassian.net/browse/CLJS>. Before submitting issues |
52 | | -please read the |
53 | | -[Reporting Issues](https://github.com/clojure/clojurescript/wiki/Reporting-Issues) |
54 | | -page first. |
55 | | - |
56 | | -## Developers Welcome ## |
57 | | - |
58 | | -ClojureScript operates under the same license as Clojure. All |
59 | | -contributors must have a signed CA (Contributor's Agreement) and |
60 | | -submit their patch via the appropriate channels. If you're interested |
61 | | -in contributing to the project, please see the |
62 | | -[contributing](https://clojure.org/dev/contributing) page on |
63 | | -[clojure.org](https://clojure.org). For more information about working |
64 | | -on the compiler and testing check the |
65 | | -[Developer section of the wiki](https://github.com/clojure/clojurescript/wiki/Developers). |
66 | | - |
67 | | -YourKit |
68 | | ----- |
69 | | - |
70 | | -<img src="https://www.yourkit.com/images/yklogo.png"></img> |
71 | | - |
72 | | -YourKit has given an open source license for their profiler, greatly simplifying the profiling of ClojureScript performance. |
73 | | - |
74 | | -YourKit supports open source projects with its full-featured Java Profiler. |
75 | | -YourKit, LLC is the creator of <a href="https://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a> |
76 | | -and <a href="https://www.yourkit.com/.net/profiler/index.jsp">YourKit .NET Profiler</a>, |
77 | | -innovative and intelligent tools for profiling Java and .NET applications. |
78 | | - |
79 | | -## License ## |
80 | | - |
81 | | - Copyright (c) Rich Hickey. All rights reserved. The use and |
82 | | - distribution terms for this software are covered by the Eclipse |
83 | | - Public License 1.0 (https://opensource.org/license/epl-1-0/) |
84 | | - which can be found in the file epl-v10.html at the root of this |
85 | | - distribution. By using this software in any fashion, you are |
86 | | - agreeing to be bound by the terms of this license. You must |
87 | | - not remove this notice, or any other, from this software. |
| 93 | +## Applications using ClojureScriptStorm |
| 94 | + |
| 95 | +* [FlowStorm debugger](http://www.flow-storm.org) |
0 commit comments