About this manual

Who it is for

This manual is for MSX users who want to write their own programs in Z80 assembly language, and in particular for those who are just starting. It assumes that you know how to use MSX-DOS: how to change drives and directories, list files and run programs. It does not assume that you have used an assembler or a linker before.

If you already program in assembly, you can skip chapter 2. The reference material you are most likely to want is in Parts II and III and in the appendices.

What it does not teach

This manual explains how to use Tatara and Tanren. It does not teach the Z80 instruction set, or how to design and write a program with it; for that you will need a book or course on Z80 assembly programming.

How it is organised

The manual is divided into four parts and a set of appendices.

Part I, Getting started,

says what the tools are, explains how an assembler and a linker work together, installs them, and takes you through building a first program.

Part II, The assembler, Tatara,

describes the assembler: how to run it, how a source file is written, and every feature of the language, from expressions and instructions to macros and conditional assembly.

Part III, The linker, Tanren,

describes the linker: how to run it, how it finds and joins object files, where it places the program in memory, and the kinds of file it can write.

Part IV, Worked guides,

builds a complete program for each of a number of common tasks, such as a program in several files, a binary for MSX-BASIC, or a ROM cartridge.

The appendices

are for looking things up: every directive, instruction, operator, error message and limit in one place.

If you are new to assembly, read Part I in order, and then work through the guides in Part IV, turning to Parts II and III when a guide uses something you want to understand in full. If you are an experienced programmer, chapters 5 and 21 and the appendices will give you most of what you need.

Conventions

What you type is shown in bold typewriter type, as in tatara hello.as hello.tro. What a program prints is shown in plain typewriter type, as in ERROR: undefined symbol in an expression.

An example of a session at the MSX-DOS2 prompt shows both. The prompt is shown as A:\>. When the current directory is not the root directory of the drive, the prompt includes it, as in A:\SOMEDIR\>:

A:\>tanren /v 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools
 

File names are written in upper case in the text, such as HELLO.AS, because that is how MSX-DOS and both programs show them. You can type them in upper or lower case.

Hexadecimal numbers are written the way the assembler reads them, with a trailing h: 0100h is the hexadecimal number 100, which is 256 in decimal.

Tatara and Tanren are the names of the two tools. When the manual means the programs themselves, the files you run, it writes their names in capitals: TATARA and TANREN.

Which version it describes

This manual describes version 1.2.0 of Tatara and Tanren. The latest version of both tools, and of this manual, is published at https://tatara.tools. The programs can be downloaded from https://tatara.tools/download, and the example programs used in this manual from https://tatara.tools/examples.