Erlang/OTP Communications in Clojure (wraps jiface + JInterface)
This project provides a final solution to the Clojure
The jiface low-level API solves this to a
certain extent, but
jiface requires that programmers perform all their own type
conversions, manual creation of nodes and mboxes, etc.
The Clojang library, however, provides an interface that is not only
syntactically idiomatic Clojure (not unlike the jiface library), but even more
so, provides developers with the same level of convenience they have come to
expect when using Clojure libraries in general, without the need to perform
many manual operations in order to handle Erlang data.
For a comparison of JInterface, the low-level
jiface API, and the high-level
clojang API, see
the APIs summary page.
The default (and tested) version combinations are as follows:
|Clojang||jiface||JInterface||Erlang Release||Erlang Version (erts)|
|0.4.0||0.4.0||1.7.1||19.2, 19.3||8.2, 8.3|
|0.2.0||0.2.0||1.7.1||19.1, 19.2||8.1, 8.2|
|0.1.0||0.1.0||1.6.1||18.2, 18.3||7.2, 7.3|
While other version combination may work (and existing versions may be updated
to work with different onces), those are the only ones which are supported.
rebar3 is used for the top-level builds of the project. It runs
the covers in order to build the Clojure code and create the Clojang
file. As such, to build everything -- LFE, Erlang, and Clojure -- you need
only do the following:
If you wish to build your own JInterface
.jar file and not use the one we've
uploaded to Clojars, you'll need to follow the instrucations given in the
jinterface-builder Clojang project.
There are three interactive programming environments you may start, each of
which will have full access to the project's libraries/dependencies.
$ make lfe-repl
$ rebar3 shell
$ lein clj-repl
Project documentation, including Clojang API reference docs, Javadocs for
JInterface, and the Erlang JInterface User's Guide, is availble here:
Quick links for the other docs:
- Clojang User Guides:
- jiface User's Guide -
A translation of the JInterface User's Guide (Erlang documantaion) from
Java into Clojure; this is refered to as the Clojang low-level API.
- Clojang User's Guide -
An adaptation of the jiface User's Guide which demonstrates the improved
API that Clojang offers
- JInterface User's Guide - The JInterface (Java support for Erlang Ports) documentation provided in
- Jinterface Javadocs -
Javadoc-generated API documentation built from the JInterface source code
Using Clojang in a project is just like any other Clojure library. Just add
the following to the
:dependencies in your
For the Erlang/LFE side of things, you just need to add the Github URL to your
rebar.config file, as with any other rebar-based Erlang VM project.
As for actual code usage, the documentation section provides links to
developer guides and API references, but below are also provided some quick
Here, we'll send a message to our own (default) node's message box, and then
(require '[clojang.core :refer [! receive self]])
(! [(self) :hello-word])
(let [[pid msg] (receive)]
To show remote usage, from an LFE (Lisp Flavoured Erlang) REPL:
(clojang-lfe@mndltl01)> (! #(default clojang@host) `#(,(self) hej!))
Then back in Clojure, the same that we used before, but we'll capture the
process id that we sent from LFE and then send another message back to it:
(let [[pid msg] (receive)]
(! pid "hello, world!"))
Then, returning to the LFE REPL, we check that we received the message from
Shell got "hello, world!"
All the tests may be run with just one command:
$ rebar3 eunit
This will not only run Erlang and LFE unit tests, it also runs the Clojure
unit tests for Clojang.
Clojure Test Selectors
If you would like to be more selective in the types of Clojang tests which get
run, you may be interested in reading this section.
The Clojang tests use metadata annotations to indicate whether they are unit,
system, or integration tests. to run just the unit tests, you can do any one
of the following, depending upon what you're used to:
$ lein test
$ lein test :unit
$ lein test :default
To run just the system tests:
$ lein test :system
And, similarly, just the integration tests:
$ lein test :integtration
To run everything:
$ lein test :all
This is what is used by the
rebar3 configuration to run the Clojang tests.
A donation account for supporting development on this project has been set up
on Liberapay here:
You can learn more about Liberapay on its Wikipedia entry or on the
service's "About" page.
Copyright © 2018 The Clojang Project
Copyright © 2016-2017 Duncan McGreggor
Distributed under the Apache License Version 2.0.