amitools - AmigaOS tools for other platforms

amitools is a set of command line tools and Python libraries for working with classic Amiga disk images, file systems, Kickstart ROMs, icons and executables on macOS, Linux and Windows. Its centrepiece, vamos, runs AmigaOS command line programs directly on the host by emulating the 68k CPU and the AmigaOS API.

The tools target the classic 680x0 Amiga with AmigaOS 1.x to 3.x and are written for developers, so a background in Amiga programming helps.

• Documentation: https://amitools.readthedocs.io/
• Source and issues: https://github.com/cnvogelg/amitools
• Releases: https://pypi.org/project/amitools/, change log

Installation

amitools supports Python 3.11 through 3.15 and can be installed with pip or uv.

Tools only

pip install amitools

This installs the pure Python package: all tools except vamos work out of the box.

With vamos

vamos needs the 68k CPU emulator from the machine68k package, which the vamos extra pulls in:

pip install 'amitools[vamos]'

machine68k is a C extension published as a source package, so a C compiler has to be available (Xcode command line tools on macOS, gcc on Linux, Visual Studio Build Tools on Windows).

With uv, install the command-line tools in an isolated environment:

uv tool install amitools

To include vamos and its emulator dependency:

uv tool install 'amitools[vamos]'

Latest development version

pip install -U git+https://github.com/cnvogelg/machine68k.git
pip install -U git+https://github.com/cnvogelg/amitools.git

Repeat the commands to update. The development version has the newest features but may be unstable from time to time.

Optional packages

• lhafile lets the file scanners look inside .lha archives.
• pypng is needed by icontool to import and export PNG images.

Tools

Every tool prints its usage with -h or help.

Quick examples

# list a floppy image, then read a file from it to the current directory
xdftool wb310.adf list
xdftool wb310.adf read c/dir

# create a new disk, format it and copy a file in, all in one command line
xdftool test.adf format "My Image" + makedir c + write myfile c

# create a 10 MiB RDB hard disk image with one partition
rdbtool work.hdf create size=10Mi + init + fill

# check a whole directory tree of disk images
xdfscan my_disks

# show what is inside a Kickstart ROM
romtool scan kick31.rom -i

# run an Amiga program; -V maps a host directory to an Amiga volume
vamos -V work:/path/to/dir myprog

Python libraries

The tools are built on packages you can use in your own code:

The vamos library API is described in the library documentation.

Development

Clone the repository and set up an editable install with the development and test requirements:

git clone https://github.com/cnvogelg/amitools.git
cd amitools
make init

make init installs machine68k from its git repository, the test and documentation tools, and amitools itself in editable mode, so edits in the tree take effect immediately.

To set up the same environment with uv, create and activate a virtual environment, then install the existing development and test requirements:

uv venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
uv pip install -r requirements-dev.txt -r requirements-test.txt -e .

Tests

The unit tests run in a few seconds:

pytest test/unit

pytest test also runs the vamos test suite, which executes the prebuilt Amiga test programs under vamos and compares their output with recordings from real Amigas; add --full-suite for the slow tests as well. make test runs everything through tox for all supported Python versions. Rebuilding the test programs needs the cross compilers described in test/README.md.

Code style and docs

The code is formatted with Ruff: make format. The documentation is Sphinx; make docs builds it into build/docs/html.

Contributing

Bug reports and pull requests are welcome on GitHub. Please add a unit test for a fix where possible and run ruff format . before submitting.

License and authors

amitools is written by Christian Vogelgsang chris@vogelgsang.org, with contributions from many others, and is licensed under the GNU General Public License version 2 or later.