Source executed via Planck can depend on other bootstrapped-compatible libraries. To do so, the library must be on Planck's classpath, available either as source on an accessible filesystem, or bundled in a JAR.

Planck can consume conventional JARs meant for use with ClojureScript obtained from Clojars or elsewhere.

Note that, since Planck employs bootstrapped ClojureScript, not all regular ClojureScript libraries will work with Planck. In particular, libraries that employ macros that either rely on Java interop, or call macros in the same compilation stage cannot work. But libraries that employ straightforward macros that expand to ClojureScript work fine.

Classpath Specification

Planck's classpath is specified by providing a colon-separated list of directories and/or JARs via the -c / -​-​classpath argument, or by the PLANCK_CLASSPATH environment variable. The default classpath, if none is specified, is taken as the current working directory.

For example,

planck -c src:/path/to/foo.jar:some-lib/src

will cause Planck to search in the src directory first, then in foo.jar next, and finally some-lib/src for files when processing require, require-macros, import, and ns forms.

Abbreviated Dependency Specs

The -D / -​-​dependencies option can be used to specify coordinates for JARs installed in your local .m2 repo: You can provide a comma separated list of SYM:VERSION, and paths to these JARs will be appended to your classpath.

For example,

planck -c src -D andare:0.7.0,org.clojure/test.check:0.10.0-alpha2

will expand to a classpath that specifies src followed by the paths to the Andare and test.check dependencies in your local .m2 repository.

In order to use an explicitly-specified path to a Maven repository, you can additionally include -L or -​-​local-repo, specifying the repository path.

Downloading Deps

While Planck can consume JARs from your local .m2 repo, it doesn't take care of downloading them. An easy way to quickly download dependencies is to use boot with its -d option. For example, executing this will ensure the dependencies specified above are installed:

boot -d andare:0.7.0 -d org.clojure/test.check:0.10.0-alpha2

Using Clojure CLI Tools

An easy way to form a classpath while also ensuring that dependencies are downloaded is to use the Clojure CLI tools. The Getting Started guide shows how to install the tools. With them in place you can create a deps.edn file specifying the dependencies of your project. For example, if you set up deps.edn with

  :deps {
    andare {:mvn/version "0.7.0"}
    org.clojure/test.check {:mvn/version "0.10.0-alpha2"}

then Planck can be launched via

planck -c `clojure -Spath`

This will ensure that the needed dependencies have been downloaded, and that Planck is set up with the proper classpath. Note that the clojure tool is fast, caching classpath information so that it runs instantly.

The classpath generated by clojure -Spath will by default include src. If you need to specify other source directories, this is also possible using deps.edn by using :paths. You can also specify dependencies on the source trees of local disk-based projects by using :local/root and a path instead of :mvn/version. More details are at the Deps and CLI Guide.

Bundled Deps

Planck ships with many of the deps that are available to conventional ClojureScript code. In particular this includes most of the Google Closure library as well as these namespaces:

In addition, Planck ships with these libraries:

Note that bundled dependencies, which includes the core ClojureScript compiler namespaces, are loaded in preference to dependencies specified via -c / -​-​classpath, -D / -​-​dependencies, or PLANCK_CLASSPATH.

A consequence of this (as well as the fact that nearly all of the code that ships with Planck is AOT-compiled), means that Planck works with a fixed version of ClojureScript. (It is not possible to update the ClojureScript version by providing a path to a newer version via -c / -​-​classpath, -D / -​-​dependencies, or PLANCK_CLASSPATH.)

Foreign Libs

It is possible to use foreign libraries with Planck.

“Foreign” libraries are implemented in a language that is not ClojureScript. (In other words, JavaScript!)

Planck will honor any deps.cljs files on the classpath (including those embedded in a JAR file). A deps.cljs file will have a :foreign-libs specification for foreign dependencies, essentially indicating the synthetic namespace, the JavaScript file that needs to be loaded, and an indication of any other dependencies that need to be loaded for each foreign lib. If specified for a given foreign lib, Planck will load :file-min in preference to :file if Planck is launched with simple optimizations (via -O simple or –optimizations simple).

While deps.cljs files are usually bundled in JAR files in order to convey upstream foreign lib dependencies, you can also put a deps.cljs file directly on Planck's classpath in order to specify :foreign-libs. (This is useful since Planck doesn't provide a command line argument mechanism for specifying foreign libs.)

One easy way to make use of foreign libs packaged in this manner is via the excellent CLJSJS project. While many of the libraries packaged by CLJSJS cannot work with Planck because they either require a browser environment or Node, some utility libraries work just fine.

Here's an example: Let's say you want to use the long.js library. The first thing you'll need to do is to obtain the CLJSJS JAR containing this library. The easiest way to do this is to execute boot -d cljsjs/long:3.0.3-1 as described in the Downloading Deps section above.

If you launch Planck wtih planck -D cljsjs/long:3.0.3-1, you can (require 'cljsjs.long) to load the library and then proceed to use it using ClojureScript's JavaScript interop capabilities:

cljs.user=> (require 'cljsjs.long)
cljs.user=> (str (js/Long. 0xFFFFFFFF 0x7FFFFFFF))
cljs.user=> (str js/Long.MAX_UNSIGNED_VALUE)