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.LZH, where xyz is the version: TATAR120.LZH is version 1.2.0. You download it from https://tatara.tools/download. It holds five files, listed in table 3.1.

An .LZH archive is unpacked on the MSX with PMEXT. It does not come with MSX-DOS2 or Nextor, and it is no longer distributed anywhere else, so a copy is at https://tatara.tools/download too.

The example programs are a separate download, from https://tatara.tools/examples. They are a set of directories, one for each example, not an archive.

This manual assumes that you download the 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 the directories below, on drive A:.

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

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.

3.3 Installing, step by step

Before you start, copy TATAR120.LZH and PMEXT.COM to the root directory of drive A:.

1. Create the directories.

   A:\>md a:\tatara 
   A:\>md a:\tatara\bin 
   A:\>md a:\tatara\include
    
   

2. Unpack the archive into A:\TATARA. PMEXT cannot be given a path for the archive, so copy the archive into the directory first, and unpack it there. The a: at the end tells PMEXT to write the files to the current directory of drive A:.

   A:\>cd a:\tatara 
   A:\TATARA>copy a:\tatar120.lzh . 
   A:\TATARA>pmext tatar120.lzh a: 
    
   PMext Version 2.22 for 34K CP/M(Z80) 
   Copyright(C) 1990,1991 by Yoshihiko Mino. 
   Time stamp supported for MSX-DOS(2) 
    
   Archive file = TATAR120.LZH 
   Output device= A: 
    
   TATARA  .COM Extracting 00ED/00ED OK 
   TANREN  .COM Extracting 0066/0066 OK 
   INCLUDES.LZH Extracting 0185/0185 OK 
   README  .TXT Extracting 0002/0002 OK 
   LICENSE .    Extracting 005B/005B OK 
    
   End of archive.
    
   

   PMEXT lists each file as it unpacks it. The numbers after Extracting depend on the size of each file, so they differ from one version of Tatara to another. What matters is the OK at the end of each line.

3. Move each file to its directory: the two programs to BIN, and the include archive to INCLUDE.

   A:\TATARA>move tatara.com bin 
   A:\TATARA>move tanren.com bin 
   A:\TATARA>move includes.lzh include
    
   

   README.TXT and LICENSE stay in A:\TATARA.

4. Unpack the include files.

   A:\TATARA>cd include 
   A:\TATARA\INCLUDE>pmext includes.lzh a: 
    
   PMext Version 2.22 for 34K CP/M(Z80) 
   Copyright(C) 1990,1991 by Yoshihiko Mino. 
   Time stamp supported for MSX-DOS(2) 
    
   Archive file = INCLUDES.LZH 
   Output device= A: 
    
   WORKAREA.INC Extracting 00D5/00D5 OK 
   HOOKS   .INC Extracting 0045/0045 OK 
   BIOS    .INC Extracting 0098/0098 OK 
   ASCII   .INC Extracting 001C/001C OK 
   PORTS   .INC Extracting 007F/007F OK 
   SUBROM  .INC Extracting 003A/003A OK 
   EXTBIO  .INC Extracting 0091/0091 OK 
   ERRORS  .INC Extracting 006D/006D OK 
   MSXDOS  .INC Extracting 003A/003A OK 
   README  .TXT Extracting 0013/0013 OK 
    
   End of archive.
    
   

   The two archives are not needed any more, and you can delete them:

   • A:\TATARA\TATAR120.LZH
   • A:\TATARA\INCLUDE\INCLUDES.LZH
5. Copy the examples. On the other computer, copy the example directories you downloaded into A:\TATARA\EXAMPLES on the MSX’s disk or memory card, keeping one directory for each example: EXAMPLES\HELLO, EXAMPLES\TWOMOD, and so on. This is the only step that is done outside the MSX.
6. Check. dir a:\tatara\bin should list TATARA.COM and TANREN.COM, and dir a:\tatara\include should list the ten files in table 3.2.

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.

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
 

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 installed in the same way, and its files replace the old ones. /V shows which version each program is.