Skip to content

Commit 959c2d0

Browse files
dave hornerdavehorner
dave horner
authored and
davehorner
committed
feat: go Taskfile.yml; tested on windows/ubuntu. install:qt works. top-level makefile and ensure task scripts.
1 parent eb93c70 commit 959c2d0

5 files changed

Lines changed: 375 additions & 17 deletions

File tree

‎Makefile‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Top-level Makefile for GoodASM
2+
# Forwards targets to tests/Makefile
3+
4+
.PHONY: all clean selftests fuzz ensure_task unidasm qt5deps yara_x
5+
6+
all:
7+
$(MAKE) -C tests all
8+
9+
clean:
10+
$(MAKE) -C tests clean
11+
12+
selftests:
13+
$(MAKE) -C tests selftests
14+
15+
fuzz:
16+
$(MAKE) -C tests fuzz
17+
18+
ensure_task:
19+
ifeq ($(OS),Windows_NT)
20+
cmd /C ensure_task.cmd
21+
else
22+
bash ./ensure_task.sh
23+
endif
24+
25+
qt5deps: yara_x
26+
@if command -v apt-get >/dev/null 2>&1; then \
27+
sudo apt-get update && \
28+
sudo apt-get install -y qtbase5-dev qt5-qmake qtbase5-dev-tools pkg-config libsdl2-ttf-dev; \
29+
elif command -v brew >/dev/null 2>&1; then \
30+
brew install qt@5 pkg-config sdl2_ttf; \
31+
else \
32+
echo "Please install Qt5 dev tools, pkg-config, and SDL2_ttf manually."; \
33+
fi
34+
35+
yara_x:
36+
@if [ ! -d yara-x ]; then git clone --depth 1 https://github.com/VirusTotal/yara-x.git; fi
37+
cd yara-x && cargo build --release
38+
mkdir -p $$HOME/.local/bin
39+
cp yara-x/target/release/yr $$HOME/.local/bin/yr || echo 'yr binary not found!'
40+
41+
unidasm: qt5deps
42+
@if [ ! -d mame ]; then git clone --depth 1 https://github.com/mamedev/mame.git; fi
43+
$(MAKE) -C mame TOOLS=1
44+
@if [ -f mame/bin/unidasm ]; then \
45+
mkdir -p $$HOME/.local/bin; \
46+
cp mame/bin/unidasm $$HOME/.local/bin/unidasm; \
47+
elif [ -f mame/unidasm ]; then \
48+
mkdir -p $$HOME/.local/bin; \
49+
cp mame/unidasm $$HOME/.local/bin/unidasm; \
50+
else \
51+
echo 'unidasm binary not found!'; exit 1; \
52+
fi

‎README.md‎

Lines changed: 107 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -47,27 +47,108 @@ check the issue tracker for their status.
4747
Source code and binaries were publicly released at
4848
[DistrictCon](https://www.districtcon.org/) on Feb 21, 2025.
4949

50-
## Building
51-
52-
For GUI development, install the [Qt Dev
53-
Kit](https://www.qt.io/download-qt-installer-oss) and then open
54-
`CMakefile.txt` in Qt Creator. On Windows, you must also install the
55-
[Git](https://git-scm.com/downloads/win) client; Github Desktop is not
5650
enough on its own.
57-
58-
To build in Linux, first install `qt6-declarative-dev`, `qml6-module-\*`, `git`
5951
and `cmake`, then run the following:
52+
53+
54+
## Building and Automation
55+
56+
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`).
57+
58+
### Recommended: Go Task (Windows & Cross-Platform)
59+
60+
The preferred way to build and test GoodASM on Windows (and optionally on Linux/macOS) is via Go Task:
61+
62+
### Ensuring Go Task is Installed
63+
64+
If you do not already have [Go Task](https://taskfile.dev) installed:
65+
66+
- **On Windows:**
67+
- Since `make` is not available by default, run the script directly:
68+
```cmd
69+
ensure_task.cmd
70+
```
71+
- **On Linux/macOS:**
72+
- Run:
73+
```sh
74+
make ensure_task
75+
```
76+
77+
The scripts are located at:
78+
- `ensure_task.cmd` (Windows)
79+
- `ensure_task.sh` (Linux/macOS)
80+
81+
These scripts will attempt to install Go Task if it is missing, ensuring that all automation commands are available.
82+
83+
84+
### Recommended: Go Task (Windows & Cross-Platform)
85+
86+
The preferred way to build and test GoodASM on Windows (and optionally on Linux/macOS) is via Go Task:
87+
88+
1. In a terminal, run:
89+
```cmd
90+
task all
91+
```
92+
This will:
93+
- Install CMake, Qt, Git, NASM, unidasm, and YARA-X (`yr`) if not already present
94+
- Build the project (using CMake or Makefile as appropriate)
95+
- Run all self-tests
96+
97+
You can also run individual tasks, e.g. `task build:cmake` or `task run:repl`. Run `task --list` to see all available tasks.
98+
99+
### Makefile (Linux/macOS & Advanced)
100+
101+
The top-level `Makefile` is the single source of truth for build and test logic on POSIX systems. It:
102+
103+
- Installs all required dependencies (Qt5, pkg-config, SDL2_ttf, unidasm, YARA-X)
104+
- Builds the project and runs all tests
105+
- Builds and installs the MAME unidasm tool and YARA-X (`yr`) automatically
106+
107+
To build and test on Linux/macOS:
108+
109+
```sh
110+
make qt5deps # Installs all dependencies, including YARA-X (yr)
111+
make # Builds and runs all tests
60112
```
61-
git clone https://github.com/travisgoodspeed/goodasm
62-
cd goodasm
63-
mkdir build
64-
cd build
65-
cmake ..
66-
make -j 8 clean all
113+
114+
You can also use `make unidasm` to build and install the MAME unidasm tool, or `make clean` to remove build artifacts.
115+
116+
#### Note on YARA-X
117+
118+
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.
119+
120+
#### Windows Manual Build
121+
122+
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.
123+
124+
You can also run individual tasks, e.g. `task build:cmake` or `task run:repl`. Run `task --list` to see all available tasks.
125+
126+
### Makefile (Linux/macOS & Advanced)
127+
128+
The top-level `Makefile` is the single source of truth for build and test logic on POSIX systems. It:
129+
130+
- Installs all required dependencies (Qt5, pkg-config, SDL2_ttf, unidasm, YARA-X)
131+
- Builds the project and runs all tests
132+
- Builds and installs the MAME unidasm tool and YARA-X (`yr`) automatically
133+
134+
To build and test on Linux/macOS:
135+
136+
```sh
137+
make qt5deps # Installs all dependencies, including YARA-X (yr)
138+
make # Builds and runs all tests
67139
```
68140

69-
The preferred executable is `goodasm`. The GUI for iOS and Android is
70-
more of a fun toy than a tool.
141+
You can also use `make unidasm` to build and install the MAME unidasm tool, or `make clean` to remove build artifacts.
142+
143+
#### Note on YARA-X
144+
145+
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.
146+
147+
#### Windows Manual Build
148+
149+
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.
150+
151+
---
71152

72153
## Examples
73154

@@ -304,6 +385,16 @@ interactive mode for iOS and Android. Please don't do real work this
304385
way, but it's handy when studying an instruction set with pen and
305386
paper, away from a real laptop.
306387

388+
### Exiting the REPL
389+
390+
To exit the GoodASM interactive REPL:
391+
392+
- On **Windows**: Press `Ctrl+Z` then Enter
393+
- On **Linux/macOS**: Press `Ctrl+D`
394+
- Or use `Ctrl+C` to interrupt/terminate the REPL
395+
396+
There are no built-in `.exit` or `.quit` commands; only EOF or interrupt will exit the REPL.
397+
307398
## Identification and Grading
308399

309400
It's a frequent problem in embedded systems reverse engineering that
@@ -510,7 +601,6 @@ source of examples for using the library.
510601
languages, so that someday the parser can be rewritten without
511602
breaking code compatibility.
512603

513-
514604
## Similar Assembler/Disassemblers
515605

516606
[Naken ASM](https://github.com/mikeakohn/naken_asm)

‎Taskfile.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
version: '3'
2+
3+
vars:
4+
TARGET: Debug
5+
6+
tasks:
7+
install:qt:
8+
desc: |
9+
Ensure Qt 6 is installed and discoverable by CMake.
10+
- Checks for Qt6Config.cmake or cmake --find-package.
11+
- Installs via package manager if not found.
12+
- On Windows, uses the official Qt installer.
13+
cmds:
14+
- cmd: |
15+
if where /q Qt6Config.cmake || where /q "C:\Qt\6.10.0\msvc2022_64\lib\cmake\Qt6\Qt6Config.cmake"; then \
16+
echo Qt6 is already installed and discoverable by CMake.; \
17+
else \
18+
curl -L -O https://download.qt.io/official_releases/online_installers/qt-online-installer-windows-x64-online.exe && \
19+
qt-online-installer-windows-x64-online.exe --root C:\Qt --accept-licenses --default-answer --confirm-command install qt.qt6.6100.win64_msvc2022_64; \
20+
fi
21+
platforms: [windows]
22+
- cmd: |
23+
if cmake --find-package -DNAME=Qt6 -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST 2>/dev/null; then \
24+
echo Qt6 is already installed and discoverable by CMake.; \
25+
elif [ -f /usr/lib/cmake/Qt6/Qt6Config.cmake ] || [ -f /usr/local/lib/cmake/Qt6/Qt6Config.cmake ]; then \
26+
echo Qt6 is already installed and discoverable by CMake.; \
27+
else \
28+
if command -v apt-get >/dev/null 2>&1; then \
29+
sudo apt-get update && \
30+
sudo apt-get install -y qt6-base-dev qt6-declarative-dev; \
31+
elif command -v brew >/dev/null 2>&1; then \
32+
brew install qt6; \
33+
else \
34+
echo "Please install Qt6 manually."; \
35+
fi; \
36+
fi
37+
platforms: [darwin, linux]
38+
ignore_error: false
39+
40+
install:deps:
41+
desc: Install dependencies (CMake, Qt, Git, NASM, unidasm)
42+
cmds:
43+
- cmd: |
44+
if where /q cmake && where /q git; then \
45+
echo CMake and Git are already installed.; \
46+
else \
47+
cmd /C "winget install -e --id Kitware.CMake" && \
48+
cmd /C "winget install -e --id Git.Git"; \
49+
fi
50+
platforms: [windows]
51+
- cmd: |
52+
if command -v cmake >/dev/null 2>&1 && command -v git >/dev/null 2>&1 && command -v nasm >/dev/null 2>&1 && command -v unidasm >/dev/null 2>&1; then \
53+
echo CMake, Git, NASM, and unidasm are already installed.; \
54+
else \
55+
if command -v apt-get >/dev/null 2>&1; then \
56+
sudo apt-get update && \
57+
sudo apt-get install -y cmake git nasm unidasm || echo "unidasm not available in apt repo"; \
58+
elif command -v brew >/dev/null 2>&1; then \
59+
brew install cmake git nasm unidasm || echo "unidasm not available in brew repo"; \
60+
else \
61+
echo "Please install cmake, git, nasm, and unidasm manually."; \
62+
fi; \
63+
fi
64+
platforms: [darwin, linux]
65+
ignore_error: true
66+
67+
build:cmake:
68+
desc: |
69+
Build the project (Windows: native, POSIX: Makefile)
70+
cmds:
71+
- cmd: cmd /C "if not exist build mkdir build"
72+
platforms: [windows]
73+
- cmd: cmd /C "cd build && cmake -DCMAKE_PREFIX_PATH=C:\Qt\6.10.0\msvc2022_64 .."
74+
platforms: [windows]
75+
- cmd: cmd /C "cd build && cmake --build ."
76+
platforms: [windows]
77+
- cmd: make
78+
platforms: [darwin, linux]
79+
ignore_error: false
80+
81+
test:self:
82+
desc: |
83+
Run GoodASM self-tests (Windows: native, POSIX: Makefile)
84+
cmds:
85+
- cmd: cmd /C "if exist build\{{.TARGET}}\goodasm.exe build\{{.TARGET}}\goodasm.exe --6502 --test else (exit /b 1)"
86+
platforms: [windows]
87+
- cmd: PATH="$(pwd)/build:$(pwd)/build/Debug:$PATH" make
88+
platforms: [darwin, linux]
89+
- cmd: PATH="$(pwd)/build:$(pwd)/build/Debug:$PATH" make selftests
90+
platforms: [darwin, linux]
91+
ignore_error: false
92+
93+
run:repl:
94+
desc: |
95+
Start GoodASM in interactive REPL mode (Windows: native, POSIX: Makefile build first)
96+
cmds:
97+
- task: build:cmake
98+
- cmd: cmd /C "if exist build\{{.TARGET}}\goodasm.exe build\{{.TARGET}}\goodasm.exe --repl else (exit /b 1)"
99+
platforms: [windows]
100+
- cmd: ./build/goodasm --repl
101+
platforms: [darwin, linux]
102+
ignore_error: false
103+
104+
clean:
105+
desc: |
106+
Remove build artifacts (Windows: native, POSIX: Makefile)
107+
cmds:
108+
- cmd: cmd /C "if exist build rmdir /s /q build"
109+
platforms: [windows]
110+
- cmd: make clean
111+
platforms: [darwin, linux]
112+
ignore_error: true
113+
114+
default:
115+
desc: Default build (cross-platform)
116+
deps: [install:qt]
117+
cmds:
118+
- task: build:cmake
119+
120+
all:
121+
desc: Install dependencies, build, and test (cross-platform)
122+
cmds:
123+
- task: install:deps
124+
- task: test:self
125+

‎ensure_task.cmd‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
@echo off
2+
REM Cross-platform ensure_task for Windows (cmd.exe)
3+
where task >nul 2>nul
4+
if %ERRORLEVEL%==0 (
5+
echo [ensure_task] Task is already installed.
6+
exit /b 0
7+
)
8+
9+
where npm >nul 2>nul
10+
if %ERRORLEVEL%==0 (
11+
echo [ensure_task] Installing Task via npm...
12+
npm install -g @go-task/cli
13+
exit /b %ERRORLEVEL%
14+
)
15+
16+
where winget >nul 2>nul
17+
if %ERRORLEVEL%==0 (
18+
echo [ensure_task] Installing Task via winget...
19+
winget install -e --id Task.Task
20+
exit /b %ERRORLEVEL%
21+
)
22+
23+
REM Try choco as a fallback
24+
where choco >nul 2>nul
25+
if %ERRORLEVEL%==0 (
26+
echo [ensure_task] Installing Task via choco...
27+
choco install go-task -y
28+
exit /b %ERRORLEVEL%
29+
)
30+
31+
REM Could not install
32+
>&2 echo [ensure_task] ERROR: Could not find a supported package manager to install Task.
33+
exit /b 1

0 commit comments

Comments
 (0)