cl-hackvmtr

Overview

cl-hackvmtr is a VM Translator for the Hack platform, written in Common Lisp. It was designed as the exercise for Chapters 7 and 8 of the book The Elements of Computing Systems, by Nisan and Schocken.

This VM Translator comprises the full translator for the Hack platform, which works perfectly for all scripts up to Chapter 8 of the book.

More information on my progress on the book can be seen at my study repository.

Usage

One should be able to use this VM Translator by either using Quicklisp directly or Roswell.

Using with Quicklisp and the REPL directly

Either add this repository to your local-projects folder or install it using Quicklisp (this project should be available from Ultralisp. If you don’t know how to add a new dist, I recommend taking a look at the Quicksys tool).

Then, given a .vm file, or a directory containing .vm files, one might use the following:

(ql:quickload :cl-hackvmtr)
(cl-hackvmtr:vm-translate "/path/to/file/or/directory")

This will create a directory-or-file-name.asm file, which can be finally compiled into bytecode for the Hack platform.

If you want the generated code to not have the starting bootstrap section, which sets up the stack and calls Sys.init, just pass the flag which inhibits the bootstrap section to vm-translate:

(cl-hackvmtr:vm-translate "/path/to/file/or/directory" t)

A file with the same name of the .vm file or directory will appear on the current location, with an appended .asm extension to it.

Using from Roswell

One can simply install this tool using Roswell with the following command:

ros install luksamuk/cl-hackvmtr

From there on, a script called hackvmtr should be available to invoke directly from command line. Simply pass as argument either a single .vm file, or a directory containing .vm files, and hackvmtr will attempt to generate a single assembly file for the given file or directory.

You may call the application directly, just as you would use any other application. This VM Translator will only translate a single directory or file at once:

hackvmtr /path/to/file/or/directory

If you want the generated code to not have the starting bootstrap section, which sets up the stack and calls Sys.init, just pass the flags --no-bootstrap or -nb, which inhibits the bootstrap section, at any position of the command:

hackvmtr --no-bootstrap /path/to/file/or/directory

Just like using the REPL directly, an .asm file will appear on the current directory, named after the compiled .vm file or the compiled directory.

Using qlot

This project also supports qlot, so one will be able to use this tool to either run or develop this project. However, the primary use of qlot involved setting up a local Quicklisp directory with SLIME support.

Unit Testing

This project provides no utilities for unit testing, since the nand2tetris book materials (which can be found online) already provide test scripts and tools to verify the correctness of this software.

License

This project is distributed under the MIT License. See LICENSE for details.

Copyright (c) 2019 Lucas Vieira