Skip to main content

Nand to Tetris

Overview​

Tips and tricks​

On a Mac, an .sh file accepts the -h flag for help. For example, 

~/Desktop/nand2tetris/tools/HardwareSimulator.sh -h

returns the following:

Usage:
    HardwareSimulator.sh             Starts the Hardware Simulator in
                                     interactive mode.
    HardwareSimulator.sh FILE.tst    Starts the Hardware Simulator and runs the
                                     FILE.tst test script.  The success/failure
                                     message is printed to the command console.

Software​

macOS​

Go to the software page and click the download the Nand2tetris Software Suite Version 2.6 link. The Setup Guide for Apple MacOS will be helpful. Below are details concerning my experience.

I already had Java installed from previous use (confirmed via java -version). I did as instructed and moved the extracted files from the .zip folder to my Desktop, but the goal in using something like 

~/Desktop/nand2tetris/tools/HardwareSimulator.sh

is longer possible because the .sh file is not executable. To resolve this issue, we can make each .sh file executable by issuing the following command from within the tools directory:

~/Desktop/nand2tetris/tools
chmod +x *.sh

Now each .sh file should be executable and something like

~/Desktop/nand2tetris/tools/HardwareSimulator.sh

should now run. It is possible you could get an error about the Times font no longer being available, but you can download and install it without issue.

Compiling .jack files​

Unlike the simulators, which feature an interactive user interface, the Jack Compiler is a terminal-oriented application. In order to run it, you must supply the name of the file or folder that you wish to compile. For example, suppose you wish to compile all .jack files stored in the folder projects/09/Square (that's a folder called Square, located in the 09 folder, which is located in the projects folder). To do so, open a Terminal window and type:

JackCompiler.sh ~/Desktop/nand2tetris/projects/09/Square

This results in either a successful compilation of the .jack files in Square, or some compilation errors.

About the software​

The Nand2tetris Software Suite consists of two directories: projects, and tools.

projects folder​

The projects directory is divided into 14 project directories named 00, 01, ..., 13 (of which project 00 is relevant only to learners who take the course in Coursera, and project 13 is open-ended). These directories contain files that you have to modify and complete as you work on various nand2tetris projects.

tools folder​

The tools directory contains the nand2tetris software tools. It's a collection of programs and files that will be explained as you follow the various projects.

Software reference​

The remainder of this section should be used as reference; there is no need to read what follows until you will be asked to use a particular software tool.

The .bat and .sh files are batch and script files, 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.

Software tool descriptions and tutorials​

The Nand to tetris Software Suite features the following software tools:

ToolDescriptionTest Scripts
Hardware SimulatorSimulates and tests logic gates and chips implemented in the HDL (Hardware Description Language) described in the book. Used in hardware construction projects. -> TutorialSimulating a Xor gate; Running a test script; Simulating the topmost Computer chip
CPU EmulatorEmulates the operation of the Hack computer system. Used to test and run programs written in the Hack machine language, in both its binary and assembly versions. -> TutorialRunning a machine language program that draws a rectangle on the computer screen
VM EmulatorEmulates the operation of our virtual machine (similar to Java's JVM); used to run and test programs written in the VM language (similar to Java's Bytcode). -> TutorialRunning a VM program
AssemblerTranslates programs from the Hack assembly language to Hack binary code. The resulting code can be executed directly on the Computer chip (in the hardware simulator), or emulated on the supplied CPU Emulator (much faster and more convenient). -> TutorialTranslating; Using a compare file
CompilerTranslates programs written in Jack (a simple, Java-like object-based language) into VM code. The resulting code can run on the supplied VM Emulator. Alternatively, the VM code can be translated further by the supplied VM translatorinto Hack assembly code that can then be executed on the supplied CPU Emulator.(A GUI-less, command-level program)
Operating systemTwo OS implementations are supplied: (i) a collection of eight .vm class files, written originally in Jack (just like Unix is written in C), and (ii) a faster implementation of all the OS services, embedded in the supplied VM Emulator.(GUI-less)
Text ComparerThis utility checks if two input text files are identical, up to white space differences. Used in various projects. In Unix use diff instead.(A GUI-less, command-level program)

Test script illustrations​

Hardware simulator​

Simulating a XOR gate​

Running a test script​

Simulating the topmost Computer chip​

CPU Emulator​

Running a machine language program that draws a rectangle on the computer screen​

VM Emulator​

Running a VM program​

Assembler​

Translating​

Using a compare file​

Demos​

Hardware Simulator: First Look​

video content

First look at the Nand to Tetris hardware simulator. This demo illustrates how to load a chip specification (HDL file / program), and how to evaluate the chip by changing the values of its input pins and observing the resulting values of its output pins. Two kinds of chips are illustrates: a chip that operates on 1-bit inputs, and another chip that operates on 16-bit inputs (also known as "buses").

HDL-Based Chip Simulation​

video content

Illustrates how to edit, load, and interact with a chip specification (HDL file / program), using the Nand to Tetris hardware simulator. Also demonstrates how to use chip-parts that were not yet implemented, using built-in chips in their stead.

Script-Based Chip Simulation​

video content

Illustrates how to test a chip specification (HDL program / file) in the Nand to Tetris hardware simulator, using a test script. In particular, we show two cases: testing a well-written HDL program, and testing / debugging an HDL program that has a bug. Also illustrates working with script (.tst), output (.out), and compare (.cmp) files.

Clock Demo​

video content

Illustrates how the clock comes to play when simulating sequential (time-dependent) chips in the Nand to Tetris hardware simulator. In particular, illustrates how to advance the clock interactively, and using a test-script. These operations realize a sequence of cycles, to which the sequential chips respond according to their specifications.

Register Demo​

video content

Illustrates how a Register chip operates on the Nand to Tetris hardware simulator. Shows how the register maintains its value (state) over time, and how we can load the register with a new value. In particular, shows how it takes a complete cycle before the register commits to its new value.

Program Counter Demo​

video content

This video illustrates how to have a program counter.

RAM Demo​

video content

Illustrates how a RAM (Random Access Memory) chip operates on the Nand to Tetris hardware simulator. In particular, shows how to read data from, and write data into, the Hack computer's RAM chip.

CPU Emulator Demo​

video content

Illustrates the CPU emulator, which enables loading and executing programs written in the Hack machine language. The emulator allows loading either symbolic (assembly) code or binary code. In the former case, it translated the assembly instructions to binary instructions, on the fly.

CPU Emulator Demo: Executing a simple graphics program​

video content

Illustrates how to execute a graphics program on the CPU emulator. The program, stored in a file named Rectangle.asm, is written in the Hack assembly language. It is designed to draw a rectangle on the computer's screen, as this demo illustrates.

CPU Emulator Demo: Executing Pong​

video content

The Nand to Tetris CPU emulator can execute any program written in the Hack machine language. Such programs are typically written in a high level language (like Jack) and then compiled into machine language. One such program is a version of the classical video game Pong. This demo illustrates how the Nand to Tetris CPU emulator executed the compiled Pong program.

Screen Chip Demo​

video content

Illustrates working with the Screen chip in the Nand to Tetris hardware simulator. The screen device of the Hack computer is realized as a memory chip, called Screen, that has 8K 16-bit registers. The Screen chip continuously refreshes a 2D screen device consisting of 256 rows of 512 black-and-white pixels each. The demo shows how this screen device can be manipulated by entering various values into the Screen memory chip.

Keyboard Chip Demo​

video content

This video gives a demonstration of what a keyboard chip is.

ROM Demo​

video content

Illustrates the ROM chip of the Hack computer, which serves as the computer's instruction memory, i.e. the storage device that contains the presently executing program. In particular, shows how to load a program into the ROM, and how to inspect the ROM's contents using both symbolic and binary representations.

Coursera​

Project files​

Syllabi​