{"id":13626087,"url":"https://github.com/archseer/enigma","last_synced_at":"2025-04-12T20:42:06.006Z","repository":{"id":146044801,"uuid":"161794751","full_name":"archseer/enigma","owner":"archseer","description":"An Erlang VM implementation in Rust","archived":false,"fork":false,"pushed_at":"2022-01-12T11:28:33.000Z","size":5213,"stargazers_count":1067,"open_issues_count":19,"forks_count":41,"subscribers_count":54,"default_branch":"master","last_synced_at":"2025-04-03T23:11:55.114Z","etag":null,"topics":["elixir","erlang","erlang-vm","rust","virtual-machine","vm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/archseer.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}},"created_at":"2018-12-14T14:24:50.000Z","updated_at":"2025-03-29T05:28:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"33b6756c-027b-49ed-9e36-76d4a1358cb8","html_url":"https://github.com/archseer/enigma","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archseer%2Fenigma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archseer%2Fenigma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archseer%2Fenigma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archseer%2Fenigma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/archseer","download_url":"https://codeload.github.com/archseer/enigma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631668,"owners_count":21136554,"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","erlang","erlang-vm","rust","virtual-machine","vm"],"created_at":"2024-08-01T21:02:09.672Z","updated_at":"2025-04-12T20:42:05.976Z","avatar_url":"https://github.com/archseer.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"![Enigma](/enigma.png)\n\nEnigma VM\n=========\n\n[![Build status](https://api.travis-ci.org/archseer/enigma.svg?branch=master)](https://travis-ci.org/archseer/enigma)\n[![Windows build status](https://ci.appveyor.com/api/projects/status/github/archseer/enigma?svg=true)](https://ci.appveyor.com/project/archseer/enigma)\n\nAn implementation of the Erlang VM in Rust. We aim to be complete, correct and\nfast, in that order of importance.\n\nOTP 22+ compatible (sans the distributed bits for now) \u0026mdash; all your code\nshould eventually run on Enigma unchanged. Deprecated opcodes won't be\nsupported.\n\n## Why?\n\nBecause it's fun and I've been learning a lot. BEAM and HiPE are awesome, but\nthey're massive (~300k SLOC). A small implementation makes it easier for new\npeople to learn Erlang internals. We also get a platform to quickly iterate on\nideas for inclusion into BEAM.\n\n## Installation\n\nOnly prerequisite to building Enigma is Rust. Use [rustup](https://rustup.rs/)\nto install the latest nightly rust. At this time we don't support stable / beta\nanymore, because we're relying on async/await, which is scheduled to run in\nstable some time in Q3 2019.\n\nTo boot up OTP you will also need to compile the standard library. At the\nmoment, that relies on the BEAM build system:\n\n```bash\ngit submodule update --init --depth 1\ncd otp\n/otp_build setup -a\nmake libs\nmake local_setup\n```\n\nWe hope to simplify this step in the future (once enigma can run the compiler).\n\nRun `cargo run` to install dependencies, build and run the VM. By default, it\nwill boot up the erlang shell ([iex also works, but has some rendering bugs](https://asciinema.org/a/zIjbf5AJx9YxEycyl9ij5ISVM)).\n\nExpect crashes, but a lot of the functionality is already available.\n\nPre-built binaries for various platforms will be available, once we reach a certain level of stability.\n\n## Feature status\n\nWe implement most of the opcodes, and about half of all BIFs. You can view\na detailed progress breakdown on [opcodes](/notes/opcodes.org) or [BIFs](/notes/bifs.org).\n\n#### Roadmap\n\n- [x] Get the full OTP kernel/stdlib to boot (`init:start`).\n- [x] Get the Eshell to run.\n- [x] Get OTP tests to run (works with a custom runner currently).\n- [x] Get the erlang compiler to work.\n- [x] Get IEx to run.\n- [ ] Get OTP tests to pass.\n\n#### Features\n\n- [x] Floating point math\n- [x] Spawn \u0026 message sending\n- [x] Lambdas / anonymous functions\n- [x] Exceptions \u0026 stack traces\n- [x] Process dictionary\n- [x] Signal queue\n- [x] Links \u0026 monitors\n- [ ] Timers\n- [x] Maps\n- [x] Binaries\n- [ ] File IO\n    - [x] open/read/close/read_file/write\n    - [ ] Filesystem interaction\n- [ ] [External NIFs](http://erlang.org/doc/man/erl_nif.html)\n- [ ] Ports (might never be fully supported, we provide a few boot-critical ones as builtins: tty, fd)\n- [ ] External Term representation\n  - [x] Decoding\n  - [ ] Encoding\n- [ ] ETS\n  - [x] PAM implementation\n  - [x] All table types partially, but we do not provide any concurrency guarantees\n- [ ] Regex (some support exists for basic matching)\n- [ ] Garbage Collection (arena-based per-process at the moment)\n- [ ] inet via socket nifs\n- [ ] Code reloading\n- [ ] Tracing/debugging support\n- [ ] Load-time instruction transform\n- [x] Load-time instruction specialization engine\n\n### Goals, ideas \u0026 experiments\n\nProcess scheduling is implemented on top of rust futures:\n- A process is simply a long running future, scheduled on top of\n    tokio-threadpool work-stealing queue\n- A timer is a delay/timeout future relying on tokio-timer time-wheel\n- Ports are futures we can await on\n- File I/O is AsyncRead/AsyncWrite awaitable\n- NIF/BIFs are futures that yield at certain points to play nice with reductions\n    (allows a much simpler yielding implementation)\n\nFuture possibilities:\n- Write more documentation about more sparsely documented BEAM aspects (binary matching, time wheel, process monitors, ...)\n- Explore using immix as a GC for Erlang\n- Eir runtime\n- JIT via Eir\n- BIF as a generator function (yield to suspend/on reduce)\n- Provide built-in adapter modules for [hyper](https://github.com/hyperium/hyper) as a Plug Adapter / HTTP client.\n- Cross-compile to WebAssembly ([runtime](https://github.com/rustasync/runtime/))\n\n#### Initial non-goals\n\nUntil the VM doesn't reach a certain level of completeness, it doesn't make sense to consider these.\n\n- Distributed Erlang nodes\n- Tracing / debugging support\n- BEAM compatible NIFs / FFI\n\nNote: NIF/FFI ABI compatibility with OTP is going to be quite some work. But,\na rust-style NIF interface will be available. It would also probably be possible\nto make an adapter compatible with [rustler](https://github.com/rusterlium/rustler).\n\n## Contributing\n\nContributors are very welcome!\n\nThe easiest way to get started is to look at the `notes` folder and pick a BIF\nor an opcode to implement. Take a look at `src/bif.rs` and the `bif` folder on\nhow other BIFs are implemented. There's also a few issues open with the `good\nfirst issue` tag, which would also be a good introduction to the internals.\n\nAlternatively, search the codebase for `TODO`, `FIXME` or `unimplemented!`,\nthose mark various places where a partial implementation exists, but a bit more\nwork needs to be done.\n\nTest coverage is currently lacking, and there's varying levels of documentation; I will be addressing these soon.\n\nWe also have a #enigma channel on the [Elixir Slack](https://elixir-slackin.herokuapp.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchseer%2Fenigma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchseer%2Fenigma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchseer%2Fenigma/lists"}