Basilisp Integration with CIDER

Basilisp support was added in CIDER 1.14.

Overview

Basilisp aims to enable writing Clojure programs on Python with full interoperability. It is highly compatible with Clojure.

To install Basilisp, run:

$ pip install basilisp

Usage

There are several ways to connect to Basilisp.

jack-in

M-x cider-jack-in and M-5 M-x cider-jack-in-universal

If you have created a basilisp.edn project file at the root of your project tree, you can jack in to the project with M-x cider-jack-in. The basilisp.edn is similar to deps.edn for clojure-cli projects. It can be left empty just to mark the root of your project.

If you don’t have or want a basilisp project file, you can use universal jack in with a numerical argument of 5:

  • M-5 M-x cider-jack-in-universal, or

  • M-5 C-c C-x j u, from within a file in clojure-mode

an alternative to M-5 is C-u 5

You can also bind the universal jack-in to Basilisp to a function to use as a shortcut, for example:

(global-set-key (kbd "<f12>") (lambda ()
                                (interactive)
                                (cider-jack-in-universal 5)))

connect

M-x cider-connect

You can start its bundled nREPL server:

$ basilisp nrepl-server

and connect to it afterward using M-x cider-connect.

To see available options, type basilisp nrepl-server -h in a shell prompt.

Configuration

The jack-in command can be configured with the following defcustoms:

cider-basilisp-command

(default is basilisp)

If Basilisp is installed in a virtual environment, update this to the full path of the basilisp executable within that virtual environment.

cider-basilisp-parameters

(default is nrepl-server)

Customization

There are a few ways to set up (custom) variables in Emacs

1. Examining and Setting Variables

  • C-h v cider-basilisp-command, and

  • C-h v cider-basilisp-parameters

2. Per-Directory Local Variables

Uses .dir-locals.el to setup per mode variables. This file is typically stored at the root of the project.

For example, to set the path to the basilisp executable within a virtual environment

  • M-x add-dir-local-variable

  • Mode or subdirectory: clojure-mode

  • Add directory-local variable: cider-basilisp-command

  • Add cider-basilisp-command with value: "c:/dev/venvs/312/Scripts/basilisp"

This should result in updating or creating a .dir-locals.el file like below

;;; Directory Local Variables            -*- no-byte-compile: t -*-
;;; For more information see (info "(emacs) Directory Variables")

((clojure-mode . ((cider-basilisp-command . "c:/dev/venvs/312/Scripts/basilisp"))))

3. Specifying File Variables

It is best to put this in the top of your project’s basilisp.edn file, and always jack-in from there.

For example, setting cider-basilisp-command to start basilisp from within a virtual environment:

  • M-x add-dir-local-variable

  • Add file-local variable: cider-basilisp-command

  • Add cider-basilisp-command with value: "c:/dev/venvs/312/Scripts/basilisp"

This will result in the following in basilisp.edn

;; Local Variables:
;; cider-basilisp-command: "c:/dev/venvs/312/Scripts/basilisp"
;; End:
{}