BEAM Jupyter Kernels Tool

ierl is a command line tool based on
erlang-jupyter to allow running and
installing Jupyter kernels on the Erlang Virtual Machine written in pure Erlang.
A precompiled version can be downloaded from the release page,
download the ierl escript.

Currently, three kernels have been implemented to the point that they support
running code, compiling modules, and code completion:

Erlang

Currently, only the f shell function to forget a variable is implemented.
However, in contrast to the usual erl shell, this backend also supports
defining modules inline, i.e. one can have a cell

-module(my_mod).
-export([
    func/1
]).
func(X) ->
    X.

and it will be compiled and usable after executing.

Elixir

If ierl has been built using mix (as are the releases that we provide here),
Elixir will be embedded and work without the need to install it locally.
Otherwise, ierl will try to guess the path by running the Elixir executable,
so make sure that elixir‘s binary path is included in the PATH
environment variable. It is also possible to override the Elixir installation
path using the --path switch on installing the kernel.

The Jupyter Notebook will currently highlight the code as Ruby for lack of a
built-in Elixir mode in CodeMirror, but I will look into bundling
codemirror-mode-elixir in
the future.

LFE

LFE is completely bundled and can be run without any further installation. The
highlighting is currently just straight Common Lisp, which means quite a few
things are not highlighted correctly (like defmodule, defrecord, atoms,
etc.).

Common functionality

All kernels can access the jup_display functions to print non-text output (in
particular on the Jupyter Notebook):

% Print 
DisplayRef = jup_display:display(#{ html => "<h1>Some Text</h1>" }).

The key of the passed map is either html, text, or a binary or string
indicating an actual MIME type like text/html. The value is an IO list with
data matching the MIME type. A displayed value can be updated within the same
cell by using the returned reference:

jup_display:update(DisplayRef, #{ html => "<h1>Updated Text</h1>" }).

Currently, the Jupyter Notebook will also update output sections that were
initialised before, but it’s not specified, whether this implementation detail
will stay.

Usage

The released escript can be run directly by either making it executable
(chmod +x ierl) and using it directly (./ierl) or starting it explicitly
with escript ierl (needed on Windows, for example). It will present the
available commands and backends.

To install an Erlang kernel, run

./ierl install erlang

Analogously kernels for LFE and Elixir can be installed.

To specify the name of the installed kernelspec, pass it using --name. By
default it will match the backend name (so erlang, elixir or lfe).

./ierl install erlang --name my_erlang_kernel

Remoting is also supported. Pass the node to connect to via --node and the
cookie to use via --cookie.

./ierl install erlang --node remote_node@REMOTEHOST --cookie my_secret_cookie

If no name is given, it will be inferred from the kernel name and the node the
kernel is supposed to run against.

The installed kernels will be immediately available in the Jupyter Notebook, to
use them in the console run

jupyter console --kernel my_erlang_kernel

Building

Clone this repository and run

./_download_rebar3.sh

to download the most current rebar3. After this, run

./rebar3 escriptize

to download the dependencies and compile the escript. It will be created in
_build/default/bin/ierl.

For development it might make sense to check out a local instance of
erlang-jupyter by running

./_checkout_jupyter.sh