Permalink
Newer
Older
100644 232 lines (175 sloc) 7.5 KB
1
# lein-cljsbuild
2
3
This is a Leiningen plugin that makes it quick and easy to automatically compile
4
your ClojureScript code into Javascript whenever you modify it. It's simple
5
to install and allows you to configure the ClojureScript compiler from within your
6
`project.clj` file.
8
Beyond basic compiler support, lein-cljsbuild can optionally help with a few other things:
10
* [Launching REPLs for interactive development] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/REPL.md)
11
* [Launching ClojureScript tests] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/TESTING.md)
12
* [Sharing code between Clojure and ClojureScript] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/CROSSOVERS.md)
14
The latest version of lein-cljsbuild is `0.2.7`.
15
[See the release notes here.](https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/RELEASE-NOTES.md)
17
## Requirements
18
19
The lein-cljsbuild plugin works with
20
[Leiningen] (https://github.com/technomancy/leiningen/blob/master/README.md)
21
version `1.7.0` or higher.
23
## Installation
24
25
You can install the plugin by adding lein-cljsbuild to your `project.clj`
26
file in the `:plugins` section:
27
29
; Using Leiningen 1.7.0 or newer:
30
(defproject lein-cljsbuild-example "1.2.3"
31
:plugins [[lein-cljsbuild "0.2.7"]])
34
And then running the following command to download it:
35
36
$ lein deps
37
38
## Just Give Me a Damned Example Already!
39
41
[example-projects] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/example-projects)
42
directory for a couple of simple examples of how to use lein-cljsbuild. The
43
[simple project] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/example-projects/simple)
44
shows a dead-simple "compile only" configuration, which is a good place to start. The
45
[advanced project] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/example-projects/advanced)
46
contains examples of how to use the extended features of the plugin.
48
Also, see the
49
[sample.project.clj] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/sample.project.clj)
50
file for an exhaustive list of all options supported by lein-cljsbuild.
52
## Basic Configuration
53
54
The lein-cljsbuild configuration is specified under the `:cljsbuild` section
55
of your `project.clj` file. A simple project might look like this:
56
58
(defproject lein-cljsbuild-example "1.2.3"
59
:plugins [[lein-cljsbuild "0.2.7"]]
60
:cljsbuild {
61
:builds [{
62
; The path to the top-level ClojureScript source directory:
63
:source-path "src-cljs"
64
; The standard ClojureScript compiler options:
65
; (See the ClojureScript compiler documentation for details.)
66
:compiler {
67
:output-to "war/javascripts/main.js" ; default: main.js in current directory
68
:optimizations :whitespace
69
:pretty-print true}}]})
72
For an exhaustive list of the configuration options supported by lein-cljsbuild, see the
73
[sample.project.clj] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/sample.project.clj)
75
76
## Basic Usage
78
Once the plugin is installed, you can build the ClojureScript once:
79
80
$ lein cljsbuild once
81
82
Or you can have lein-cljsbuild watch your source files for changes and
83
automatically rebuild them. This is recommended for development, as it
84
avoids the time-consuming JVM startup for each build:
85
86
$ lein cljsbuild auto
88
To delete all of the JavaScript and ClojureScript files that lein-cljsbuild
89
automatically generated during compilation, run:
90
91
$ lein cljsbuild clean
92
93
## Hooks
94
95
Some common lein-cljsbuild tasks can hook into the main Leiningen tasks
96
to enable ClojureScript support in each of them. The following tasks are
97
supported:
98
99
$ lein compile
100
$ lein clean
101
$ lein test
102
$ lein jar
103
104
To enable ClojureScript support for these tasks, add the following entry to
105
your project configuration:
108
:hooks [leiningen.cljsbuild]
109
```
110
111
Note that by default the `lein jar` task does *not* package your ClojureScript
112
code in the JAR file. This feature needs to be explicitly enabled by adding
113
the following entry to each of the `:builds` that you want included in the
114
JAR file.
117
:jar true
118
```
119
120
If you are using the
121
[crossovers] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/CROSSOVERS.md)
122
feature, and want the `:crossover-path` included in the JAR file, add this entry to your
123
top-level `:cljsbuild` configuration:
124
125
```clj
126
:crossover-jar true
127
```
128
129
## Multiple Build Configurations
130
131
If the `:builds` sequence contains more than one map lein-cljsbuild
132
will treat each map as a separate ClojureScript compiler configuration,
133
and will build all of them in parallel:
136
(defproject lein-cljsbuild-example "1.2.3"
137
:plugins [[lein-cljsbuild "0.2.7"]]
138
:cljsbuild {
139
:builds [
140
{:source-path "src-cljs-main"
141
:compiler {:output-to "main.js"}}
142
{:source-path "src-cljs-other"
143
:compiler {:output-to "other.js"}}}])
144
```
145
146
This is extremely convenient for doing library development in ClojureScript.
147
This allows cljsbuild to compile in all four optimization levels at once, for
148
easier testing, or to compile a test suite alongside the library code.
149
150
You can optionally assign an ID to a build configuration and build
151
only that one:
152
153
```clj
154
(defproject lein-cljsbuild-example "1.2.3"
155
:plugins [[lein-cljsbuild "0.2.7"]]
156
:cljsbuild {
157
:builds [
158
{:source-path "src-cljs-main"
159
:compiler {:output-to "main.js"}}
160
{:id "other"
161
:source-path "src-cljs-other"
162
:compiler {:output-to "other.js"}}}])
163
```
164
165
$ lein cljsbuild auto other
166
167
If you want IDs for all of your build configurations, you can specify
168
them as a map instead of a vector:
169
170
```clj
171
(defproject lein-cljsbuild-example "1.2.3"
172
:plugins [[lein-cljsbuild "0.2.7"]]
173
:cljsbuild {
174
:builds {
175
:main
176
{:source-path "src-cljs-main"
177
:compiler {:output-to "main.js"}}
178
:other
179
{:source-path "src-cljs-other"
180
:compiler {:output-to "other.js"}}}})
181
```
182
183
You can also build multiple configurations at once:
184
185
$ lein cljsbuild auto main other
188
[example-projects/advanced] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/example-projects/advanced)
189
directory for a working example of a project that uses this feature.
191
## REPL Support
192
193
Lein-cljsbuild has built-in support for launching ClojureScript REPLs in a variety
194
of ways. See the
195
[REPL documentation] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/REPL.md)
196
for more details.
198
## Testing Support
199
200
Lein-cljsbuild has built-in support for running external ClojureScript test processes. See the
201
[testing documentation] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/TESTING.md)
202
for more details.
203
Feb 20, 2012
204
## Sharing Code Between Clojure and ClojureScript
205
206
Sharing code with lein-cljsbuild is accomplished via the configuration
207
of "crossovers". See the
208
[crossovers documentation] (https://github.com/emezeske/lein-cljsbuild/blob/0.2.7/doc/CROSSOVERS.md)
209
for more details.
211
## License
212
213
Source Copyright © Evan Mezeske, 2011-2012.
214
Released under the Eclipse Public License - v 1.0.
215
See the file COPYING.
216
217
## Contributors
218
219
* Evan Mezeske **(Author)** (evan@mezeske.com)
220
* Shantanu Kumar (kumar.shantanu@gmail.com)
221
* Luke VanderHart (http://github.com/levand)
222
* Phil Hagelberg (phil@hagelb.org)
223
* Daniel E. Renfer (duck@kronkltd.net)
224
* Daniel Harper (http://djhworld.github.com)
225
* Philip Kamenarsky (http://github.com/pkamenarsky)
226
* Felix H. Dahlke (fhd@ubercode.de)
227
* Jenan Wise (http://github.com/jenanwise)
May 10, 2012
228
* Kris Jenkins (http://github.com/krisajenkins)
229
* Daniel Turczański (http://jvmsoup.com/)
230
* Brandon Henry (http://brandonhenry.net/)
231
* Daniel Gregoire (http://techylinguist.com)