This document describes:
* The purpose of various files in the distribution.
* How to run the JACL tests in a Web browser.
* How to connect to a JACL REPL, hosted in Google Chrome, from a
host terminal.
* How to connect to a JACL REPL from within
[Emacs](https://www.gnu.org/software/emacs/).
# Files of Interest
* `jacl.html` is Web page that includes the JACL runtime, compiler,
and test suite. Currently, JACL development is performed mostly by
making changes and reloading this file in a Web browser to see if
anything breaks.
* `jacl.js` contains the JACL runtime, compiler, and REPL
machinery. `jacl.js` will also fetch, compile, and evaluate any
`<script type='application/lisp' src=... />` tags found in `<head>`
in their order of appearance. Lisp script loading is why `jacl.html`
must be served from a Web browser and not simply from a `file://`
URL. JACL uses Ajax to fetch Lisp scripts.
* `boot.lisp` is where the `COMMON-LISP` package is populated from. It
is evaluated by `jacl.js` when `jacl.html` loads.
* `jacl-tests.lisp` contains Lisp unit tests and is evaluated after
`boot.lisp`.
* `repl/jacl-client.R` is a JACL REPL client written in R. It is
capable of connecting to the WebSocket interface presented by an
instance of Google Chrome with remote debugging enabled. It then
communicates with JACL over the debugging channel.
* `repl/jacl` is a shell wrapper around `jacl-client.R`. It is
designed to be symlinked from somewhere on your `$PATH` for use as
an Emacs
[inferior-lisp](https://www.gnu.org/software/emacs/manual/html_node/emacs/External-Lisp.html)
program.
# Running JACL Tests
First, you must start a local Web server on localhost:8000 to serve
this directory. There are many ways to do this, but on a typical Linux
system, one or both of the following commands will probably work:
# If you have Python 2:
python -m SimpleHTTPServer
# If you have Python 3:
python3 -m http.server
Next, visit http://localhost:8000 with your Web browser of
choice. JACL development is performed primarily on Google Chrome, but
other browsers should work.
You should see a page of test results. [QUnit](https://qunitjs.com/)
The JACL runtime and compiler are contained in the file `jacl.js`.
# Connect to a JACL REPL
This task involves downloading R, several R packages, and starting
Google Chrome with remote debugging enabled. These instructions are
for Linux but likely work on macOS and Windows 10 with slight
modification.
## Install R and required R Packages
First, install the latest version of [R](https://www.r-project.org/)
for your platform. Then, install openssl for your platform:
* deb: libssl-dev (Debian, Ubuntu, etc)
* rpm: openssl-devel (Fedora, CentOS, RHEL)
* csw: libssl_dev (Solaris)
* brew: openssl (Mac OSX)
Next, start R with the `R` command. At the R prompt, evaluate the
following to install the `remotes` package package from CRAN, R's
primary package repository:
install.packages(c("curl", "remotes"))
Now you must install a development package, `chromote`, that is not
yet on CRAN. `chromote` may be installed from GitHub using the
`remotes` package you have just installed. At the R prompt, evaluate
the following:
remotes::install_github("rstudio/chromote")
After compilation completes, you will be returned to the `>` R
prompt. You can exit R with `q()`. You need not "Save workspace image"
when prompted.
## Run Google Chrome with Remote Debugging
If you haven't yet, start a local Web server using the instructions
under "Run JACL Tests".
Then, start Google Chrome — or Chromium, an open-source alternative —
using the procedure documented here:
https://blog.chromium.org/2011/05/remote-debugging-with-chrome-developer.html
Note that the `--user-data-dir` is required; Chrome will not start
properly unless this directory is specified, exists, and can be
created or is otherwise writable.
After the browser opens, use it to navigate to
http://localhost:8000. You should see the JACL tests page.
## Start `jacl`
At this point, you may start a JACL REPL with the following command:
./repl-client/jacl
# Connect to a JACL REPL from Emacs
Follow the steps under "Connect to a JACL REPL".
Then, open Emacs, and type `C-u M-x run-lisp`
At the prompt, enter `jacl`
You should be presented with an inferior-lisp buffer in which you may
evaluate JACL forms.
You may also send forms from Lisp buffers to the JACL REPL for
evaluation. See the documentation for `lisp-mode` for details and
applicable key bindings.
You may find the following elisp function useful. It starts or
restarts a JACL REPL:
```
(defun jacl-repl ()
(interactive)
(let ((kill-buffer-query-functions nil))
(when (get-buffer "*inferior-lisp*")
(kill-buffer "*inferior-lisp*")))
(run-lisp "jacl"))
```