A significant refactoring of the ClojureScript-standard browser-repl environment that's as easy to "configure" and use as a Clojure REPL.
Austin has one objective: to get you into a fast ClojureScript REPL suited for your project running in a browser environment as quickly and painlessly as possible, with full support for the nREPL toolchain.
Check out the screencast demonstrating how Austin is used, or forge ahead for detailed documentation.
I've been using this browser-repl alternative for more than a year with good results,
and others have banged it around some as well. That said, I've only recently
begun to think about the API around its configuration and project integration
(in particular, the cemerick.austin.repls
namespace). It all works nice, but
changes in that department are almost surely going to happen.
When using Austin via nREPL, it depends upon Piggieback. Please refer to Piggieback's compatibility notes to see if there are any known problems with using it (and therefore Austin) with your preferred toolchain.
Available here.
Austin is largely a refactoring of the original ClojureScript REPL. These changes include:
:port
arguments, etc.com.sun.net.httpserver.*
bits (a
standard part of J2SE
6+):port
argument to repl-env
is no longer supported; the lifecycle of
the server is not tied to the creation of a browser-REPL environment. If you
need to get the port of the running browser-REPL server, use
(get-browser-repl-port)
; if you need a URL you can use with
clojure.browser.repl/connect
as shown in existing browser-REPL tutorials,
it's available under :repl-url
from the browser-REPL environment you want to
connect to. See 'Browser-connected REPLs' for
easy-mode browser-connected REPLsAustin is available in Maven Central. Add it to your project.clj
's list of
:plugins
, probably in your :dev
profile:
:profiles {:dev {:plugins [[com.cemerick/austin "0.1.6"]]}}
Also, just like in Clojure development, your ClojureScript source roots must be
listed in e.g. :source-paths
and/or :test-source-paths
in order for
ClojureScript source files to be picked up properly. i.e. just having them
enumerated in your lein-cljsbuild configuration(s) is not sufficient.
Note that Austin requires ClojureScript 0.0-2665
or higher.
Austin contains some Leiningen middleware that does the following:
:repl-options
to include Piggieback's
wrap-cljs-repl
middleware.(require '[cemerick.austin.repls :refer (exec) :rename {exec austin-exec}])
to your project's :injections
, thus making
cemerick.austin.repls/exec
available as austin-exec
in the user
namespace for your fast'n'easy ClojureScript browser REPL pleasure.If you're impatient, skip on down to start a ClojureScript REPL using phantomjs/slimerjs/Chrome/etc in about 10 seconds.
Austin provides two types of ClojureScript REPL environments. One, returned by
calls to cemerick.austin/repl-env
, is analogous to the standard ClojureScript
browser-REPL environment implemented in cljs.repl.browser
, with various
usability improvements. The other, returned by calls to
cemerick.austin/exec-env
, provides all the same functionality as repl-env
,
but also fully manages the lifecycle of an external JavaScript runtime that is
used to service all REPL interactions (i.e. you don't need to have an app
running in a GUI browser to get a browser-REPL going). Either of these REPL
environments can be used with either of:
cljs.repl/repl
, described in the various "core" ClojureScript tutorials as
the primary entry point for all things REPL. This is suitable in terminal
settings, can be used w/ e.g. inferior-lisp
in emacs, and so on, but cannot
be used with nREPL.cemerick.piggieback/cljs-repl
, the nREPL-compatible analogue to
cljs.repl/repl
, provided by PiggiebackAustin's two types of REPL environments roughly correspond to the two primary scenarios for ClojureScript REPLs:
exec-env
is used.This nomenclature is a bit hand-wavy, since the JavaScript runtimes used by project REPLs are almost always also browsers; hopefully I'll come up with a better term for the first category eventually.
To start a project REPL, just pass the result of calling exec-env
to the
ClojureScript REPL function that corresponds with your environment:
(cemerick.piggieback/cljs-repl :repl-env (cemerick.austin/exec-env))
(cljs.repl/repl (cemerick.austin/exec-env))
Alternatively, you can use cemerick.austin.repls/cljs-repl
, a convenience
function that will detect whether you're using nREPL or not, and pass a new exec
environment to the correct ClojureScript REPL function. So,
(cemerick.austin.repls/cljs-repl (cemerick.austin/exec-env))
is equivalent to
the two examples above; this particular combination is so commonly used that
it's wrapped up into a single function, (cemerick.austin.repls/exec)
, probably
the easiest way to start a ClojureScript REPL that uses a browser JavaScript
runtime. Note that cemerick.austin.repls/exec
passes all of its arguments
along to exec-env
.
exec-env
's browser runtimesAny of the above options will give you a headless ClojureScript REPL that has all
of your project's dependencies, sources, and other resources available.
exec-env
uses phantomjs
by default, so you'll need to have that installed
and on your PATH
. If you are using a different phantomjs-compatible
headless browser implementation (e.g. slimerjs, or perhaps your package manager
installs phantomjs with a different name?), you can pass the name of that binary
as :phantom-cmd, e.g. (exec-env :phantom-cmd "slimerjs")
.
Whichever process is started will be automatically terminated when you stop the
ClojureScript REPL (via :cljs/quit
), or the parent Clojure REPL.
I've been saying "headless" here because it's often most convenient to avoid
using "headed" browsers, which necessarily open a new window for each
ClojureScript REPL you start. But, if you really want to, you can use a full
GUI browser with exec-env
, which can be handy if you need to see the results
of DOM manipulations, etc., without having to set up and connect to a browser
running your application. To do this, just pass the terminal commands necessary
to start your preferred browser (such that Austin can append the browser-repl
URL to the command) to exec-env
or exec
as a :exec-cmds
vector keyword
argument:
user=> (cemerick.austin.repls/exec
:exec-cmds ["open" "-ga" "/Applications/Google Chrome.app"])
Browser-REPL ready @ http://localhost:59423/4877/repl/start
Type `:cljs/quit` to stop the ClojureScript REPL
nil
cljs.user=> (apply + (js/Array 1 2 3))
6
The command strings passed to exec
in this example will open the browser-REPL
endpoint URL in a new Chrome window in the background on Mac OS X. Substitute
whatever invocation you like for your preferred browser / operating system.
This was always the primary use case for the original browser-repl: load your application up in a browser, have it connect back to your Clojure / ClojureScript compiler environment, and you can develop/debug/inspect/etc your running ClojureScript application as it runs in its target environment.
This repo provides a completely self-contained sample project demonstrating and documenting how to use Austin for your browser-connected REPL'ing needs. Check it out.
By default, Austin's embedded HTTP server (which is what accepts requests from
all JavaScript runtimes hosting a ClojureScript REPL) starts on a random
system-assigned port. If you're using the provided facilities for generating
Javascript to insert into your app's HTML to connect back to the HTTP server
(i.e. cemerick.austin.repls/browser-connected-repl-js
), then this is ideal:
the server will always find an open port, and running multiple applications,
each with N browser-REPLs, will always work.
However, if you need to fix the port used by the HTTP server, there are three ways to go about it:
AUSTIN_DEFAULT_SERVER_PORT
environment variable before starting your
Clojure processcemerick.austin.default-server-port
system property; this will only
take effect if you have not yet caused the server to start automatically by
creating a browser-REPL environment.(cemerick.austin/start-server 9000)
.Ping cemerick
on freenode irc or
twitter if you have questions or would
like to contribute.
Big shout out to Brenton Ashworth, Alex Redington, and Bobby Calderwood (the
authors of the original browser-repl), Brandon Bloom for pushing hard on making
ClojureScript easier to use, and everyone else in #clojure and on the mailing
list(s) that took the time to take Austin for a spin when it was still just a
gist and then a .patch
file.
Copyright ©2013 Chas Emerick and other contributors.
Portions copyright (c) Rich Hickey. All rights reserved. The use and
distribution terms for this software are covered by the Eclipse
Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
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.