JackE

Русская версия README здесь.

---

This project includes a compiler and emulator for the HACK computer virtual machine from the NAND-TO-TETRIS course.

Initial setup

1. Install uv

If you don't have uv installed yet, install it:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or via pip:

pip install uv

2. Create a virtual environment and install dependencies

uv sync

3. Activate the virtual environment

macOS/Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Quick start

Install JackE as a CLI tool

From the project root:

uv pip install -e .

To verify the installation, get information about the flags:

jacke -h

After this, the jacke command is available from any directory in the current environment:

jacke /path/to/jack/files

Compiler

More information about the compiler can be found here

Virtual machine

More information about the vm can be found here

Development

Pre-commit workflow

Run these commands before each commit:

# 1. Code formatting
uv run ruff format .

# 2. Fix linter issues
uv run ruff check --fix .

# 3. Type checking
uv run mypy vm/ compiler/ main.py

# 4. If everything is OK, commit
git add .
git commit -m "your commit message"

# tests will be added soon...

Alternative: all in one line

ruff format . && uv run ruff check --fix . && mypy vm/ compiler/ && echo "✅ All checks passed!"

Adding new dependencies

uv add package-name

Troubleshooting

Python version issues

If Python 3.14 is required, but you have a different version:

uv python install 3.14
uv python pin 3.14

Reset the environment

rm -rf .venv
uv sync