{"id":15551374,"url":"https://github.com/pprzetacznik/ielixir","last_synced_at":"2025-05-16T15:06:34.946Z","repository":{"id":34649467,"uuid":"38615179","full_name":"pprzetacznik/IElixir","owner":"pprzetacznik","description":"Jupyter's kernel for Elixir programming language","archived":false,"fork":false,"pushed_at":"2024-05-26T13:23:28.000Z","size":527,"stargazers_count":362,"open_issues_count":13,"forks_count":42,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-16T15:06:34.389Z","etag":null,"topics":["elixir","jupyter","jupyter-kernels","jupyter-notebook","repl"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pprzetacznik.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-06T11:39:08.000Z","updated_at":"2025-04-12T13:11:50.000Z","dependencies_parsed_at":"2022-07-13T01:30:33.380Z","dependency_job_id":"22d79998-8e45-4e75-87e8-2e66ed8b384f","html_url":"https://github.com/pprzetacznik/IElixir","commit_stats":{"total_commits":258,"total_committers":18,"mean_commits":"14.333333333333334","dds":"0.13953488372093026","last_synced_commit":"ef96064e4a6958fbed85dad724342c973c84c6ec"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprzetacznik%2FIElixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprzetacznik%2FIElixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprzetacznik%2FIElixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprzetacznik%2FIElixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pprzetacznik","download_url":"https://codeload.github.com/pprzetacznik/IElixir/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553960,"owners_count":22090417,"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":["elixir","jupyter","jupyter-kernels","jupyter-notebook","repl"],"created_at":"2024-10-02T14:04:39.264Z","updated_at":"2025-05-16T15:06:34.929Z","avatar_url":"https://github.com/pprzetacznik.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"IElixir\n=======\n\nJupyter's kernel for Elixir\n\n[![Build Status](https://travis-ci.org/pprzetacznik/IElixir.svg?branch=master)](https://travis-ci.org/pprzetacznik/IElixir)\n[![IElixir CI](https://github.com/pprzetacznik/IElixir/workflows/IElixir%20CI/badge.svg)](https://github.com/pprzetacznik/IElixir/actions?query=workflow%3A\"IElixir+CI\")\n[![IElixir Docker](https://github.com/pprzetacznik/IElixir/workflows/IElixir%20Docker/badge.svg)](https://github.com/pprzetacznik/IElixir/actions?query=workflow%3A\"IElixir+Docker\")\n[![Inline docs](http://inch-ci.org/github/pprzetacznik/IElixir.svg?branch=master)](http://inch-ci.org/github/pprzetacznik/IElixir)\n[![Coverage Status](https://coveralls.io/repos/github/pprzetacznik/IElixir/badge.svg?branch=master)](https://coveralls.io/github/pprzetacznik/IElixir?branch=master)\n[![Join the chat at https://gitter.im/pprzetacznik/IElixir](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/pprzetacznik/IElixir?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nHex: https://hex.pm/packages/ielixir.\n\nPlease see generated documentation for implementation details: http://hexdocs.pm/ielixir/.\n\n## Getting Started\n\n### Table of contents\n\n* [Configure Jupyter](#configure-jupyter)\n* [Configure IElixir](#configure-ielixir)\n* [Install Kernel](#install-kernel)\n* [Use IElixir](#use-ielixir)\n* [Package management with Boyle](#package-management-with-boyle)\n* [Developement mode](#developement-mode)\n* [Generate documentation](#generate-documentation)\n* [Docker](#docker)\n* [Some issues](#some-issues)\n* [Contribution](#contribution)\n* [References](#references)\n* [License](#license)\n\n### Configure Jupyter\n\nI recommend you to use `virtualenv` and `virtualenvwrapper` for this project to isolate dependencies between this and other projects however you may also work without this if you don't like this.\n```Bash\n$ pip install virtualenv virtualenvwrapper\n```\nNow you need to load `virtualenvwrapper.sh` script into your current environment. I recommend you to add this like as well to the `~/.bash_profile.sh` script to have this script loaded every time you open fresh bash.\n```Bash\n$ source /usr/local/bin/virtualenvwrapper.sh\n```\n\nNow using our new tools we can easily create isolated virtual environment for jupyter installation.\n```Bash\n$ mkvirtualenv jupyter-env\n$ workon jupyter-env\n(jupyter-env) $ pip install jupyter\n```\n\n### Configure IElixir\n\nClone IElixir repository and prepare the project\n```Bash\n$ git clone https://github.com/pprzetacznik/IElixir.git\n$ cd IElixir\n$ mix deps.get\n$ mix test\n$ MIX_ENV=prod mix compile\n```\n\nIf you're meeting problem with missing zeromq header files then you should install it. [More](#zeromq-header-files-missing).\n\nRunning all tests, including longer ones that requires more time for evaluation:\n```Bash\n$ mix test --include skip\n```\n\nThere may be also need to install rebar before IElixir installation, you can do this with command:\n```Bash\nmix local.rebar --force\n```\nAfter this you may need to add `~/.mix/` to your `$PATH` variable if you don't have `rebar` visible yet outside `~/.mix/` directory.\n\n### Install Kernel\n\nSimply run installation script to create file `kernel.json` file in `./resouces` directory and bind it to the jupyter:\n```Bash\n$ ./install_script.sh\n```\n\n### Use IElixir\n\nRun Jupyter console with following line:\n```Bash\n(jupyter-env) $ jupyter console --kernel ielixir\n```\n\nTo quit IElixir type `Ctrl-D`.\n\nRun Jupyter Notebook with following line:\n```Bash\n(jupyter-env) $ jupyter notebook resources/example.ipynb\n```\n\nGo to [http://localhost:8888/](http://localhost:8888/) site (by default) in your browser and pick IElixir kernel:\n\n![Pick IElixir](/resources/jupyter_pick_kernel.png?raw=true)\n\nEvaluate some commands in your new notebook:\n\n![IElixir basics](/resources/jupyter_ielixir_matrex_demo.png?raw=true)\n\n### Magic commands\n\nYou can also use `ans` variable to access output of previous cell. Moreover, if you want to access any cell which you can do it using it's number by calling `out` map, eg. `out[1]`.\n\n### Package management with Boyle\n\nYou can manage your packages in runtime with Boyle. Name of the package honours remarkable chemist, Robert Boyle. This package allows you to manage your Elixir virtual enviromnent without need of restarting erlang virtual machine. Boyle installs environment into `./envs/you_new_environment` directory and creates new mix project there with requested dependencies. It keeps takes care of fetching, compiling and loading/unloading modules from dependencies list of that environment.\n\nYou can also use this environment as a separate mix project and run it interactively with `iex -S mix` from the environment directory.\n\n\nCreating new Elixir virtual environment\n```Elixir\niex\u003e Boyle.mk(\"my_new_environment\")\n{:ok, [\"my_new_environment\"]}\n```\n\nList available virtual environments\n```Elixir\niex\u003e Boyle.list()\n{:ok, [\"my_new_environment\"]}\n```\n\nActivate virtual environment\n```Elixir\niex\u003e Boyle.activate(\"my_new_environment\")\n:ok\n```\n\nInstall new package in virtual environment and use new package\n```Elixir\niex\u003e Boyle.install({:number, \"~\u003e 0.5.7\"})\n:ok\niex\u003e Number.Currency.number_to_currency(2034.46)\n\"$2,034.46\"\n```\n\nDeactivate virtual environment and unload packages installed within that virtual environment\n```Elixir\niex\u003e Boyle.deactivate()\n:ok\niex\u003e Number.Currency.number_to_currency(2034.46)\n** %UndefinedFunctionError{arity: 1, exports: nil, function: :number_to_currency, module: Number.Currency, reason: nil}\n```\n\nAdditional resources:\n* [Notebook with Boyle examples](https://github.com/pprzetacznik/IElixir/blob/master/resources/boyle%20example.ipynb)\n* [Notebook with Boyle examples with usage of Matrex library](https://github.com/pprzetacznik/IElixir/blob/master/resources/boyle%20example%20-%20matrex%20installation%20and%20usage.ipynb)\n* [Notebook with inline image examples with usage of Gnuplot library](https://github.com/pprzetacznik/IElixir/blob/master/resources/inlineplot%20example%20-%20gnuplot.ipynb)\n\n### Developement mode\n\nIf you want to see requests passing logs please use `dev` environment to see what is happening in the background.\n\n```Bash\n(jupyter-env) $ MIX_ENV=dev jupyter console --kernel ielixir\n```\n\n### Generate documentation\n\nRun following command and see `doc` directory for generated documentation in HTML:\n```Bash\n$ MIX_ENV=docs mix docs\n```\n\n### Docker\n\nYou can find docker image at [pprzetacznik/ielixir](https://hub.docker.com/r/pprzetacznik/ielixir).\n\nRunning jupyter notebook:\n```\n$ docker run -p 8888:8888 --hostname localhost -v /my/workspace:/home/jovyan/work pprzetacznik/ielixir\n```\n\nDocker image is based on following images:\n* [jupyter/base-notebook image](https://hub.docker.com/r/jupyter/base-notebook/) - this is image use as a base for ielixir image,\n* [elixir image](https://hub.docker.com/_/elixir/) - some installation parts were taken from dockerfile used for this image,\n* [pprzetacznik/ielixir-requirements image](https://hub.docker.com/r/pprzetacznik/ielixir-requirements/) - this image resolves all dependencies for jupyter and elixir so only IElixir installation is left.\n\nIf you would like to make some changes to the images you can find dockerfiles in:\n* docker/ielixir - for dockerfile source of pprzetacznik/ielixir image,\n* docker/ielixir-requirements - for dockerfile source of pprzetacznik/ielixir-requirements image.\n\nElixir builds taken from [hex.pm builds.txt](https://repo.hex.pm/builds/elixir/builds.txt).\n\n#### Other docker images worth seeing\n\n* [Dockerfile for smaller image based on alpine](https://github.com/cprieto/docker-jupyter/blob/master/elixir/Dockerfile)\n\n### Some issues\n\n#### ZeroMQ header files missing\n\n```\n===\u003e /home/travis/build/bryanhuntesl/IElixir/deps/erlzmq/c_src/erlzmq_nif.c:24:17: fatal error: zmq.h: No such file or directory\n #include \"zmq.h\"\n                 ^\ncompilation terminated.\n```\n\nInstall ZeroMQ development package for you operating system.\n\n* On RHEL/Centos/Fedora `dnf install zeromq-devel`\n* On OSX `brew install zmq`\n* On Ubuntu `apt-get install libzmq3-dev`\n* On Alpine Linux `apk add zeromq-dev`\n\n#### Erlang configuration\n\nThere may be need to run IElixir kernel with specific erlang attribute which can be turned on by setting variable:\n```Bash\nELIXIR_ERL_OPTIONS=\"-smp enable\"\n```\nThis option has been included inside `install_script.sh` and `start_script.sh` scripts.\n\n#### Listing all available jupyter kernels.\n\n```Bash\n$ jupyter kernelspec list\n```\n\n### Contribution\n\n* Try to write some description of the feature or bug fix you're working in pull request's description and concise description of new modules or functions in moduledoc annotations,\n* Please follow Elixir style guides to keep style clear, consider Elixir and Phoenix source code as the style ground truth,\n* Keep as little comments as you can, comments tend to expire so try to use doctests instead to show how your code works,\n* Write some unit tests for your code but don't try to test private functions, class tests are bad and units tests are good - https://blog.arkency.com/2014/09/unit-tests-vs-class-tests/\n\n### References\n\nSome useful articles:\n\n* [IElixir Notebook in Docker](https://mattvonrocketstein.github.io/heredoc/ielixir-notebook-in-docker.html)\n* [Hydrogen plugin for Atom](https://atom.io/packages/hydrogen)\n* [Installation guide](http://blog.jonharrington.org/elixir-and-jupyter/)\n* [Jupyter Notebooks with Elixir and RDF](https://medium.com/@tonyhammond/jupyter-notebooks-with-elixir-and-rdf-598689c2dad3)\n* [Making Graphs using Elixir inside Jupyter Notebook snapshot from 2019/04 on Internet Archive](https://web.archive.org/web/20191228085409/http://aipotato.com/2019/04/making-graphs-using-elixir-inside-jupyter-notebook/)\n\nI was inspired by following codes and articles:\n\n* [https://github.com/pminten/ielixir](https://github.com/pminten/ielixir)\n* [https://github.com/robbielynch/ierlang](https://github.com/robbielynch/ierlang)\n* [https://github.com/dsblank/simple_kernel](https://github.com/dsblank/simple_kernel)\n* [http://andrew.gibiansky.com/blog/ipython/ipython-kernels/](http://andrew.gibiansky.com/blog/ipython/ipython-kernels/)\n* [https://ipython.org/ipython-doc/dev/development/messaging.html](https://ipython.org/ipython-doc/dev/development/messaging.html)\n\n### License\n\nCopyright 2015 Piotr Przetacznik.\nIElixir source code is released under Apache 2 License.\nCheck [NOTICE](NOTICE) and [LICENSE](LICENSE) files for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpprzetacznik%2Fielixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpprzetacznik%2Fielixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpprzetacznik%2Fielixir/lists"}