-
Notifications
You must be signed in to change notification settings - Fork 0
Quick Start
NOTE: The following instructions are useful if for some reason you need to use the ClojureScript compiler directly. For a more integrated workflow, Leiningen with lein-cljsbuild is recommended.
Run the following three commands to get ClojureScript and the Google libraries it depends on.
git clone git://github.com/clojure/clojurescript.git
cd clojurescript
./script/bootstrap
Windows users please also see Windows Setup.
There are a few notable tools which come with ClojureScript:
./script/repl
Start a properly-classpathed Clojure REPL. From within this REPL, start a ClojureScript REPL by evaluating:
(require '[cljs.repl :as repl])
(require '[cljs.repl.rhino :as rhino])
(def env (rhino/repl-env))
(repl/repl env)./script/repljs
Start a ClojureScript REPL.
In this mode, ClojureScript code will be compiled into JavaScript and executed by the JDK's embedded JavaScript engine.
For more information about using the ClojureScript REPL, including information about how to use the browser as the evaluation environment, see The REPL and Evaluation Environments.
./bin/cljsc
Compile ClojureScript source files or projects to runnable JavaScript. To run this tool from anywhere other than the ClojureScript root directory, it is convenient to set a CLOJURESCRIPT_HOME environment variable pointing to the ClojureScript root directory and to add $CLOJURESCRIPT_HOME/bin to your path.
The first argument to cljsc is a ClojureScript file or a root directory containing any number of ClojureScript files. The second optional argument is a Clojure map of options, many of which are demonstrated below.
cljsc is convenient when a command-line tool is required or when a file or project only needs to be compiled once. While developing, it is much faster to use the build function from the Clojure (not ClojureScript) REPL:
(require '[cljs.closure :as cljsc])
(doc cljsc/build)
-------------------------
cljs.closure/build
([source opts])
Given a source which can be compiled, produce runnable JavaScript.The examples below will show both the command-line and REPL way to compile each example.
The following example shows the basic steps involved in creating a ClojureScript application and running it from a web page. The example assumes that you are working in the ClojureScript root directory.
First, write some ClojureScript code. In the example below, a function is created which will be called from JavaScript in a web page. The :export metadata ensures that this function name is not minified. The JavaScript function will be available as hello.greet.
(ns hello)
(defn ^:export greet [n]
(str "Hello " n))Save this code into a file named hello.cljs and then compile it to JavaScript.
From the command-line:
$ ./bin/cljsc hello.cljs '{:optimizations :advanced}' > hello.js
Or from the REPL:
(cljsc/build "hello.cljs" {:optimizations :advanced :output-to "hello.js"})Finally, host this JavaScript in a HTML page and call the hello.greet function.
<html>
<head></head>
<body>
<script type="text/javascript" src="hello.js"></script>
<script>
alert(hello.greet("ClojureScript"));
</script>
</body>
</html>To run ClojureScript on Node.js, set the var *main-cli-fn* to the function you want to use as an entrypoint. For instructions on installing Node.js, see the Node.js wiki. The example below shows how a functional programmer might print "Hello World".
(ns nodehello)
(defn -main [& args]
(println (apply str (map [\ "world" "hello"] [2 0 1]))))
(set! *main-cli-fn* -main)Save this to a file named nodehello.cljs and then run the following commands to compile and run.
$ ./bin/cljsc nodehello.cljs '{:optimizations :advanced :target :nodejs}' > nodehello.js
$ node nodehello.js
Note on some platforms (such as ubuntu) the node command may be named nodejs. Another example is available in samples/nodels.cljs, but it currently only works with simple optimizations:
$ ./bin/cljsc samples/nodels.cljs '{:target :nodejs}' > nodels.js
$ node nodels.js src samples
The REPL equivalent of the above two compilation commands are shown below.
(cljsc/build "nodehello.cljs" {:optimizations :advanced :target :nodejs :output-to "nodehello.js"}
(cljsc/build "samples/nodels.cljs" {:target :nodejs :output-to "nodels.js"}Note: This section assumes that you have set the CLOJURESCRIPT_HOME environment variable and have cljsc on your path. All examples show how to compile the project in samples/hello.
The cljsc tool, and the underlying build function, supports three levels of optimization and a development mode where no optimization is performed and each input JavaScript file is kept separate. This section will give a quick overview of how to use each mode.
While developing a new application, leave out the :optimizations option. This will compile all JavaScript into the working directory, which defaults to out and write a "dependencies" file to hello.js.
$ cljsc src > hello.js
From the REPL use:
(cljsc/build "samples/hello/src" {:output-dir "samples/hello/out" :output-to "samples/hello/hello.js"})To host this application in a web page, pull in base.js, hello.js and then goog.require the top-level namespace.
<script type="text/javascript" src="out/goog/base.js"></script>
<script type="text/javascript" src="hello.js"></script>
<script type="text/javascript">
goog.require('hello');
</script>When ready to deploy, compile the file with advanced optimizations.
$ cljsc src '{:optimizations :advanced}' > hello.js
In this situation, only one script tag is required which will pull in the hello.js file:
<script type="text/javascript" src="hello.js"></script>The other types of optimizations: :whitespace and :simple each produce less optimized but more readable code. There is also a :pretty-print option.
$ cljsc src '{:optimizations :simple :pretty-print true}' > hello.js
The command above has the same effect as the one below. :output-dir, the location where compiled JavaScript files are stored, defaults to out. When :output-to is not set, compiled output is printed to standard out.
$ cljsc src '{:optimizations :simple :pretty-print true :output-dir "out" :output-to "hello.js"}'
All of the options shown above may also be used when compiling form the REPL with the build function.