Tatara

Chapter 3
Installation

This chapter takes you from the downloaded files to an MSX on which TATARA and TANREN run from any directory and find the include files. The installation it describes is the one the rest of the manual assumes: every session from here on is shown with these directories.

3.1 What you get

Tatara is distributed as one archive, a file that holds several files packed together. It is named TATARxyz.ZIP, where xyz is the version: TATAR120.ZIP is version 1.2.0. You download it from https://tatara.tools/download. It holds a whole installation, already arranged in directories, as table 3.1 shows.

File or directory

What it holds

BIN

TATARA.COM, the assembler, and TANREN.COM, the linker

INCLUDE

the include files (chapter 14)

EXAMPLES

the example programs of this manual, one directory each

README.TXT

the version, and the address of the web site

LICENSE

the Apache License 2.0, under which Tatara is distributed

Table 3.1: What the archive holds.

The archive is unpacked on the MSX with UNKAGO, a decompressor for ZIP, LZH and PMA archives. UNKAGO is required: it is what unpacks the archive on the MSX, and it does not come with MSX-DOS2 or Nextor. Download UNKAGO.COM from https://kago.tools/en/download/. Like TATARA and TANREN, it runs under MSX-DOS2 or Nextor.

Note.  Earlier releases were distributed as .LZH archives, such as TATAR117.LZH. They hold no directories, so they are not installed as this chapter describes. This chapter describes the .ZIP archive.

This manual assumes that you download the two files on another computer, such as a PC or a Mac, and copy them to the MSX, for instance on a memory card.

3.2 Where the files go

The manual assumes that the archive is unpacked into A:\TATARA, which gives the directories below.

A:\TATARA\ 
    BIN\         TATARA.COM and TANREN.COM 
    INCLUDE\     the include files 
    EXAMPLES\    the example programs, one directory each 
    README.TXT 
    LICENSE
 

Any other place works just as well, as long as two things are true: the directory that holds the two programs is on the PATH, and the TATARA environment variable names the directory that holds the include files. Section 3.4 explains both. The rest of the manual shows A:\TATARA; if you install elsewhere, read your own directories in its place.

Note.  A Japanese MSX shows the backslash as a yen sign, so the directory above appears as A:¥TATARA¥INCLUDE. It is the same character, and the paths in this manual work as they are.

3.3 Installing, step by step

Copy TATAR120.ZIP and UNKAGO.COM to the MSX, both into the same directory. Any directory will do, because UNKAGO is told where to put the files; the example below has them in the root directory of drive A:.

  1. Unpack the archive into A:\TATARA. In the directory that holds the two files, run UNKAGO with the switch /D: and the directory to unpack into. UNKAGO creates A:\TATARA if it does not exist, and the directories inside it.

    A:\>unkago /d:a:\tatara tatar120.zip 
    UNKAGO LZH/PMA/ZIP Decompressor v1.0.1 
    Copyright (C) 2026 Javier Lavandeira 
    https://kago.tools 
     
    Extracting BIN\ OK 
    Extracting BIN\TATARA.COM OK 
    Extracting BIN\TANREN.COM OK 
    Extracting INCLUDE\ OK 
    Extracting INCLUDE\WORKAREA.INC OK 
    ... 
    Extracting EXAMPLES\TWOMOD\TWOMOD.LNK OK 
    Extracting README.TXT OK 
    Extracting LICENSE OK
     
    

    UNKAGO prints one line for each directory and file in the archive, fifty in all, and each line should end in OK. The list above is shortened in the middle.

  2. Check. dir a:\tatara\bin should list TATARA.COM and TANREN.COM, dir a:\tatara\include the ten files in table 3.2, and dir a:\tatara\examples eight directories, one for each example.
  3. Tidy up. TATAR120.ZIP is not needed any more, and you can delete it. Keep UNKAGO.COM: an update is unpacked with it too (section 3.6).

File What it holds
ASCII.INC the control codes
BIOS.INC the MAIN ROM entry points
ERRORS.INC the MSX-DOS and MSX-DOS2 error codes
EXTBIO.INC the extended BIOS, and the MSX-MUSIC FM BIOS
HOOKS.INC the hooks
MSXDOS.INC the MSX-DOS function numbers, and the system macro
PORTS.INC the I/O ports
SUBROM.INC the SUB ROM entry points
WORKAREA.INC the system work area
README.TXT a short description of the files
Table 3.2: The files in A:\TATARA\INCLUDE.

3.4 Setting PATH and TATARA

An environment variable is a name that holds a piece of text, which MSX-DOS2 keeps in memory and which programs can read. The installation needs two of them.

PATH

When you type a command, MSX-DOS2 looks for a program of that name in the current directory, and then in every directory named in PATH. Adding A:\TATARA\BIN to it lets you run TATARA and TANREN from any directory.

TATARA

When a source file includes another file, TATARA looks for it in the directory of the source file, then in the current directory, and then in every directory named in TATARA. Setting it to A:\TATARA\INCLUDE lets every program include the files of table 3.2 without a copy of them. Chapter 13 gives the full rule.

To set them for the session you are in, type:

A:\>set path=%path%;a:\tatara\bin 
A:\>set tatara="a:\tatara\include"
 

%path% stands for what PATH already holds, so the first line adds the new directory to the end of it rather than replacing it. Type set on its own to see every environment variable and its value; your PATH will show directories of your own before the new one.

Note.  At the MSX-DOS2 prompt, write the value of TATARA between quotation marks, as above. Without them, MSX-DOS2 answers *** Invalid environment string and does not set the environment variable. In AUTOEXEC.BAT, below, the quotation marks are not needed.

An environment variable set this way lasts until the MSX is reset or switched off. To set both every time the MSX starts, add the two lines below to AUTOEXEC.BAT, the batch file in the root directory of the boot drive that MSX-DOS2 runs when it starts. If you do not have one, create it with a text editor. It can already hold commands of its own; add the two lines at the end:

set path=%path%;a:\tatara\bin 
set tatara=a:\tatara\include
 

Note.  TATARA can name several directories, separated by semicolons, in the same way as PATH. This is useful when a project has include files of its own (chapter 13).

Note.  TANREN has an environment variable of its own, TANREN, which names the directories where it looks for object files. This installation does not need it (chapter 23).

3.5 Checking the installation

From any directory, run each program with the option /V. It prints the program’s name and version, and does nothing else.

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

If MSX-DOS2 answers as below instead, PATH does not include A:\TATARA\BIN. Check it with set, and set it again as in section 3.4.

A:\>tatara /v 
*** Unrecognized command
 

The TATARA environment variable is checked in chapter 4, when the first program includes MSXDOS.INC.

3.6 Updating

A new version is unpacked in the same way, with the switch /O added:

A:\>unkago /o /d:a:\tatara tatarxyz.zip
 

Without /O, UNKAGO does not replace files that already exist: it prints Skipping BIN\TATARA.COM: it already exists for each one, and the old version stays. /V shows which version each program is.

Warning.  /O replaces the examples too. Before you change an example, copy its directory somewhere else and work on the copy, or the next update will overwrite your changes.