Basilisp Integration with CIDER

since 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 your 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 at few ways to setup (custom) variables in Emacs

1. Examining and Setting Variables

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

  • C-h v cider-basilisp-parameters

2. Per-Diretory 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 to updating or creating a .dir-local.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:
{}