DOCSEARCHbyAlgolia
Submit Docs

amitools

repository·main·Indexed 18 days ago

https://github.com/cnvogelg/amitools

A collection of Python 3 tools and libraries for working with AmigaOS binaries and files on macOS and Linux. It includes CLI utilities such as vamos (a Virtual Amiga OS emulator), xdftool, xdfscan, rdbtool, romtool, hunktool, typetool, and fdtool, as well as libraries for parsing Hunk and ELF formats, Amiga APIs (.fd files), and OFS/FFS file system structures.

Tokens
26.5K
Snippets
97
Records
123
Agent score
62%

What's inside amitools

  1. Overview of amitools tools and libraries

    main
    The amitools project provides a suite of command-line tools and Python libraries designed to assist developers in cross-developing for the Amiga computer system. The toolkit includes specialized utilities for handling disk images, partitions, and ROM files.

  2. Overview of amitools CLI tools

    main

    The amitools package provides several command-line utilities for working with AmigaOS files and binaries:

    • vamos: A Virtual Amiga OS emulator. It is an API-level emulator that runs CLI Amiga programs on macOS/Linux/PC by replacing exec and dos calls with its own implementation and mapping file access to your local filesystem. Requires machine68k.
    • xdftool: Used to create and modify ADF or HDF disk image files.
    • xdfscan: Scans directory trees for ADF or HDF disk image files and verifies their contents.
    • rdbtool: Used to create or modify disk images with Rigid Disk Block (RDB).
    • romtool: Inspects, dissects, and builds Amiga Kickstart ROM images for use with emulators, soft kickers, or flash ROMs.
    • hunktool: Uses the hunk library to load and display the contents of hunk-based Amiga binaries, libraries, object files, and overlayed files.
    • typetool: A companion for vamos that dumps and provides information on the AmigaOS API C structures used in vamos.
    • fdtool: Reads Commodore's .fd (function description) files and dumps their contents, including jump table offsets and code structures used in vamos.

  3. Use xdftool to manage Amiga disk images

    main

    The xdftool is a command-line utility used to manage Amiga disk images (such as .adf or .hdf files). It allows you to inspect, extract, create, and modify the contents of these images.

    Key capabilities include:

    • Reading and displaying contents of ADF or HDF files.
    • Creating new ADF or HDF images.
    • Copying files from an image to your local system.
    • Copying local files into an image.
    • Mastering new images or repacking existing ones.
    • Working with partitions inside RDISK/RDB HDF images or real disks.
    xdftool <image.adf|image.hdf> <command> [option]

  4. Use rdbtool to manage Amiga disk partitions

    main

    The rdbtool is a command-line utility used to inspect or create Rigid Disk Block (RDB) partitions compatible with classic Amiga computers. It allows you to manage the partition layout and file system information stored in the first blocks of a disk.

    Note: If your goal is to manipulate files within a DOS partition rather than the partition layout itself, use xdftool instead.

  5. Unpack, Pack, and Repack disk images

    main

    Advanced workflows for converting between disk images and host file systems.

    Unpacking: Extracts the entire volume to a host directory. It creates a <volume>.xdfmeta file to preserve metadata (protection, comments, timestamps) and a <volume>.bootcode file if the image is bootable. Use the fsuae option to generate .uaem files for FS-UAE compatibility.

    Packing: Reconstructs an image from a host directory. If a .xdfmeta file exists, metadata is restored. If a .bootcode file exists, the image becomes bootable. For HDF, you must specify blkdev_size or provide a <volume_dir>.blkdev file.

    Repacking: A single-step command to rebuild an image (often for defragmentation or resizing) without intermediate host file system extraction. It combines unpack and pack on the fly.

    # Unpack an image to the current directory with FS-UAE metadata
xdftool mydisk.hdf unpack . fsuae

# Pack a directory back into a 10MB HDF image
xdftool newimg.hdf pack Dir 10M

# Repack an old image into a new one (defragmentation)
xdftool new.adf repack old.adf

  6. Configure library path mapping

    main

    When an OpenLibrary() call is made, vamos searches for Amiga files using the following logic:

    • Base name (no path): Searched within the LIBS: assign. Multi-assigns are supported, and all locations in the multi-assign are searched.
    • Relative path: Searched in the current working directory of the emulated process.
    • Absolute path: Searched only at the specified location.

  7. Understand library types in vamos

    main

    vamos handles three distinct types of libraries to emulate Amiga software without requiring original hardware or ROMs:

    1. Amiga (m68k): Original libraries from a real Amiga system.
    2. Vamos (Python): Python-based libraries that replace original OS functions (like exec or dos). These require an associated .fd file so vamos knows the function structure and call counts. They appear in emulated memory as regular libraries.
    3. Fake: A Vamos library with no actual implementation. All functions are treated as dummy functions that simply return 0 in d0.

    Note: exec.library and dos.library must remain as Vamos type libraries for vamos to function correctly.

  8. Configure library versions and profiling

    main

    You can manipulate how libraries report their version and performance:

    • Lib Versions: You can use the version option to overwrite the library's version number. This allows you to pretend a library is an older version to match the requirements of an OpenLibrary call.
    • Lib Profiling: By setting profile = True, vamos adds measurement instructions around the Python code of a Vamos library. This provides detailed execution time data but is computationally expensive and should only be used for specific libraries you intend to debug.

  9. Configure libraries in .vamosrc

    main

    Library settings are managed in the .vamosrc configuration file using sections. The manager searches for configuration in this specific order:

    1. Path prefix: If the library name contains a path, it looks for a section matching that path prefix (e.g., [libs/foo.library]).
    2. Base name: A section matching the library name without a path (e.g., [foo.library]).
    3. Default section: The [* .library] section.
    4. Internal defaults: If no section is found, vamos uses its built-in defaults.

    Available Options

    Each section can use the following keys:

    • mode: off, auto, amiga, vamos, fake
    • expunge: last_close, no_mem, shutdown
    • version: <number> (e.g., 39)
    • profile: True or False
    [icon.library]
mode=fake
version=40

[68040.library]
mode=off

[dos.library]
profile=True

[libs/foo.library]
mode=off

[foo.library]
mode=amiga

  10. Inspect Amiga disk images with xdftool

    main

    Use xdftool to view the contents and metadata of Amiga disk images (ADF, HDF, etc.) without mounting them.

    Key inspection commands:

    • list: Displays files and directories. Use all for recursion, info for statistics (blocks, bytes), and detail for storage details.
    • type <ami_path>: Dumps file contents to stdout.
    • info: Shows total, used, and free blocks/bytes for the entire image.
    • blkdev: Shows cylinder, head, and sector counts for the underlying block device.
    • read <ami_path>: Extracts a file or directory tree to your host system.
    # List all files in the image recursively with info
xdftool test.adf list / all info

# View file contents
xdftool wb310.adf type s/startup-sequence

# Extract a directory to the current host directory
xdftool wb310.adf read devs .

  11. Install amitools

    main

    You can install amitools via pip3. Depending on your needs, choose one of the following methods:

    Standard Installation

    To install the core Python tools (without the vamos emulator):

    pip3 install amitools

    To install the core tools plus the vamos emulator (requires the machine68k dependency):

    pip3 install 'amitools[vamos]'

    Installation from GitHub (Latest Features)

    If you need the most recent changes or features from the development branch, install directly from GitHub. If you want vamos, you must install machine68k first.

    With vamos support:

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

    Without vamos support:

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

    Developer Setup

    To contribute to the codebase, clone the repository and install it in editable mode:

    pip3 install cython machine68k
pip3 install -U -e .
    pip3 install amitools

  12. Manage boot blocks with xdftool

    main

    The boot command allows you to inspect and modify the disk's boot block.

    • boot show [hex] [asm]: Displays the boot block. Use hex for a hex dump or asm for disassembly (requires vda68k).
    • boot read <file>: Saves the boot code to a host file.
    • boot write <file>: Writes boot code from a host file to the image (automatically adjusts checksum).
    • boot install [boot1x]: Makes the disk bootable by writing standard WB 2.x/3.x boot code (or 1.x if specified).
    • boot clear: Removes boot code and invalidates the checksum.
    # Make a disk bootable
xdftool my.adf boot install

# View boot code as assembly
xdftool my.adf boot show asm