Home

Overview

The a2kit package consists of a command line interface (CLI), a few language servers, and a rust library. It manipulates retro disk images, file systems, and 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 executables are maintained for Linux, Mac, and Windows.

Scope

This wiki applies to a2kit version 4.1.0.

Install

• Command Line Interface (CLI)

  • Method 1: download an executable. Visit the release page.
  • Method 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.
  • Optional: Generate shell completions using a2kit completions ... (exact procedure depends on the shell).

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

• Language Servers

  • The language servers are installed along with the CLI. They are used by some editors to provide language support.

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

Smart Copy

For some users the cp subcommand may be all that is needed, e.g. a2kit cp mydisk.woz/hello . will extract the HELLO program to the working directory and put it in a readable format. All such transformations are invertible, i.e., a2kit cp hello mydisk.woz also works. Glob patterns such as a2kit cp mydisk.woz/* . are fully supported, only remember you may have to play with quotes or escapes depending on the shell.

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. If you want to write the textual output to a pipe the --console flag can often be used.

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.