travisgoodspeed · davehorner · Nov 15, 2025
diff --git a/Makefile b/Makefile
@@ -0,0 +1,125 @@
+# Top-level Makefile for GoodASM
+# Forwards targets to tests/Makefile
+
+.PHONY: all clean selftests fuzz ensure_task unidasm qt5deps yara_x tests-all build
+
+# Default: configure & build with CMake (creates build/ if missing)
+CURDIR:=$(shell pwd)
+BUILD_PATHS:=$(CURDIR)/build:$(CURDIR)/build/Debug:$(CURDIR)/build/Release:$(CURDIR)/scripts
+export PATH:=$(BUILD_PATHS):$(PATH)
+
+all: build tests-all
+
+build:
+	@mkdir -p build
+	@cmake -S . -B build || true
+	@cmake --build build
+# Preserve old behavior to forward to tests when explicitly requested
+tests-all: yara_x nasm qt5deps unidasm
+	$(MAKE) -C tests all
+
+clean:
+	$(MAKE) -C tests clean
+
+ifeq ($(OS),Windows_NT)
+	@echo "Removing unidasm.exe from %USERPROFILE%\\bin if present";
+	@cmd /C "if exist %USERPROFILE%\\bin\\unidasm.exe del %USERPROFILE%\\bin\\unidasm.exe" || true
+else
+	@echo "Removing local unidasm if present";
+	@rm -f "$$HOME/.local/bin/unidasm" || true;
+	@# If a system-wide copy exists on macOS/linux, remove if writable or show sudo hint
+	@if [ -f /usr/local/bin/unidasm ]; then \
+		if [ -w /usr/local/bin ]; then \
+			rm -f /usr/local/bin/unidasm && echo "removed /usr/local/bin/unidasm"; \
+		else \
+			echo "/usr/local/bin/unidasm exists; to remove run: sudo rm /usr/local/bin/unidasm"; \
+		fi; \
+	fi;
+endif
+
+selftests:
+	$(MAKE) -C tests selftests
+
+fuzz:
+	$(MAKE) -C tests fuzz
+
+ensure_task:
+ifeq ($(OS),Windows_NT)
+	cmd /C scripts\\ensure_task.cmd
+else
+	bash ./scripts/ensure_task.sh
+endif
+
+qt5deps:
+	@echo "checking for Qt5 (qmake/pk-config) on PATH...";
+	@if command -v qmake-qt5 >/dev/null 2>&1 || command -v qmake >/dev/null 2>&1 || (command -v pkg-config >/dev/null 2>&1 && pkg-config --exists Qt5Core); then \
+		echo "Qt5 appears to be installed: $$(command -v qmake-qt5 || command -v qmake || echo pkg-config)"; \
+	else \
+		if command -v apt-get >/dev/null 2>&1; then \
+			sudo apt-get update && sudo apt-get install -y qtbase5-dev qt5-qmake qtbase5-dev-tools pkg-config libsdl2-ttf-dev; \
+		elif command -v brew >/dev/null 2>&1; then \
+			brew install qt@5 pkg-config sdl2_ttf; \
+		else \
+			echo "Please install Qt5 dev tools, pkg-config, and SDL2_ttf manually."; \
+		fi; \
+	fi
+
+
+nasm:
+	@echo "checking for nasm on PATH...";
+	@if command -v nasm >/dev/null 2>&1; then \
+		echo "nasm is already on PATH at: $$(command -v nasm)"; \
+	else \
+		if command -v apt-get >/dev/null 2>&1; then \
+			sudo apt-get update && sudo apt-get install -y nasm; \
+		elif command -v brew >/dev/null 2>&1; then \
+			brew install nasm; \
+		else \
+			echo "Please install nasm manually"; \
+		fi; \
+	fi
+
+
+yara_x:
+	@echo "checking for yr on PATH...";
+	@if command -v yr >/dev/null 2>&1; then \
+		echo "yr is already on PATH at: $$(command -v yr)"; \
+	else \
+		if [ ! -d yara-x ]; then git clone --depth 1 https://github.com/VirusTotal/yara-x.git; fi; \
+		cargo install --path yara-x/cli --root $$HOME/.local; \
+	fi
+
+# unidasm: qt5deps
+# 	@if [ ! -d mame ]; then git clone --depth 1 https://github.com/mamedev/mame.git; fi
+# 	$(MAKE) -C mame TOOLS=1 generate target=generate
+# 	$(MAKE) -C mame TOOLS=1 unidasm target=unidasm
+# 	@if [ -f mame/bin/unidasm ]; then \
+# 		mkdir -p $$HOME/.local/bin; \
+# 		cp mame/bin/unidasm $$HOME/.local/bin/unidasm; \
+# 	elif [ -f mame/unidasm ]; then \
+# 		mkdir -p $$HOME/.local/bin; \
+# 		cp mame/unidasm $$HOME/.local/bin/unidasm; \
+# 	else \
+# 		echo 'unidasm binary not found!'; exit 1; \
+# 	fi
+
+# .PHONY: unidasm
+unidasm:
+	@if [ ! -d mame ]; then git clone --depth 1 https://github.com/mamedev/mame.git; fi
+ifeq ($(OS),Windows_NT)
+	@echo "Building unidasm on Windows...";
+	@cmd /C scripts\\build-unidasm.cmd
+else
+	@echo "Building unidasm on Unix-like system...";
+	@if sh scripts/build-unidasm.sh; then \
+		if [ -f "$$HOME/.local/bin/unidasm" ]; then \
+			echo "unidasm built and copied to $$HOME/.local/bin/unidasm"; \
+			echo "To install system-wide to /usr/local/bin run:"; \
+			echo "  sudo cp \"$$HOME/.local/bin/unidasm\" /usr/local/bin/unidasm && sudo chmod 755 /usr/local/bin/unidasm"; \
+		else \
+			echo "build script reported success but unidasm not found at $$HOME/.local/bin/unidasm"; exit 1; \
+		fi; \
+	else \
+		echo "build-unidasm.sh failed; see its output above for details"; exit 1; \
+	fi
+endif
diff --git a/README.md b/README.md
@@ -47,27 +47,104 @@ check the issue tracker for their status.
 Source code and binaries were publicly released at
 [DistrictCon](https://www.districtcon.org/) on Feb 21, 2025.
 
-## Building
+## Building and Automation
 
-For GUI development, install the [Qt Dev
-Kit](https://www.qt.io/download-qt-installer-oss) and then open
-`CMakefile.txt` in Qt Creator.  On Windows, you must also install the
-[Git](https://git-scm.com/downloads/win) client; Github Desktop is not
-enough on its own.
+This project supports robust, cross-platform build and test automation using both a top-level `Makefile` (for Linux/macOS and advanced users) and a [Taskfile.yml](https://taskfile.dev) for [Go Task](https://taskfile.dev) (especially recommended for Windows users). The automation ensures all dependencies are installed, including CMake, Qt, Git, NASM, unidasm, and YARA-X (`yr`).
 
-To build in Linux, first install `qt6-declarative-dev`, `qml6-module-\*`, `git`
-and `cmake`, then run the following:
+### Recommended: Go Task (Windows & Cross-Platform)
+
+The preferred way to build and test GoodASM on Windows (and optionally on Linux/macOS) is via Go Task:
+
+### Ensuring Go Task is Installed
+
+If you do not already have [Go Task](https://taskfile.dev) installed:
+
+- **On Windows:**
+  - Since `make` is not available by default, run the script directly:
+    ```cmd
+    ensure_task.cmd
+    ```
+- **On Linux/macOS:**
+  - Run:
+    ```sh
+    make ensure_task
+    ```
+
+The scripts are located at:
+- `ensure_task.cmd` (Windows)
+- `ensure_task.sh` (Linux/macOS)
+
+These scripts will attempt to install Go Task if it is missing, ensuring that all automation commands are available.
+
+
+### Recommended: Go Task (Windows & Cross-Platform)
+
+The preferred way to build and test GoodASM on Windows (and optionally on Linux/macOS) is via Go Task:
+
+1. In a terminal, run:
+   ```cmd
+   task all
+   ```
+   This will:
+   - Install CMake, Qt, Git, NASM, unidasm, and YARA-X (`yr`) if not already present
+   - Build the project (using CMake or Makefile as appropriate)
+   - Run all self-tests
+
+You can also run individual tasks, e.g. `task build:cmake` or `task run:repl`. Run `task --list` to see all available tasks.
+
+### Makefile (Linux/macOS & Advanced)
+
+The top-level `Makefile` is the single source of truth for build and test logic on POSIX systems. It:
+
+- Installs all required dependencies (Qt5, pkg-config, SDL2_ttf, unidasm, YARA-X)
+- Builds the project and runs all tests
+- Builds and installs the MAME unidasm tool and YARA-X (`yr`) automatically
+
+To build and test on Linux/macOS:
+
+```sh
+make qt5deps        # Installs all dependencies, including YARA-X (yr)
+make                # Builds and runs all tests
 ```
-git clone https://github.com/travisgoodspeed/goodasm
-cd goodasm
-mkdir build
-cd build
-cmake ..
-make -j 8 clean all
+
+You can also use `make unidasm` to build and install the MAME unidasm tool, or `make clean` to remove build artifacts.
+
+#### Note on YARA-X
+
+The test infrastructure uses [YARA-X](https://github.com/VirusTotal/yara-x) (`yr`), not classic YARA. The Makefile will automatically build and install YARA-X if it is not present.
+
+#### Windows Manual Build
+
+For GUI development, install the [Qt Dev Kit](https://www.qt.io/download-qt-installer-oss) and open `CMakeLists.txt` in Qt Creator. You must also install [Git](https://git-scm.com/downloads/win); Github Desktop is not enough.
+
+You can also run individual tasks, e.g. `task build:cmake` or `task run:repl`. Run `task --list` to see all available tasks.
+
+### Makefile (Linux/macOS & Advanced)
+
+The top-level `Makefile` is the single source of truth for build and test logic on POSIX systems. It:
+
+- Installs all required dependencies (Qt5, pkg-config, SDL2_ttf, unidasm, YARA-X)
+- Builds the project and runs all tests
+- Builds and installs the MAME unidasm tool and YARA-X (`yr`) automatically
+
+To build and test on Linux/macOS:
+
+```sh
+make qt5deps        # Installs all dependencies, including YARA-X (yr)
+make                # Builds and runs all tests
 ```
 
-The preferred executable is `goodasm`.  The GUI for iOS and Android is
-more of a fun toy than a tool.
+You can also use `make unidasm` to build and install the MAME unidasm tool, or `make clean` to remove build artifacts.
+
+#### Note on YARA-X
+
+The test infrastructure uses [YARA-X](https://github.com/VirusTotal/yara-x) (`yr`), not classic YARA. The Makefile will automatically build and install YARA-X if it is not present.
+
+#### Windows Manual Build
+
+For GUI development, install the [Qt Dev Kit](https://www.qt.io/download-qt-installer-oss) and open `CMakeLists.txt` in Qt Creator. You must also install [Git](https://git-scm.com/downloads/win); Github Desktop is not enough.
+
+---
 
 ## Examples
 
@@ -304,6 +381,16 @@ interactive mode for iOS and Android.  Please don't do real work this
 way, but it's handy when studying an instruction set with pen and
 paper, away from a real laptop.
 
+### Exiting the REPL
+
+To exit the GoodASM interactive REPL:
+
+- On **Windows**: Press `Ctrl+Z` then Enter
+- On **Linux/macOS**: Press `Ctrl+D`
+- Or use `Ctrl+C` to interrupt/terminate the REPL
+
+There are no built-in `.exit` or `.quit` commands; only EOF or interrupt will exit the REPL.
+
 ## Identification and Grading
 
 It's a frequent problem in embedded systems reverse engineering that
@@ -510,7 +597,6 @@ source of examples for using the library.
 languages, so that someday the parser can be rewritten without
 breaking code compatibility.
 
-
 ## Similar Assembler/Disassemblers
 
 [Naken ASM](https://github.com/mikeakohn/naken_asm)