Custom REPLs

This page documents recent changes to requirements for custom REPLs that use the functionality provided in cljs.repl. These changes have been made towards the goal of dramatically diminishing the start time of all ClojureScript REPLs and simplifying the synchronization of REPL state with compiled source. This is accomplished by reusing the globally available compilation caching infrastructure. In fact it is currently possible to launch a REPL with :output-dir set to an existing compilation cache and incur no analysis or compilation.

Under the new infrastructure all the builtin REPLs are capable of booting on modern hardware in a second or less.

Expectations

In order to boot REPLs as quickly as possible REPLs should implement the second arity of -setup which take the typical compiler build options. In the past -setup was permitted to be asynchronous - this is no longer supported, REPLs must now compile and load cljs.core and all of its dependencies during -setup. In -setup REPLs should use the build options to cache compiled JavaScript and analysis information to the expected location. Note, while it is OK to stream compiled forms the user has entered this should be avoided at all costs for loading namespaces - REPLs should rely on the target environment to interpret goog.require. This has many benefits including precise source mapping information.

The new Node.js REPL is a good example of the new pattern. The Node.js REPL is short because it relies on the Node.js runtime itself to interpret goog.require.

Examining cljs.repl/load-file and cljs.repl/load-namespace will clarify the new approach:

• Given a namespace ensure that it's compiled.
• Compute the goog.addDependency string for the file.
• Evaluate this expression in the target JavaScript environment and then emit goog.require statement for the namespace.

REPLs should override the global CLOSURE_IMPORT_SCRIPT function to get custom goog.require behavior.

Eliminating Loaded Libs tracking

Under the new changes REPLs no longer need to bother with libs tracking. This was only done because goog.provide throws if the namespace has already been loaded. This is a completely bogus error intended to teach "beginners". By monkey-patching goog.isProvided_ to be a function that always returns false - the error can be suppressed. Again the Node.js REPL is a good example.

Special Functions

The all REPLs support several "special functions". All special function must take the REPL environment, an analysis environment, the form, and optional compiler build options. Out of the box in-ns, require, load-file, and load-namespace are provided.