{"id":15718799,"url":"https://github.com/easoncxz/hack-assembler","last_synced_at":"2025-10-09T14:40:32.317Z","repository":{"id":147145061,"uuid":"90454629","full_name":"easoncxz/hack-assembler","owner":"easoncxz","description":"An assembler for an educational assembly language, as a project for the nand2tetris course","archived":false,"fork":false,"pushed_at":"2020-04-15T01:58:37.000Z","size":1195,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-06T03:37:04.999Z","etag":null,"topics":["hack-assembler","nand2tetris"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/easoncxz.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":"2017-05-06T10:12:48.000Z","updated_at":"2021-11-26T10:36:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"f55999c3-4eef-4fc7-975c-85a02ad5d816","html_url":"https://github.com/easoncxz/hack-assembler","commit_stats":null,"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easoncxz%2Fhack-assembler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easoncxz%2Fhack-assembler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easoncxz%2Fhack-assembler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easoncxz%2Fhack-assembler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/easoncxz","download_url":"https://codeload.github.com/easoncxz/hack-assembler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246388533,"owners_count":20769209,"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":["hack-assembler","nand2tetris"],"created_at":"2024-10-03T21:54:03.567Z","updated_at":"2025-10-09T14:40:27.272Z","avatar_url":"https://github.com/easoncxz.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"hack-assembler\n==============\n\n[![Build Status](https://travis-ci.org/easoncxz/hack-assembler.svg?branch=master)](https://travis-ci.org/easoncxz/hack-assembler)\n![Build and test](https://github.com/easoncxz/hack-assembler/workflows/Build%20and%20test/badge.svg)\n\n![nand2tetris](resources/nand2tetris-banner.png \"NAND to Tetris\")\n\n# An assembler for an educational assembly language\n\n`hack-assembler` is a command-line tool that compiles assembly programs written\nin an language called \"Hack\", into a plain-text form of binary machine code\nthat targets the \"Hack\" instruction set architecture.\n\nBoth the Hack language and the Hack hardware platform are developed as part of\nthe course [nand2tetris][homepage]. Indeed, `hack-assembler` is an \nimplementation of project 06 of the course: [Project 6: The Assembler][project]. \nSpecifications for the Hack language can be found in a chapter of the textbook \nfor that course: [(PDF) 6.  Assembler][chapter].\n\n# Installation\n\n### macOS\n\n    $ brew install easoncxz/tap/hack-assembler\n    ... Homebrew does its thing ...\n    $ which hack-assembler\n    /usr/local/bin/hack-assembler\n\nFor macOS, I've set up some CI servers to pre-compile the package for you if you \nare on High Sierra (macOS 10.13) through to Catalina (macOS 10.15), so the `brew \ninstall` should be pretty quick (less than a minute). If you're on another OS \nplatform, the above installation would still work, but Homebrew will need to use \nyour machine to compile my Haskell code and all its dependencies. \n`hack-assembler` will take some 15-60 minutes to build depending on your \nmachine's performance.\n\n### Linux\n\nI haven't yet packaged up this app for Linux. My plan is to use Nix for this, but\nI don't yet know how to do so. Please download and compile from source for now,\nas per the [Development](#development) section.\n\n# Usage example\n\nHere's a minimal example:\n\n    $ which hack-assembler\n    /usr/local/bin/hack-assembler\n    $ echo 'D = D - 1' | hack-assembler\n    1110001110010000\n\n`hack-assembler` reads Hack assembly code from standard input, and writes \nplain-text binary machine code to standard output. Below is a more realistic \nexample.\n\nWith a Hack assembly source file, say `two-and-three.asm`:\n\n    // This file is part of www.nand2tetris.org\n    // and the book \"The Elements of Computing Systems\"\n    // by Nisan and Schocken, MIT Press.\n    // File name: projects/06/add/Add.asm\n\n    // Computes R0 = 2 + 3  (R0 refers to RAM[0])\n\n        @2\n        D=A\n        @3\n        D=D+A\n        @0\n        M=D\n    (INFINITE_LOOP)\n        @INFINITE_LOOP\n        0;JMP\n\n\nIf we run the command:\n\n    hack-assembler \u003c two-and-three.asm \u003e two-and-three.hack\n\nWe will get a file `two-and-three.hack` with the contents below:\n\n    0000000000000010\n    1110110000010000\n    0000000000000011\n    1110000010010000\n    0000000000000000\n    1110001100001000\n    0000000000000110\n    1110101010000111\n\nI have provided the above `two-and-three.asm` and a reference output\n`two-and-three.reference.hack` inside the `resources` directory for your\nconvenience.\n\n# Hack language and platform\n\nThe Hack language has only a handful of types of instructions:\n\n- \"A instructions\", with their leading `@`, and\n- \"C instructions\", with three sometimes-optional components separated by `=`\n  and `;` symbols, and\n- Some pseudo-instructions like comments (`//`) and labels (`(LABEL)`).\n\nI implemented these in the `Model` module.  To know more about the syntax and\nsemantics of the Hack language, you'd have to read the chapter in the book :\n[(PDF) 6.  Assembler][chapter].\n\nTo execute the resulting Hack binary machine code, you'll have to use the \"CPU\nEmulator\" GUI program, which is implemented in Java Swing and provided by the\nNAND to Tetris course staff: See [The Nand to Tetris Software Suite][software].\nI've checked-in a copy of their software suite here at\n[resources/nand2tetris.zip][zip].\n\nThe GUI can be launched via the script at `nand2tetris/tools/CPUEmulator.sh`\ninside the zip file. It looks like this if we load up the example\n`resources/two-and-three.reference.hack` program from above:\n\n![CPU Emulator](resources/CPUEmulator_screenshot.png \"CPU Emulator\")\n\nClick the \"Load Program\" icon (brown folder), select your plain-text binary\n`.hack` file, then click the \"Run\" icon (`\u003e\u003e` symbol) to start running your\nHack program.\n\n# Development\n\nCompile and run `hack-assembler` from source:\n\n    $ git clone git@github.com:easoncxz/hack-assembler.git\n    $ cd hack-assembler\n    \nInstall [Stack][hs-stack], most conveniently via their curl-method:\n\n    curl -sSL https://get.haskellstack.org/ | sh\n\nThen you're ready to compile some code.\n\n    $ stack build\n    ... it then takes ages to compile half the Haskell ecosystem ...\n\n    $ stack test\n    ... (my tests passing) ...\n\n    $ stack exec -- hack-assembler \u003c hello.asm \u003e output.hack\n\n    $\n\n# About packaging and publishing\n\nAs you'd probably have figured from the above, I've published `hack-assembler` \nas a Homebrew Formula, [`hack-assembler.rb`][formula], over in my personal \nHomebrew Tap at [`easoncxz/homebrew-tap`][tap]. \"Formula\" and \"Tap\" are \n[Homebrew's beer-themed jargon words][beer]. Homebrew identifies my tap by their \nnaming convention as `easoncxz/tap`, hence the Homebrew command `brew install \neasoncxz/tap/hack-assembler`.\n\nTo know more about how I've set it all up, you can read through my `.travis.yml` \nand `.github/workflows/` continuous-integration configuration files. It's a bit \nof a mess because I had to use Travis CI's macOS build servers to get macOS \nversions 10.13 and 10.14, and Github Action's build servers to get macOS 10.15.  \n\nTo decouple this repo from the nitty-gritty Homebrew-related details, I dealt \nwith the Homebrew publishing workflows in a RubyGem I created for exactly this \npurpose, called [`homebrew_automation`][gem]. I use the `homebrew_automation.rb` \nCLI tool in this repo via `gem install homebrew_automation`.\n\n[homepage]: http://www.nand2tetris.org/\n[project]: https://www.nand2tetris.org/project06\n[chapter]: resources/chapter-06.pdf\n[software]: https://www.nand2tetris.org/software\n[zip]: resources/nand2tetris.zip\n[hs-stack]: https://docs.haskellstack.org/en/stable/README/\n[tap]: https://github.com/easoncxz/homebrew-tap\n[formula]: https://github.com/easoncxz/homebrew-tap/blob/master/Formula/hack-assembler.rb\n[beer]: https://docs.brew.sh/\n[gem]: https://github.com/easoncxz/homebrew-automation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasoncxz%2Fhack-assembler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feasoncxz%2Fhack-assembler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasoncxz%2Fhack-assembler/lists"}