The Nand2Tetris Software Suite contains all the tools and files necessary to complete all the projects described in this site and in the book. Once you download the nand2tetris software suite to your PC, there is no need to download anything else throughout the course.
The software runs as is on Windows, Unix, and Mac OS.
The software can be used freely and is protected by the GNU GPL (General Public License).
The software is open source. You If you wish to inspect/modify/extend the source code, see the bottom of this page.Download
(Note: we have recently updated the software suite; since the download file is new, some browsers may warn that "this file is not frequently downloaded and can be dangerous", or something like this. Please ignore this warning, and proceed to download and extract the zip file to your computer.)
Download the Nand2tetris Software Suite Version 2.5 (about 790K).
Mac users: after downloading, read this Setup Guide for Mac OS X, written by Yong Bakos.
Windows users: after downloading, put the downloaded zip file in an empty directory on your computer and extract its contents as is, without changing the directories structure and names. In order to use our software tools, your computer must be equipped with a Java Run-time Environment. The JRE can be downloaded freely from many sites including this one. For best performance, download the latest available version.
Problems? Describe your problem in our Q&A Forum and you will get help soon.
About the Software
The Nand2tetris Software Suite consists of two directories named projects and tools.
The projects directory is divided into 14 project directories named 00, 01, ..., 13 (of which project 00 is a warm-up and project 13 is open-ended). These directories contain files that you have to modify and complete, as explained throughout the course.
The tools directory contains the nand2tetris software tools. There is no need to inspect or touch any of these files. Rather, you have to use them as the course progresses, following our guidelines. The remainder of this section describes the contents of the tools directory. Once again, there is no need to touch these files, so this description is optional.
The .bat and .sh files are batch and script files that are used to invoke the nand2tetris software tools. These files are explained in detail below.
The bin directory contains the code of the nand2tetris software tools. It consists of several subdirectories containing Java class files and supporting files.
The builtInChips and the builtInVMCode directories contain files that are used by the supplied Hardware Simulator and VM Emulator, respectively.
The OS directory contains a compiled version of the Jack operating system.
The Nand2tetris Software Suite features the following software tools:
Running the Software Tools
The supplied software tools are designed to be run from your computer's command-line environment (also known as "terminal", or "shell"). Command-line environments vary from one operating system to another, and working in them requires knowledge of various OS shell commands.
In order to eliminate this overhead, we supply batch files (for Windows) and scripts (for Unix and Mac OS), developed by Mark Armbrust. These batch and script files enable invoking the supplied nand2tetris tools from the command line on your computer, painlessly. They can be used from any working directory on your computer, without requiring full paths to the files on which they operate. Further, they accept spaces in directory and file names, so they will work if nand2tetris is installed under a directory named, say, "My Documents".
The batch files have been tested on Windows XP and Windows 7 32- and 64-bit. The scripts have been tested on Ubuntu Linux and Mac OS X.
Mac and Linux users:
Before running the scripts you must first change their file attributes to include "executable". You can then run the scripts by typing their name, as well as the .sh extension, in the terminal environment.
If you want to avoid typing the 'sh' extensions, you can create (once and for all) symbolic links in your ~/bin directory. Here is an example how to do it for, say, the HardwareSimulator tool:
ln -s ~/nand2tetris/tools/HardwareSimulator.sh HardwareSimulator chmod +x HardwareSimulatorWindows users:
For the batch files to work from the command line, you must add (once and for all) the nand2tetris/tools directory to your PATH variable.
To run a batch file from command-line, type its name, without the .bat extension.
If you use Windows 7 64-bit you need to install the 64-bit version of Java so that 64-bit cmd.exe can run Java commands in batch files. If the batch files say " 'java' is not recognized..." you likely only have the 32-bit Java installed.
You can create desktop icons and use them to invoke the interactive versions of the following supplied tools: HardwareSimulator, Assembler, CPUEmulator and VMEmulator. This can be done by finding the disk locations of the respective batch files, right-clicking on them and picking "Send to > Desktop." Edit the shortcuts' properties and set "Run" to "minimized."
Hardware Simulator: To invoke the interactive version of the Hardware Simulator, type "HardwareSimulator" in the command line:
C:\...\projects\02>HardwareSimulator (a window will open up, running the interactive version of the Hardware Simulator)
Typing "HardwareSimulator xxx.tst" will run the given test script in the simulator and report the result (but note that test scripts can also be loaded into the simulator in interactive mode).
C:\...\projects\02>HardwareSimulator ALU.tst End of script - Comparison ended successfullyFailed test:
C:\...\projects\02>HardwareSimulator ALU.tst Comparison failure at line 24Error in the associated HDL file:
C:\...\projects\02>HardwareSimulator ALU.tst In HDL file C:\...\projects\02\ALU.hdl, Line 60, out: the specified sub bus is not in the bus range: load ALU.hdl
CPU Emulator and VM Emulator: These tools work similarly, by either opening the tool in interactive mode if there is no parameter, or running a test script.
Assembler: Typing "Assembler" will start the supplied assembler in interactive mode. Typing "Assembler xxx.asm" will assemble the given xxx.asm file and generate a file named xxx.hack, containing the translated binary code (but note that these operations can also be done in the interactive version).
C:\...\projects\04\fill>Assembler Fill.asm Assembling "c:\...\projects\04\fill\Fill.asm"Failed assembly:
C:\...\projects\04\fill>Assembler Fill.asm Assembling "C:\...\projects\04\fill\Fill.asm" In line 15, Expression expected
There is no way to automatically compare the resulting code to expected output. Such comparisons can be done though using the supplied TextComparer tool, described below.
Compiler: Typing "JackCompiler" with no arguments will cause the Jack compiler to compile all the files in the current directory. With an argument, it will compile a single Jack file or all the files in the named directory. Wildcards are not supported. Here are some examples:
Compile the current directory:
C:\...\projects\09\Reflect>JackCompiler Compiling "c:\...\projects\09\Reflect"Compile a single file:
C:\...\projects\09\Reflect>JackCompiler Mirrors.jack Compiling "C:\...\projects\09\Reflect\Mirrors.jack"Compile the "Reflect" directory (for example):
C:\...\projects\09>JackCompiler Reflect Compiling "C:\...\projects\09\Reflect"
TextComparer: The supplied TextComparer tool compares two given files and reports success or failure. For example, suppose you run the hardware simulator with some test script and get some comparison failure. Next, you can use the TextComparer to investigate the problem:
C:\...\projects\02>HardwareSimulator ALU.tst Comparison failure at line 24 C:\...\projects\02>TextComparer ALU.cmp ALU.out Comparison failure in line 23: |0101101110100000|0001111011010010|1|1|0|0|0|0|0001111011010010|0|0| |0101101110100000|0001111011010010|1|1|0|0|0|0|0001111011010010|0|1|(Note the line number discrepancy between the reports of the two tools).
Help: In Windows, each batch file accepts a "/?" option that shows its intended usage. In Mac and Unix, use "-h". For example:
C:\...\projects\09>JackCompiler /? Usage: JackCompiler Compiles all .jack files in the current working directory. JackCompiler DIRECTORY Compiles all .jack files in DIRECTORY. JackCompiler FILE.jack Compiles FILE.jack to FILE.vm.
All the nand2tetris software tools are written in Java. If you wish to inspect, modify, or extend some tool, you can download the source code Version 2.5. Before compiling the source code on your computer, read Readme.txt.
For details on what's new in the current version of the software (somewhat technical but useful for porting old modifications to the current version), read this ChangeLog.txt file.
If you wish to share your software extensions with others, please email us at firstname.lastname@example.org.