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 some 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 folder on your computer, without requiring full paths to the files on which they operate. Further, they accept spaces in folder and file names, so they will work if nand2tetris is installed under a folder named, say, "My Documents".

​

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 folder. Here is an example how to do it for, say, the HardwareSimulator tool:

 

ln -s ~/nand2tetris/tools/HardwareSimulator.sh HardwareSimulator

chmod +x HardwareSimulator

​

Windows users

​

For the batch files to work from the command line, you must add (once and for all) the nand2tetris/tools folder 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 cmdexe can run Java commands in batch files. If you get the output "'java' is not recognized..." you likely only have the 32-bit Java installed on your computer.

​

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."

​

Usage

​

Hardware Simulator: To invoke the hardware simulator in interactive mode, type "HardwareSimulator" in the command line. For example:

​

C:\...\projects\02> HardwareSimulator

(a window will open up, running the interactive version of the Hardware Simulator)

​

To invoke the hardware simulator in batch (shell/cmd) mode, type "HardwareSimulator" in the command line. For example:

​

C:\...\projects\02>HardwareSimulator ALU.tst

(invokes the simulator, loads the given test script, executes it, and reports the result). Note that the simulator's interactive mode also enables loading and executing test scripts.

 

Successful test (example):

​

C:\...\projects\02> HardwareSimulator ALU.tst

End of script - Comparison ended successfully

 

Failed test (example):

​

C:\...\projects\02> HardwareSimulator ALU.tst

Comparison failure at line 24

 

Error in the associated HDL file:

​

C:\...\projects\02> HardwareSimulator ALU.tst

In HDL file C:\...\projects\02\ALU.hdl, Line 60, out[16]: the specified sub bus is not in the bus range: load ALU.hdl

​

CPU Emulator and VM Emulator: The operations of these tools follow the same convention described above. If you invokve either tool without a parameter, the tool will work in interactive mode; if you supply a parameter (test script), the tool will run batch-style.

​

Assembler: Typing "Assembler" will start the supplied assembler in interactive mode. Typing "Assembler xxx.asm" will assemble the specified xxx.asm file and generate a file named xxx.hack, containing the translated binary code. Note that the assembler's interactive mode also enables loading and translating .asm files.

 

Successful assembly (example):

​

C:\...\projects\04\fill> Assembler Fill.asm Assembling "c:\...\projects\04\fill\Fill.asm"

 

Failed assembly (example):

 

C:\...\projects\04\fill> Assembler Fill.asm

Assembling "C:\...\projects\04\fill\Fill.asm" In line 15, Expression expected

​

To compare the resulting .hack code file to some expected .hack file, use the supplied TextComparer tool, described below.

​

Compiler: Typing "JackCompiler fileName.jack" will compile the supplied Jack file. Typing "JackCompiler folderName" will compile all the Jack file in the specified folder. Wildcards are not supported. Examples:

 

Compile a single file:

​

C:\...\projects\09\Reflect> JackCompiler Mirrors.jack

Compiling "C:\...\projects\09\Reflect\Mirrors.jack"

 

Compile a folder named "reflect":

​

C:\...\projects\09> JackCompiler reflect

Compiling "C:\...\projects\09\reflect"

​

TextComparer: Compares two given files ignoring white space, and reports success or failure. For example, suppose you run the hardware simulator with some test script and get a comparison failure. If you want, you can then 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 the .jack files in the current working directory.

JackCompiler directoryName Compiles all the .jack files in the specified directory.

JackCompiler fikeName.jack Compiles the specified Jack file