{"id":13723542,"url":"https://github.com/clojang/jiface","last_synced_at":"2025-04-13T02:42:17.802Z","repository":{"id":62433113,"uuid":"57454034","full_name":"clojang/jiface","owner":"clojang","description":"A Clojure-idiomatic wrapper around Erlang's JInterface","archived":false,"fork":false,"pushed_at":"2019-05-21T03:39:10.000Z","size":2114,"stargazers_count":27,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T20:06:15.710Z","etag":null,"topics":["beam","clojure","distributed-systems","erlang","java","jinterface","jvm","otp"],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clojang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-30T17:29:58.000Z","updated_at":"2021-07-03T19:00:55.000Z","dependencies_parsed_at":"2022-11-01T21:15:35.795Z","dependency_job_id":null,"html_url":"https://github.com/clojang/jiface","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojang%2Fjiface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojang%2Fjiface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojang%2Fjiface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojang%2Fjiface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clojang","download_url":"https://codeload.github.com/clojang/jiface/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657856,"owners_count":21140843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beam","clojure","distributed-systems","erlang","java","jinterface","jvm","otp"],"created_at":"2024-08-03T01:01:42.701Z","updated_at":"2025-04-13T02:42:17.778Z","avatar_url":"https://github.com/clojang.png","language":"Clojure","readme":"# jiface\n[![Build Status][travis-badge]][travis]\n[![Dependencies Status][deps-badge]][deps]\n[![Clojars Project][clojars-badge]][clojars]\n\n*Erlang's JInterface in Idiomatic Clojure*\n\n[![Project logo][logo]][logo-large]\n\n\n#### Contents\n\n* [Introduction](#introduction-)\n* [Dependencies](#dependencies-)\n* [Building](#building-)\n* [Documentation](#documentation-)\n* [Usage](#usage-)\n* [Running Tests](#running-tests-)\n* [Erlang, Clojure, and JInterface](#erlang-clojure-and-jinterface-)\n* [Donating](#donating-)\n* [License](#license-)\n\n\n## Introduction [\u0026#x219F;](#contents)\n\nThis project provides a solution to the Clojure\n[JInterface Problem](https://github.com/clojang/jiface/wiki/The-JInterface-Problem).\nWhile JInterface is an invaluable tool for projects that need to have JVM and\nErlang VM languages communicating with each other, it is rather verbose and\ncumbersome to do so in Clojure. The syntactical burden is often enough to\ndiscourage experimentation and play (essential ingredients for innovation).\nThe primary goal of jiface is to make it easier to write Clojure programs that\nneed to communicate with Erlang nodes (including LFE and Elixir).\n\nFor a comparison of JInterface, the low-level `jiface` API, and the high-level\n`clojang` API, see\n[the APIs summary](http://clojang.github.io/jiface/current/05-apis.html) page.\n\n\n## Changes [\u0026#x219F;](#contents)\n\nFor details on breaking changes made between jiface releases, see\n[the changes](http://clojang.github.io/jiface/current/80-changes.html) page.\n\n\n## Dependencies [\u0026#x219F;](#contents)\n\n* Java\n* Erlang (`epmd` in particular)\n* lein\n\nThe default (and tested) version combinations are as follows:\n\n| jiface | JInterface | Erlang Release | Erlang Version (erts) |\n|--------|------------|----------------|-----------------------|\n| 0.7.0  | 1.10       | 22.0           | 10.4                  |\n| 0.6.1  | 1.9.1      | 21.3           | 10.3                  |\n| 0.6.0  | 1.9        | 21.0           | 10                    |\n| 0.5.0  | 1.8.1      | 20.3           | 9.3                   |\n| 0.4.0  | 1.7.1      | 19.2, 19.3     | 8.2, 8.3              |\n| 0.3.0  | 1.7.1      | 19.2           | 8.2                   |\n| 0.2.0  | 1.7.1      | 19.1, 19.2     | 8.1, 8.2              |\n| 0.1.0  | 1.6.1      | 18.2, 18.3     | 7.2, 7.3              |\n\nWhile other version combination may work (and existing versions may be updated\nto work with different onces), those are the only ones which are supported.\n\nVersions notes:\n\n* The `lein` dep for the jiface 0.6.1 release is `[clojang/jiface \"0.6.1-1\"]`\n* The `lein` dep for the JInterface 1.9.1 release is\n  `[clojang/erlang-jinterface \"1.9.1-3\"]`\n* The `lein` dep for the JInterface 1.10 release is\n  `[clojang/erlang-jinterface \"1.10-1\"]`\n\n## Building [\u0026#x219F;](#contents)\n\n``rebar3`` is used for the top-level builds of the project. It runs ``lein``\nunder the covers in order to build the Clojure code and create the\njiface``.jar`` file. As such, to build everything -- LFE, Erlang, and Clojure\n-- you need only do the following:\n\n* ``rebar3 compile``\n\nIf you wish to build your own JInterface ``.jar`` file and not use the one\nwe've uploaded to Clojars, you'll need to follow the instructions given in the\ndocumentation here:\n\n* [Building JInterface for Clojure](http://clojang.github.io/jiface/current/80-building-jinterface.html)\n\n\n## Documentation [\u0026#x219F;](#contents)\n\nProject documentation, including jiface API reference docs, Javadocs for\nJInterface, and the Erlang JInterface User's Guide, is available here:\n\n* [http://clojang.github.io/jiface/current/](http://clojang.github.io/jiface/current/)\n\nOf particular note:\n\n* [jiface User's Guide](http://clojang.github.io/jiface/current/10-low-level-api.html) - A translation of the *JInterface User's Guide* (Erlang documentation) from Java into Clojure\n* [JInterface User's Guide](http://clojang.github.io/jiface/current/erlang/jinterface_users_guide.html) - The JInterface documentation provided in Erlang distributions\n* [JInterface Javadocs](http://clojang.github.io/jiface/current/erlang/java) - Javadoc-generated API documentation built from the JInterface source code\n\nHigh-level API docs:\n\n* [Clojang User's Guide](http://clojang.github.io/clojang/current/10-low-level.html) -\n  An adaptation of the *jiface User's Guide* for the mid-level idiomatic Clojure API\n\n\n## Usage [\u0026#x219F;](#contents)\n\nUsing jiface in a project is just like any other Clojure library. Just add the\nfollowing to the ``:dependencies`` in your ``project.clj`` file:\n\n[![Clojars Project](https://img.shields.io/clojars/v/clojang/jiface.svg)](https://clojars.org/clojang/jiface)\n\nFor the Erlang/LFE side of things, you just need to add the Github URL to your\n`rebar.config` file, as with any other rebar-based Erlang VM project.\n\nAs for actual code usage, the documentation section provides links to\ndeveloper guides and API references, but below is quick example.\n\nStart LFE in distributed mode:\n\n```\n$ lfe -sname clojang-lfe\nErlang/OTP 18 [erts-7.3] [source] [64-bit] [smp:4:4] [async-threads:10] ...\n\n   ..-~.~_~---..\n  (      \\\\     )    |   A Lisp-2+ on the Erlang VM\n  |`-.._/_\\\\_.-';    |   Type (help) for usage info.\n  |         g (_ \\   |\n  |        n    | |  |   Docs: http://docs.lfe.io/\n  (       a    / /   |   Source: http://github.com/rvirding/lfe\n   \\     l    (_/    |\n    \\   r     /      |   LFE v0.11.0-dev (abort with ^G)\n     `-E___.-'\n\n(clojang-lfe@mndltl01)\u003e\n```\n\nThen start up a jiface Clojure REPL:\n\n```\n$ lein repl\n```\n\nAnd paste the following:\n\n```clj\n(require '[jiface.otp.messaging :as messaging]\n         '[jiface.otp.nodes :as nodes]\n         '[jiface.erlang.types :as types]\n         '[jiface.erlang.tuple :as tuple-type])\n(def node (nodes/node \"gurka\"))\n(def mbox (messaging/mbox node))\n(messaging/register-name mbox \"echo\")\n(def msg (into-array\n           (types/object)\n           [(messaging/self mbox)\n            (types/atom \"hello, world\")]))\n(messaging/! mbox \"echo\" \"gurka\" (types/tuple msg))\n(messaging/receive mbox)\n```\n\nWhen you paste the ``receive`` function, you'll get something like this:\n\n```clj\n#object[com.ericsson.otp.erlang.OtpErlangTuple\n        0x4c9e3fa6\n        \"{#Pid\u003cgurka@mndltl01.1.0\u003e,'hello, world'}\"]\n```\n\nIn the LFE REPL, you can send a message to your new Clojure node:\n\n```cl\n(lfe@mndltl01)\u003e (! #(echo gurka@mndltl01) `#(,(self) hej!))\n#(\u003c0.35.0\u003e hej!)\n```\n\nThen back in Clojure, check the sent message and send a response:\n\n```clojure\n(def data (messaging/receive mbox))\n(def lfe-pid (tuple-type/get-element data 0))\n(messaging/! mbox lfe-pid (types/tuple msg))\n```\n\nThen, back in LFE, flush the REPL's process mbox to see what has been sent to it:\n\n```cl\n(lfe@mndltl01)\u003e (c:flush)\nShell got {\u003c5926.1.0\u003e,'hello, world'}\nok\n```\n\n\n## Running Tests [\u0026#x219F;](#contents)\n\nAll the tests may be run with just one command:\n\n```bash\n$ rebar3 eunit\n```\n\nThis will not only run Erlang and LFE unit tests, it also runs the Clojure unit tests for jiface.\n\n**Clojure Test Selectors**\n\nIf you would like to be more selective in the types of jiface tests which get\nrun, you may be interested in reading this section.\n\nThe jiface tests use metadata annotations to indicate whether they are unit,\nsystem, or integration tests. to run just the unit tests, you can do any one\nof the following, depending upon what you're used to:\n\n```bash\n$ lein test\n$ lein test :unit\n$ lein test :default\n```\n\nTo run just the system tests:\n\n```bash\n$ lein test :system\n```\n\nAnd, similarly, just the integration tests:\n\n```bash\n$ lein test :integration\n```\n\nTo run everything:\n\n```bash\n$ lein test :all\n```\n\nThis is what is used by the ``rebar3`` configuration to run the jiface tests.\n\n\n## Erlang, Clojure, and JInterface [\u0026#x219F;](#contents)\n\nIf you are interested in building your own JInterface ``.jar`` file for use\nwith a Clojure project, be sure fo check out the\n[jinterface-builder Clojang project](https://github.com/clojang/jinterface-builder).\nThe project `README` has everything you need to get started.\n\n\n## Donating [\u0026#x219F;](#contents)\n\nA donation account for supporting development on this project has been set up\non Liberapay here:\n\n* [https://liberapay.com/clojang/donate](https://liberapay.com/clojang/donate)\n\nYou can learn more about Liberapay on its [Wikipedia entry][libera-wiki] or on the\nservice's [\"About\" page][libera-about].\n\n[libera-wiki]: https://en.wikipedia.org/wiki/Liberapay\n[libera-about]: https://liberapay.com/about/\n\n\n## License [\u0026#x219F;](#contents)\n\n```\nCopyright © 2018 The Clojang Project\n\nCopyright © 2016-2017 Duncan McGreggor\n\nDistributed under the Apache License Version 2.0.\n```\n\n\n\u003c!-- Named page links below: /--\u003e\n\n[travis]: https://travis-ci.org/clojang/jiface\n[travis-badge]: https://travis-ci.org/clojang/jiface.png?branch=master\n[deps]: http://jarkeeper.com/clojang/jiface\n[deps-badge]: http://jarkeeper.com/clojang/jiface/status.svg\n[clojars]: https://clojars.org/clojang/jiface\n[clojars-badge]: https://img.shields.io/clojars/v/clojang/jiface.svg\n[logo]: https://github.com/clojang/resources/blob/master/images/logo-5-250x.png\n[logo-large]: https://github.com/clojang/resources/blob/master/images/logo-5-1000x.png\n","funding_links":["https://liberapay.com/clojang/donate","https://liberapay.com/about/"],"categories":["Languages Integration"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclojang%2Fjiface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclojang%2Fjiface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclojang%2Fjiface/lists"}