Setting Up

Introduction

You are going to be assembling and running code hundreds of times over this course, so the loop between writing a line and seeing its effect needs to be short. Set up properly once and it stays out of your way: you press one button, and a second or two later your program is running on an Einstein.

This section is the only one with no assembly in it. By the end you will have an Einstein booting on your own machine, ready for the first program in S3.

If you would rather start straight away, every program in this course also runs in the Assembly Lab, in your web browser, with nothing to install; S3 shows you how. Come back to this section when you want to keep your programs as files of your own.

What you are installing

Five pieces, all free.

The extension drives the assembler and the emulator for you, so once everything is installed you will rarely think about them again.

Installing the tools

These steps are written for macOS. All four tools also run on Windows and Linux, but the install steps below - the Homebrew commands in particular - are macOS specific, so you will need to translate them. Everything after this section is the same on any platform.

1. Homebrew

Homebrew installs the assembler and the emulator in one command each. If you do not already have it, follow the instructions at brew.sh.

Check it is working:

brew --version

2. The assembler and the emulator

brew install z80asm mame

Then confirm both are there:

z80asm --version
mame -version

You should see Z80 assembler version 1.8 and a MAME version number. The course is written against MAME 0.289.

3. Visual Studio Code

Download it from code.visualstudio.com, open the .dmg file that downloads, and drag the Visual Studio Code icon inside it to your Applications folder.

4. The Einstein extension

Download the extension from the Downloads page. You will get a .zip file - unzip it to get the .vsix file inside.

In VS Code, open the Extensions view (View > Extensions), click the ... menu at the top of that panel, choose Install from VSIX..., and select the .vsix file you just unzipped.

You will know it worked when the status bar at the bottom of the window shows Einstein: Stopped.

5. The Einstein ROM

MAME looks for the Einstein's ROM in a file called einstein.zip. Create a folder called roms in your home folder and put it there:

~/roms/einstein.zip

The extension checks that location automatically, so if the file is there, no configuration is needed.

6. Check it

mame -rompath ~/roms einstein -window -skip_gameinfo

A window opens and, after a moment, the Einstein boots:

*** EINSTEIN ***
Insert disc in drive 0 and
press Ctrl-BREAK to load

TATUNG/xtal MOS 1.2      (C) 1983 1984

Ready
>

That > is the machine waiting for you. Close the window when you have seen it. Setup is done.

What that prompt is, and why you can ignore it

The boot screen tells you two things, and both are worth reading properly.

The first is the invitation at the top: insert a disc in drive 0. That is how an Einstein normally starts. At switch-on it looks in the drive, and if a disc is there it reads the beginning of it into memory and runs whatever it finds. Usually that is a disc operating system, which then gives you a fuller prompt where you can list files, load them and start them by name. Sometimes it is a game, which simply begins.

The second is the > underneath, which is what you get when there is no disc. That prompt belongs to MOS, the software built into the machine itself. It is a monitor rather than a command line, meant for inspecting memory and changing it directly. That is genuinely useful if you are working in machine code by hand, and close to useless otherwise. You cannot type a program into it in any language - even the machine's own BASIC lives on a disc, so without one there is nothing to load and nothing to run.

So on a real Einstein you would put a disc in. You do not need one here, because the extension does the equivalent for you. Press Run and it puts your assembled program straight into the machine's memory and sets it going, with the machine sitting at exactly this prompt. No disc, no operating system, nothing to type.

That is a convenience of working under the emulator, and it is the right trade while you are learning. It is the difference between a second and a minute every time you change a line. Later, when you have a game worth handing to somebody, Appendix VIII covers putting it onto a disc image that a real machine will boot on its own.

A note on other Einstein code

The assembler you have just installed is one of several that can build Z80 code, and they do not all accept the same syntax. The instructions are the same everywhere - they belong to the processor - but the way you write a number, or name a block of data, differs from one tool to the next.

This matters the first time you find an Einstein listing somewhere else and it will not assemble. Usually the listing is fine and just needs a small translation. Appendix II - Assemblers Are Not All the Same has the specifics, including one difference that fails silently rather than reporting an error. Worth a look before you paste in code you did not write.

Telling the extension where things are

If a tool is installed somewhere unusual, you can point the extension at it directly instead of relying on PATH. Open VS Code's settings and search for Tatung Einstein:

Leave all three paths blank unless something is actually not being found.

When it goes wrong

Summary

• You have an assembler, an emulator, an editor and the extension that joins them together.
• The extension finds the assembler and MAME on your PATH, and looks for the ROM in a roms folder in your home directory. Nothing needs configuring if they are in those places.
• You have booted an Einstein and seen its Ready prompt.

Next

S3. Your First Program. Getting a character onto that screen - which means meeting the Z80's registers, and the way the Einstein lets a program ask it for something.