{"id":13587018,"url":"https://github.com/maximecb/uvm","last_synced_at":"2025-04-09T05:09:30.658Z","repository":{"id":73195204,"uuid":"502388309","full_name":"maximecb/uvm","owner":"maximecb","description":"Fun, portable, minimalistic virtual machine.","archived":false,"fork":false,"pushed_at":"2024-09-13T19:00:25.000Z","size":1938,"stargazers_count":554,"open_issues_count":4,"forks_count":19,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-04-02T04:02:41.922Z","etag":null,"topics":["bytecode","bytecode-interpreter","compiler","containerization","emulation","emulator","interpreter","jit-compiler","permacomputing","rust","sandboxing","uvm","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/maximecb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["maximecb"]}},"created_at":"2022-06-11T15:39:49.000Z","updated_at":"2025-03-29T21:47:01.000Z","dependencies_parsed_at":"2023-10-31T02:21:40.570Z","dependency_job_id":"34ab1d73-152b-48c2-a522-a61965931bbb","html_url":"https://github.com/maximecb/uvm","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/maximecb%2Fuvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximecb%2Fuvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximecb%2Fuvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximecb%2Fuvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximecb","download_url":"https://codeload.github.com/maximecb/uvm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980837,"owners_count":21027808,"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":["bytecode","bytecode-interpreter","compiler","containerization","emulation","emulator","interpreter","jit-compiler","permacomputing","rust","sandboxing","uvm","virtual-machine"],"created_at":"2024-08-01T15:05:58.131Z","updated_at":"2025-04-09T05:09:30.634Z","avatar_url":"https://github.com/maximecb.png","language":"Rust","readme":"# UVM\n\n**NOTE: this project is very much a work in progress. You're likely to run\ninto bugs and missing features. I would like to find collaborators who share the vision\nand want to help me make it happen.**\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"media/the_grid.png\" height=180\u003e\u0026nbsp;\n    \u003cimg src=\"media/attackers.png\" height=180\u003e\u0026nbsp;\n    \u003cimg src=\"media/chess.png\" height=180\u003e\n\u003c/p\u003e\n\nA simple, minimalistic virtual machine designed to run self-contained applications. UVM is intended as a platform to distribute\nprograms that will not break and to combat code rot. It aims to be conceptually simple, easy to understand, easy\nto target, fun to work with and approachable to newcomers. It may also be valuable as a teaching tool or as a platform\nto experiment with. There is a short 4-minute [overview of UVM](https://www.youtube.com/watch?v=q9-o45B_qsA)\non YouTube if you'd like to see a quick survey.\n\nContents:\n- [Features](#features)\n- [Build Instructions](#build-instructions)\n- [Codebase Organization](#codebase-organization)\n- [Design and Architecture](doc/design.md)\n- [Subsystems and System Calls](doc/syscalls.md)\n- [Vision and Motivation](doc/vision.md)\n- [Planning and Evolution](doc/planning.md)\n\nIf you think that UVM is cool, you can support my work via [GitHub Sponsors](https://github.com/sponsors/maximecb) :heart:\n\n## Features\n\nCurrent features:\n- Stack-based bytecode interpreter\n- Variable-length instructions for compactness\n- Untyped design for simplicity\n- Little-endian byte ordering (like x86, ARM \u0026 RISC-V)\n- 32-bit and 64-bit integer ops, 32-bit floating-point support\n- Separate flat, linear address spaces for code and data ([Harvard architecture](https://en.wikipedia.org/wiki/Harvard_architecture))\n- Thread-based parallelism\n- Built-in, easy to use [assembler](vm/src/asm.rs) with a [simple syntax](vm/examples)\n- Event-driven event execution model compatible with async operations\n- Easy to use frame buffer to draw RGB graphics with no boilerplate\n- Easy to use audio output API with no boilerplate\n\nPlanned future features:\n- Simple networking API\n- Capability system to safely sandbox apps without granting access to entire computer\n- Ability to compile without SDL and without graphics/audio for headless server-side use\n- Ability to encode metadata such as author name and app icon into app image files\n- Ability to suspend running programs and save them to a new app image file\n\n## Build Instructions\n\nDependencies:\n- The [Rust toolchain](https://www.rust-lang.org/tools/install)\n- The [SDL2 libraries](https://wiki.libsdl.org/SDL2/Installation)\n\n### Installing Rust and SDL2 on macOS\n\nInstall the SDL2 package:\n```sh\nbrew install sdl2\n```\n\nAdd this to your `~/.zprofile`:\n```sh\nexport LIBRARY_PATH=\"$LIBRARY_PATH:$(brew --prefix)/lib\"\n```\n\nInstall the Rust toolchain:\n```sh\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\n### Installing Rust and SDL2 on Debian/Ubuntu\n\nInstall the SDL2 package:\n```sh\nsudo apt-get install libsdl2-dev\n```\n\nInstall the Rust toolchain:\n```sh\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\n### Installing Rust and SDL2 on Windows\n\nFollow the Windows-specific instructions to [install the Rust toolchain](https://www.rust-lang.org/tools/install).\n\nGet `SDL2.dll` from one of [SDL2 Releases](https://github.com/libsdl-org/SDL/releases).\n\nCopy `SDL2.dll` (unzip) to the `vm/` folder.\n\n### Compiling the Project\n\n```sh\ncd vm\ncargo build\n```\n\nTo run an [asm file](vm/examples) with UVM:\n```sh\ncargo run examples/fizzbuzz.asm\n```\n\nThere is also a toy C compiler in the `ncc` directory, along with many [example C programs](ncc/examples) that run on UVM:\n```sh\ncd ncc\n./build_and_run.sh examples/snake.c\n```\n\n### Running the Test Suite\n\nRun `cargo test` from the `vm`, and `ncc` directories.\n\n## Codebase Organization\n\nThe repository is organized into a 3 different subprojects, each of which is a Rust codebase which can be compiled with `cargo`:\n\n- `/vm` : The implementation of the UVM virtual machine itself\n  - [`/vm/examples/*`](vm/examples): Example assembly programs that can be run by UVM\n- `/ncc`: An implementation of a toy C compiler that outputs UVM assembly\n  - [`/ncc/README.md`](ncc/README.md): documentation for the NCC compiler.\n  - [`/ncc/examples/*`](ncc/examples): Example C source files that can be compiled by NCC\n- `/api`: A system to document and automatically export bindings for UVM system calls and constants.\n  - `/api/syscalls.json`: Declarative list of system calls exposed by UVM.\n- `/doc`: Markdown documentation for UVM\n  - [`/doc/syscalls.json`](doc/syscalls.md): List of system calls and constants accessible to UVM programs\n\nThe `ncc` compiler is, at the time of this writing, incomplete in that it lacks some C features and the error messages need improvement. This compiler\nwas implemented to serve as an example of how to write a compiler that targets UVM, and to write some library code to be used by other programs. Over\ntime, the `ncc` compiler will be improved. Despite its limitations, it is still usable to write small programs. Contributions to it are welcome.\n\nThe `api` directory contains JSON files that represent a declarative list of system calls, constants and the permission system that UVM exposes\nto programs running on it. This is helpful for documentation purposes, or if you want to build a compiler that targets UVM. The directory also contains\ncode that automatically generates [markdown documentation](doc/syscalls.md), Rust constants and [C definitions](ncc/include/uvm/syscalls.h) for system calls.\n\n## Open Source License\n\nThe code for UVM, NCC and associated tools is shared under the [Apache-2.0 license](https://github.com/maximecb/uvm/blob/main/LICENSE).\n\nThe examples under the `vm/examples` and `ncc/examples` directories are shared under the [Creative Commons CC0](https://creativecommons.org/publicdomain/zero/1.0/) license.\n\n## Contributing\n\nThere is a lot of work to be done to get this project going and contributions are welcome.\n\nA good first step is to look at open issues and read the available documentation. Another easy way to contribute\nis to create new example programs showcasing cool things you can do with UVM, or to open issues to report bugs.\nIf you do report bugs, please provide as much context as possible, and the smallest reproduction you can\ncome up with.\n\nYou can also search the codebase for TODO or FIXME notes:\n```sh\ngrep -IRi \"todo\" .\n```\n\nIn general, smaller pull requests are easier to review and have a much higher chance of getting merged than large\npull requests. If you would like to add a new, complex feature or refactor the design of UVM, I recommend opening\nan issue or starting a discussion about your proposed change first.\n\nAlso please keep in mind that one of the core principles of UVM is to minimize dependencies to keep the VM easy\nto install and easy to port. Opening a PR that adds dependencies to multiple new packages and libraries is\nunlikely to get merged. Again, if you have a valid argument in favor of doing so, please open a discussion to\nshare your point of view.\n","funding_links":["https://github.com/sponsors/maximecb"],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximecb%2Fuvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximecb%2Fuvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximecb%2Fuvm/lists"}