diff --git a/README.md b/README.md index adccde146..8f6ae0fd2 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,91 @@ -## What is ClojureScript? ## +# ClojureScriptStorm -[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. +## Intro +Welcome to the ClojureScriptStorm repository. ClojureScriptStorm is a fork of the [official ClojureScript +compiler](https://github.com/clojure/clojurescript), with some extra code added to make it a dev compiler. +This means a compiler with some extra capabilities tailored for development. -Official web site: https://clojurescript.org +ClojureScriptStorm will add instrumentation (extra javascript) to trace everything that is happening as your programs +execute. You use it by providing a bunch of callbacks that ClojureScriptStorm will call as code runs. -## Releases and dependency information ## +## Starting a repl with ClojureStorm -Latest stable release: 1.11.60 +```bash +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 +``` -* [All released versions](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22clojurescript%22) +The important bits here are : + +- add the ClojureScriptStorm dependency +- tell ClojureScriptStorm what namespaces to instrument via `instrumentOnlyPrefixes` in this case `dev` + +## Hooking into ClojureStorm + +```clojure +(set! cljs.storm.tracer/trace-fn-call-fn + (fn [_ fn-ns fn-name fn-args-vec form-id] + (prn "fn-call " fn-ns fn-name fn-args-vec form-id))) +(set! cljs.storm.tracer/trace-fn-return-fn + (fn [_ ret coord form-id] + (prn "fn-return" ret coord form-id))) +(set! cljs.storm.tracer/trace-expr-fn + (fn [_ val coord form-id] + (prn "expr" val coord form-id))) +(set! cljs.storm.tracer/trace-bind-fn + (fn [_ coord sym-name bind-val] + (prn "bind" coord sym-name bind-val))) +(set! cljs.storm.tracer/trace-form-init-fn + (fn [form-data] + (prn "form-data" form-data))) +``` -[Clojure deps.edn](http://clojure.org/guides/deps_and_cli) dependency information: +Once that is set, you could try something like this : - ``` - org.clojure/clojurescript {:mvn/version "1.11.60"} - ``` +```clojure +user=> (ns dev) +... +dev=> (defn sum [a b] (+ a b)) -[Leiningen](https://github.com/technomancy/leiningen/) dependency information: +"form-data" {:form-id -133716645, :ns "dev", :form (defn sum [a b] (+ a b)), :file nil, :line nil} -``` -[org.clojure/clojurescript "1.11.60"] -``` +dev=> (sum 4 5) -[Maven](https://maven.apache.org) dependency information: +"fn-call " "dev" "sum" #js {"0" 4, "1" 5} -133716645 +"bind" "" "a" 4 +"bind" "" "b" 5 +"expr" 4 "3,1" -133716645 +"expr" 5 "3,2" -133716645 +"fn-return" 9 "3" -133716645 +"expr" 9 "" -1067876745 +"form-data" {:form-id -1067876745, :ns "dev", :form (sum 4 5), :file nil, :line nil} +"expr" "9" "" nil +9 ``` - - org.clojure - clojurescript - 1.11.60 - + +## Forms and coordinates + +The example above shows your callbacks receiving form ids and coordinates, let's see how you can use them. + +The form-id on each fn-call, fn-return and expr corresponds with the data received by on `trace-form-init-fn`. +This function will be called once, when the form is defined in the runtime. + +Coords are strings with the coordinates inside the form tree. +In the case of our sum form, "3,1" means the third element (the `[a b]` vector), and then the first one `a`. +Coordinates also work with unordered literals like sets, and maps with more than 8 keys. + +If you want utility funcitons to work with forms and coordinates take a look at +[get-form-at-coord](https://github.com/flow-storm/hansel/blob/master/src/hansel/utils.cljc#L74-L78) for example. + +## Controlling instrumentation without restarting the repl + +You can add/remove instrumentation prefixes without restarting the repl by calling : + +```clojure +(cljs.storm.api/add-instr-prefix "my-app") +(cljs.storm.api/rm-instr-prefix "my-app") ``` -## Getting Started ## - -* Read the [Quick Start](https://clojurescript.org/guides/quick-start) guide. -* Read the [Documentation](https://clojurescript.org). -* Try a [tutorial](https://clojurescript.org/guides). -* [Companies using ClojureScript](https://clojurescript.org/community/companies) - -## Questions, Feedback? ## - -Please point all of your questions and feedback to the -[Clojure mailing list](https://groups.google.com/group/clojure). There -is a community run -[ClojureScript user mailing list](https://groups.google.com/group/clojurescript) and -the IRC channel, `#clojurescript` on [freenode.net](https://freenode.net/), is quite active. -There is also a community run [Slack channel](https://clojurians.slack.com). The -Jira bug/feature tracking application is located at -. Before submitting issues -please read the -[Reporting Issues](https://github.com/clojure/clojurescript/wiki/Reporting-Issues) -page first. - -## Developers Welcome ## - -ClojureScript operates under the same license as Clojure. All -contributors must have a signed CA (Contributor's Agreement) and -submit their patch via the appropriate channels. If you're interested -in contributing to the project, please see the -[contributing](https://clojure.org/dev/contributing) page on -[clojure.org](https://clojure.org). For more information about working -on the compiler and testing check the -[Developer section of the wiki](https://github.com/clojure/clojurescript/wiki/Developers). - -YourKit ----- - - - -YourKit has given an open source license for their profiler, greatly simplifying the profiling of ClojureScript performance. - -YourKit supports open source projects with its full-featured Java Profiler. -YourKit, LLC is the creator of YourKit Java Profiler -and YourKit .NET Profiler, -innovative and intelligent tools for profiling Java and .NET applications. - -## License ## - - Copyright (c) Rich Hickey. All rights reserved. The use and - distribution terms for this software are covered by the Eclipse - Public License 1.0 (https://opensource.org/license/epl-1-0/) - which can be found in the file epl-v10.html at the root of this - distribution. By using this software in any fashion, you are - agreeing to be bound by the terms of this license. You must - not remove this notice, or any other, from this software. +## Applications using ClojureScriptStorm + +* [FlowStorm debugger](http://www.flow-storm.org) diff --git a/deps.edn b/deps.edn index 435152b49..072b1e937 100644 --- a/deps.edn +++ b/deps.edn @@ -19,7 +19,7 @@ :main-opts ["-m" "cljs.main" "-co" "resources/test.edn" "-c"]} :runtime.storm.test.build {:extra-paths ["src/test/cljs"] - :jvm-opts ["-Dcljs.storm.instrumentOnlyPrefixes=cljs.storm.tests" + :jvm-opts ["-Dcljs.storm.instrumentOnlyPrefixes=cljs.storm.tests-code" "-Dcljs.storm.instrumentEnable=true"] :main-opts ["-m" "cljs.main" "-co" "resources/storm_test.edn" "-c"]} @@ -29,6 +29,13 @@ :main-opts ["-i" "src/test/self/self_parity/setup.clj" "-e" "(self-parity.setup/-main)" "-m" "cljs.main" "-co" "resources/self_parity_test.edn" "-c"]} + :shadow-test-storm {:extra-paths ["src/test/cljs"] + :jvm-opts ["-Dcljs.storm.instrumentOnlyPrefixes=cljs.storm.tests-code" + "-Dcljs.storm.instrumentEnable=true"] + :classpath-overrides {org.clojure/clojurescript nil} + :extra-deps {thheller/shadow-cljs {:mvn/version "2.25.6" + :exclusions [org.clojure/clojurescript]} + com.github.jpmonettas/clojurescript {:local/root "./"}}} :uberjar {:extra-deps {com.github.seancorfield/depstar {:mvn/version "2.0.193"}} :exec-fn hf.depstar/uberjar :exec-args {:aot true}} diff --git a/script/build b/script/build index a39ddafc0..513677b9e 100755 --- a/script/build +++ b/script/build @@ -27,7 +27,7 @@ CLJS_SCRIPT_MVN_OPTS=${CLJS_SCRIPT_MVN_OPTS:-""} MAJOR="1" MINOR="11" REVISION="60" -PATCH="4" +PATCH="5" # Extract the version number from the string. # REVISION_REGEX="v[0-9]*\.[0-9]*-([0-9]*)-.*" # if [[ $REVISION =~ $REVISION_REGEX ]] diff --git a/src/main/cljs/cljs/core.cljs b/src/main/cljs/cljs/core.cljs index 620bc8abc..1d6d8cbca 100644 --- a/src/main/cljs/cljs/core.cljs +++ b/src/main/cljs/cljs/core.cljs @@ -16,7 +16,7 @@ (:import [goog.string StringBuffer])) ;; next line is auto-generated by the build-script - Do not edit! -(def *clojurescript-version*) +(def *clojurescript-version* "1.11.60") ;; Setting of these Vars is in ClojureScript code is associated with intrinsics ;; that affect compilation state, but otherwise turn into no-ops in the emitted diff --git a/src/main/clojure/cljs/util.cljc b/src/main/clojure/cljs/util.cljc index 98d1325ea..4bbd724a4 100644 --- a/src/main/clojure/cljs/util.cljc +++ b/src/main/clojure/cljs/util.cljc @@ -17,7 +17,7 @@ [java.security MessageDigest])) ;; next line is auto-generated by the build-script - Do not edit! -(def ^:dynamic *clojurescript-version* {:major 1, :minor 11, :qualifier 104}) +(def ^:dynamic *clojurescript-version* {:major 1, :minor 11, :qualifier 60}) (defn compilation-error [cause] (ex-info nil {:clojure.error/phase :compilation} cause))