From 05a38f3f030cccc013dc30292d0329b24eb9fb2c Mon Sep 17 00:00:00 2001 From: Moss Prescott Date: Sat, 30 Mar 2024 18:09:38 -0400 Subject: [PATCH] Update intro for the 2020s --- README.md | 28 ++++++++++++++++++---------- requirements.txt | 3 +-- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 82e2e24..19c4532 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,13 @@ experience as compared to the tools provided by the authors: You need to have Python installed, at least version 3.6. -Pytest is required to run the tests: `pip3 install pytest`. +*Pytest* is required to run the tests: `pip3 install pytest`. -For the full Computer simulation including display and keyboard, `pygame` is required: -`pip3 install pygame`. On Mac OS X, you may need to install a dev version: -`pip3 install pygame==2.0.0dev6`. To install pygame on M1 Mac (Big Sur), this may help: -https://www.quora.com/How-do-you-install-Pygame-on-a-MacBook-M1?share=1. +For the full computer simulation including display and keyboard, *Pygame* is required: +`pip3 install pygame`. + +And for the best performance, you can install the static compiler *Cython*: +`pip3 install cython` ## Step 1: Do the Exercises @@ -57,19 +58,23 @@ running programs on your own designs as soon as you complete a single component ## Step 2: Enjoy Run `./computer.py examples/Pong.asm`. Bask in the glory of a CPU you built from scratch. -Note: the awesomeness starts after about 100,000 cycles. +Note: the awesomeness starts after about 4 million cycles. ![Pong screenshot](examples/Pong.png) +Depending on your hardware, you might need to use the simulator's options to get a playable +game. Try `./computer.py --help` to get started. + You can also run VM/Jack programs with `./computer.py [dir]`. The test programs for the -compiler are available under `examples/project_11` (along with Pong in Jack source form), -and the more interesting examples for testing the OS are in `examples/project_12`. +compiler are available under [`examples/project_11`](examples/project_11/) (along with Pong in Jack +source form), and the more interesting examples for testing the OS are in +[`examples/project_12`](examples/project_11/). More interesting/challenging programs can be found on the internet if you're persistent. Beware: many JACK programs you can find are quite large and may or may not fit in ROM when the standard compiler/translator are used. I suspect their authors only ever tested them with the course's included "VM simulator", which doesn't require the program to be translated! -You can try one of the alternative implementations (under `alt/`), several of which are +You can try one of the alternative implementations (under [`alt/`](alt/)), several of which are aimed at supporting large programs. @@ -94,10 +99,13 @@ Some experiments can be found in this repo under [alt/](alt/README.md). What language do you like to write? Can you compile _that_ language, or something like it, to the Hack VM? Or directly to assembly? +One interesting (and still experimental) alternative language is included: an interactive +interpreter for the Scheme language, ca 1991. See [alt/scheme](alt/scheme/). + ## License -This code is open source (MIT License), to the extent that I created it. However, if you want +This code is open source (MIT License), to the extent that I created it. However, if you want to base your own work on it you should be aware that the original work is covered by a different license, and I can provide no advice on the implications. diff --git a/requirements.txt b/requirements.txt index 8a02393..749a590 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,5 @@ pytest pygame -# Install these as well to use the "compiled" simulator mode +# Install this as well to use the "compiled" simulator mode # cython -# pyximport \ No newline at end of file