amitools

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 needs pip.

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).

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

Tool	Purpose	Docs
xdftool	Create, inspect and modify ADF and HDF disk images: format, list, read, write, delete, pack and unpack whole images, boot blocks, bitmaps	xdftool
xdfscan	Scan single images or whole directory trees of ADF/HDF files and verify their file systems	xdfscan
rdbtool	Create and edit hard disk images and devices with a Rigid Disk Block: partitions, file system drivers, geometry	rdbtool
romtool	Scan, split, patch and build Kickstart ROM images for emulators, soft kickers and flash ROMs	romtool
icontool	List and batch edit Workbench .info icon files: tool types, positions, structure fields, PNG import and export	icontool
vamos	Run AmigaOS command line programs on the host: the Virtual Amiga OS	vamos, reference, libraries
vamospath	Convert between AmigaOS and host paths using a vamos configuration
vamostool	Helpers around vamos: path conversion, type inspection, library profile dumps and state file info
hunktool	Load and dump Amiga Hunk executables, libraries, object files and overlays
typetool	Inspect the AmigaOS C structure definitions vamos uses
fdtool	Read Commodore’s .fd function description files and dump them in several formats, including vamos’ code structures
geotool	Detect and compute disk geometries (cylinders, heads, sectors) for image files and sizes

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:

Package	Contents
amitools.fs	OFS and FFS file systems, block devices and image files, Rigid Disk Blocks and partitions
amitools.binfmt	Readers for Amiga Hunk binaries (binfmt.hunk) and the ELF subset used by AROS m68k (binfmt.elf), with relocation
amitools.rom	Kickstart ROM parsing, splitting and building
amitools.icon	Workbench .info icon files
amitools.fd	Parser for .fd function description files
amitools.scan	Scanners that walk file trees, .lha archives and disk images
amitools.vamos	The vamos runtime: machine, memory, scheduler, library and device implementations

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.

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 black: 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 black before submitting.

License and authors

amitools is written by Christian Vogelgsang [email protected], with contributions from many others, and is licensed under the GNU General Public License version 2 or later.