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 |
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:.
-
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.
- 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.
- 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 |
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.