Quick start

Boot CP/M with one command. From the folder you unzipped this into:

$ ./altairsim examples/cpm/cpm22-buffered.toml

On Windows, the path is spelled with backslashes and the program is altairsim.exe:

> altairsim.exe examples\cpm\cpm22-buffered.toml

On macOS, if you got the package with a browser, macOS blocks the program until you remove its download mark. Type this first, one time for each download:

$ xattr -dr com.apple.quarantine ./altairsim

If macOS shows a message about the program, press Done, not Move to Trash.

That is the whole of it. The machine file boots itself — you do not type a BOOT command, because an Altair had none — and a few seconds later you are in CP/M:

56K CP/M 2.2b v2.3
For Altair 8" Floppy

A>

It is 1977. Type DIR to see what is on the disk:

A>DIR

An assembler, a debugger, Microsoft BASIC, a text editor, and a game or two are on there. Run one — A>MBASIC starts Microsoft BASIC.

The three keys to remember

You are talking to CP/M, the software the CPU is running. Two prompts share the window: A> is CP/M, and altairsim> is the simulator's own monitor. You move between them with these:

^C is not how you get out — that belongs to CP/M, which warm-boots on it. Use ^E.

The disk is real — there is no undo

The disk is mounted read/write, because that is what a machine with a disk in it is. Anything you do in CP/M happens to the file on your host, and nothing keeps a spare copy. Two ways to stay safe:

• Look around read-only. Add RO when you mount, and every write is refused at the controller so the file cannot change.
• Copy the folder first when you mean to write. It is self-contained and boots from anywhere:

$ cp -R examples/cpm my-cpm $ ./altairsim my-cpm/cpm22-buffered.toml

One trap worth knowing: this CP/M buffers a whole track and only flushes it the next time it reads the console, so get back to the A> prompt before you quit or copy the image, or the last write never lands.

Where the files come from

You named one path — the machine file — and the simulator found the disk on its own. One rule covers all of it:

• The machine file you name on the command line is found from the folder you are in — your shell. That is the one path you hand to the shell, before any machine exists.
• Everything after resolves against the machine's own folder — the directory that .toml lives in. The disk it mounts, and the MOUNT, LOAD, SAVE and DO you type at the altairsim> prompt, all come from there. cpm22-buffered.toml mounts cpm22b23-56k.dsk from beside itself — and if you type MOUNT dsk0:drive1 cpm22b23-56k.dsk you get that same file, from that same folder.

For example, from the folder you unzipped into:

$ pwd
/home/you/altairsim
$ ./altairsim examples/cpm/cpm22-buffered.toml

examples/cpm/cpm22-buffered.toml is found from where you are; the cpm22b23-56k.dsk it mounts — and anything you later type at the prompt — is found in examples/cpm/, beside the machine.

That is why every folder under examples/ boots wherever you copy it: the disk travels with the .toml that names it, and so does everything you do to that machine. altairsim never changes your working directory.

To see it, ask the machine: SHOW PATHS at the altairsim> prompt prints the base directory — and the hostbridge sandbox, the one folder kept separate:

• the base directory — the machine's own folder; what a machine file mounts and what you type both resolve against it;
• the sandbox root — the one folder the hostbridge file-transfer board may reach, and cannot escape.

The leading ./ means the altairsim in this folder — a fresh unzip is not on your PATH, so you point at it. Copy the program into a directory on your PATH (/usr/local/bin on macOS or Linux) and you can drop the ./ and type just altairsim from anywhere, including from inside an example folder: cd examples/cpm && altairsim cpm22-buffered.toml.

No disk? Boot a tape instead

Every folder under examples/ is a complete machine with its media already inside it, so any of them comes up the moment you name it:

$ ls examples/
$ ./altairsim examples/basic4k/basic4k.toml

examples/basic4k/ toggles in the MITS bootstrap by hand and loads Altair 4K BASIC off a cassette — the machine that shows you what an Altair actually was. Each folder carries its own README.pdf describing what it is and what to type. More examples, and their documentation, are at https://altairsim.com.

Where to go next

altairsim-manual.pdf is the full User Manual — the same quick start above at more length, then the machines, the disks and tapes, the S-100 boards, and the file-transfer utilities in hostbridge/. altairsim-monitor.pdf and altairsim-debugger.pdf cover the altairsim> prompt and the built-in debugger. If you are coming from AltairZ80 (SIMH) or z80pack, read migrating.pdf first.