{"id":15755420,"url":"https://github.com/hmarr/hack-stack","last_synced_at":"2026-03-01T11:33:02.417Z","repository":{"id":153831473,"uuid":"628343633","full_name":"hmarr/hack-stack","owner":"hmarr","description":"💾 Software toolchain for the nand2tetris Hack computer","archived":false,"fork":false,"pushed_at":"2024-06-26T14:49:47.000Z","size":428,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-23T11:30:02.759Z","etag":null,"topics":["compiler","nand2tetris","rust"],"latest_commit_sha":null,"homepage":"https://hmarr.github.io/hack-stack/","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/hmarr.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":"2023-04-15T16:47:29.000Z","updated_at":"2024-06-26T14:49:51.000Z","dependencies_parsed_at":"2024-06-26T16:44:26.508Z","dependency_job_id":null,"html_url":"https://github.com/hmarr/hack-stack","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hmarr/hack-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmarr%2Fhack-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmarr%2Fhack-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmarr%2Fhack-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmarr%2Fhack-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmarr","download_url":"https://codeload.github.com/hmarr/hack-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmarr%2Fhack-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29968484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T10:55:55.490Z","status":"ssl_error","status_checked_at":"2026-03-01T10:55:55.175Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["compiler","nand2tetris","rust"],"created_at":"2024-10-04T08:21:46.608Z","updated_at":"2026-03-01T11:33:02.398Z","avatar_url":"https://github.com/hmarr.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hack Stack for nand2tetris\n\nSoftware toolchain for the Hack computer built as part of [nand2tetris](https://www.nand2tetris.org/).\n\nThe main toolchain is written in Rust, and lives in the `hack-stack` directory. It includes the following binaries:\n\n- `hack-assemble`: Assembler for the Hack assembly language\n- `hack-vm-translate`: Virtual machine translator for the Hack VM language\n- `jack-compile`: Compiler for the Jack programming language\n- `hack-emulate`: Emulator for the Hack computer\n\nThere's also a [web interface](https://hmarr.github.io/hack-stack) for the emulator, which lives in the `hack-web` directory. Under the hood it uses the Rust emulator from hack-stack, compiled to WebAssembly. The rest of it is written in TypeScript, and the frame buffer rendering happens on the GPU using WebGL.\n\nhttps://user-images.githubusercontent.com/110275/232240322-09289f6b-8410-4f24-83bb-dfce3ef5b72c.mov\n\n## Building the toolchain\n\nYou'll need to have the [Rust toolchain](https://www.rust-lang.org/tools/install) installed to compile hack-stack. Then you can run the following commands to build the toolchain:\n\n```sh\ncd hack-stack\ncargo build --release\n```\n\nAt that point you should have the following binaries available:\n\n- `target/release/hack-assemble`\n- `target/release/hack-vm-translate`\n- `target/release/jack-compile`\n- `target/release/hack-emulate`\n\nYou might want to temporarily add the `target/release` directory to your `PATH` environment variable so you can run these binaries from anywhere.\n\n```sh\nexport PATH=\"$PATH:$(pwd)/target/release\"\n```\n\n## Example toolchain usage\n\nHere's how you could comple a hello world program using the toolchain. As the program uses features from the Jack standard library and OS, you'll need those files available (they're in the `my-hack-os` directory in this example). You can either use the ones provided by the course (downloaded from the [nand2tetris website](https://www.nand2tetris.org/software)), or the Jack files you write during the course.\n\nNote: the maximum ROM size for the Hack computer is 32K words, so you can't compile a program that's larger than that. The course-provided Jack standard library and OS are larger than that, so you might to remove some of the files if you want to compile a program that uses them.\n\n```console\n$ ls HelloWorld\nMain.jack\n\n$ cat HelloWorld/Main.jack\nclass Main {\n   function void main() {\n      do Output.printString(\"Hello, world!\");\n      do Output.println();\n      return;\n   }\n}\n\n$ cp my-hack-os/*.jack HelloWorld/\n\n$ jack-compile HelloWorld\nCompiled HelloWorld/Math.jack successfully, wrote to HelloWorld/Math.vm\nCompiled HelloWorld/Screen.jack successfully, wrote to HelloWorld/Screen.vm\nCompiled HelloWorld/Sys.jack successfully, wrote to HelloWorld/Sys.vm\nCompiled HelloWorld/Keyboard.jack successfully, wrote to HelloWorld/Keyboard.vm\nCompiled HelloWorld/Output.jack successfully, wrote to HelloWorld/Output.vm\nCompiled HelloWorld/Memory.jack successfully, wrote to HelloWorld/Memory.vm\nCompiled HelloWorld/Array.jack successfully, wrote to HelloWorld/Array.vm\nCompiled HelloWorld/Main.jack successfully, wrote to HelloWorld/Main.vm\nCompiled HelloWorld/String.jack successfully, wrote to HelloWorld/String.vm\n\n$ hack-vm-translate HelloWorld\nTranslated HelloWorld successfully, wrote to HelloWorld/HelloWorld.asm\n\n$ hack-assemble HelloWorld/HelloWorld.asm\nAssembled HelloWorld/HelloWorld.asm successfully, wrote to HelloWorld/HelloWorld.hack\n```\n\n## Web emulator for the Hack computer\n\nYou can try the emulator online out by visiting [hmarr.github.io/hack-stack](https://hmarr.github.io/hack-stack).\n\nTo run the web emulator yourself, you'll need to have [Node.js](https://nodejs.org/en/), the [Rust toolchain](https://www.rust-lang.org/tools/install), and [wasm-pack](https://rustwasm.github.io/wasm-pack/) installed. Then you can run the following commands to build and run the web emulator:\n\n```sh\ncd hack-web\nnpm install\nnpm run dev\n```\n\nAt this point you can visit http://localhost:8080/ in your browser to see the web emulator. You can load a ROM file by clicking the \"Load ROM\" button, and then clicking the \"Run\" button to start the emulator.\n\n### Loading custom ROMs\n\nIf you've compiled your own `.hack` ROMs, copy them to the \"hack-web/www/roms\", re-start the web server, and you should be able to load them from the web emulator.\n\nYou can also use the `compile-rom.sh` script to compile a your own Jack program and add it to the `roms` directory. First, make sure you've built the Hack toolchain. Then, add your directory of Jack source files to the `programs` directory, and run `compile-rom.sh programs/\u003cprogram-dir\u003e`. The `programs` directory includes a couple of examples you can compile right away.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmarr%2Fhack-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmarr%2Fhack-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmarr%2Fhack-stack/lists"}