Skip to content

Home

Jump to bottom
dfgordon edited this page Jan 15, 2024 · 15 revisions

Overview

The a2kit package consists of a command line interface (CLI), and a rust library. It performs retro disk image manipulations with comprehension of file systems and programming languages. The emphasis is on Apple II, but other platforms like IBM PC and selected CP/M are supported. The package is designed to work with a wide range of modern platforms. Prebuilt CLI executables are maintained for Linux, Mac, and Windows.

Scope

This wiki applies to a2kit version 2.7.0.

Install

  • Command Line Interface (CLI)

    • Option 1: download an executable. Visit the release page.
    • Option 2: use a package manager. You will need the rust toolchain, see rustup. There also needs to be a C compiler in a standard location. Once the toolchain is installed, the CLI is installed by typing cargo install a2kit.
    • Completions (optional): look for the completions directory in the release package (this is not installed with cargo). See the README therein.

  • Rust Library

    • If you want to use a2kit as a library, edit your Cargo.toml to include a2kit under [dependencies].

  • Scripting

    • For scripting you only need the CLI. It is designed to be serviceable as a subprocess.

Using CLI Help

The CLI's built-in help is sometimes the best reference. To get the general help

a2kit --help

To get help for a subcommand, e.g. mkdsk, use

a2kit mkdsk --help

General Principle

The CLI is designed to be useful either as a back-end or stand-alone application. The a2kit command takes as its first argument one of several subcommands, such as get, put, tokenize, etc.. Each subcommand is designed to be serviceable either as a node in a pipeline, or as a stand-alone console interaction. As an example, if one types

a2kit get -f hello -t atok -d hello.dsk

the console will display a hex dump of the tokenized Applesoft program HELLO that is found on the disk image hello.dsk. In order to display the BASIC listing, this can be piped into the detokenize subcommand:

a2kit get -f hello -t atok -d hello.dsk | a2kit detokenize -t atok

There are many other possibilites, see the rest of the wiki pages for more examples.

Contextual Output

If output is going to the console, a2kit will produce a textual interpretation of the data, often involving hex strings. If the output is a file or another pipeline node, binary data remains binary. The textual representations of, e.g., tracks, sectors, and binary files, are intended only for console viewing.

Note on Input Redirection

If you are using a shell that supports input redirection (PowerShell does not), there is sometimes a more compact notation. For example, the following are equivalent:

a2kit get -f prog.bas | a2kit tokenize -t atxt -a 2049
a2kit tokenize -t atxt -a 2049 < prog.bas

PowerShell Caveat

If you want to use PowerShell, please use version 7.4 or higher. This allows raw binary to flow through the pipeline unmolested.

Clone this wiki locally