Published on October 2nd, 2026
For the last few months I've been writing an assembler on my free time. Not a cross-assembler that runs on a PC and spits out a file for the MSX, but a macro assembler and linker that run on the MSX itself, under MSX-DOS2 or Nextor. Today I'm releasing version 1.2.0. It's called Tatara, and its linker is called Tanren.
Why write another assembler?
There's no shortage of ways to assemble Z80 code for the MSX. But I like to actually use the MSX to do MSX development work. Editing, assembling and running on the same machine is half the fun for me, and it's also the best way to keep in mind what the machine can and can't do.
The problem is the tools. The two assemblers that run on the MSX and that most people use are M80 (with its linker, L80) and SOLiD's AS/LD, and both frustrated me for years:
- M80 was written for CP/M. It doesn't know that directories exist, so every file of a project has to sit in the same place. It keeps only the first six characters of a symbol name, which is why so much MSX code is full of names like PRTSTR. And it runs out of memory when a program gets big, because everything has to fit in the 64 KB the Z80 can see, next to M80 itself.
- AS/LD improved some of this, but its directory support is iffy, and when something went wrong in an included file, or in a line produced by a macro, finding the line that actually caused the error was a pain in the ass.
- The documentation is either bad or missing. M80's manual dates from the CP/M days and is badly out of date. AS/LD has, as far as I know, no manual at all.
That last point bothers me the most. Newcomers to the platform are often put off by tools that are hard to set up and impossible to look things up in. I thought that an assembler with a proper manual could make that first step a lot less intimidating.
Could I actually do this?
I'd never written an assembler before. What convinced me it was doable was David Salomon's book Assemblers and Loaders, which explains the high-level concepts very clearly: two passes, symbol tables, relocatable object files, and what a linker does with them. After reading it I could see how the pieces fit together, and how to make them fit on an MSX.
The part the book couldn't solve for me was memory. A big source has a big symbol table, macros need somewhere to keep their text, and the linker needs somewhere to build the program. None of that fits in 64 KB together with the tools themselves. The answer was the memory mapper, so before going any further I wrote MapperHeap, a small library that hands out blocks of mapper memory the way malloc() and free() do in C. Tatara and Tanren keep all their tables in it, so the size of the program you can build depends on how much memory your MSX has, not on how much MSX-DOS leaves free.
What it can do
The main features:
- It runs on the MSX. Any MSX2, MSX2+ or MSX turbo R with MSX-DOS2 or Nextor.
- It reads M80 syntax. Most M80 sources assemble with few or no changes, and the manual has a checklist for converting the rest.
- Long symbol names, up to 255 characters, and optionally case-sensitive.
- Directories and environment variables. Include files are looked for in three places, and the TATARA and TANREN variables set the search paths.
- Macros, conditional assembly and repeat blocks.
- Named segments, so you can place all your music-related data in a single contiguous segment in memory even if that data is all over the place in the source files, or place all the UI code from several sources in a single segment.
- Shared variable memory using transient data segments, which let variables that are never needed at the same time share memory without working out the addresses by hand.
- Several kinds of output: .COM programs, BLOAD binaries for MSX-BASIC, and ROM cartridge images.
- Ready-made include files with over 900 entries MSX-DOS2 functions, BIOS entries, system variables, hooks and I/O ports, so you don't have to track them down and type them yourself.
But a list of features doesn't say much, so here are a few things I can do now that I couldn't before.
Errors that point to the right line
This is the one that made me start the project. When an error happens deep inside include files and macros, Tatara tells you where it is, and how it got there:
That's an error inside a repeat block, inside a macro, inside another macro, used from an include file. Every line of the message names a file and a line number, so you can follow it back to the line you wrote.
Names that say what they mean
No more six-letter names. These two symbols are 48 characters long and differ only in their last five characters, and Tatara keeps them apart, in one module and across modules:
Also, the assembler supports enabling case-sensitivity, so the symbols Counter and counter can refer to different variables:
These two put together are a requirement if someone was considering writing something like a modern ANSI-C compiler for MSX.
No more 127-character command lines
MSX-DOS cuts a command line at 127 characters, which a program built from many modules reaches very quickly. For example in the early stages of development I had to rename the module names to 3-letter filenames so they could fit in the linker's command line:
Now Tanren can read its list of files and all options from a text file instead, so we don't need to worry anymore about long command lines:
Sharing memory with transient segments
Two routines that never run at the same time can put their buffers in different groups of a transient segment, and Tatara and Tanren place them at the same address. This helps save memory in larger programs, because different variables or buffers can share the same memory addresses. This is handled by the assembler and linker transparently to the programmer.
The manual
I said one of my goals was good documentation, so I took the manual as seriously as the code. It's a full book (390 pages), in English and Japanese, online and as a PDF. It starts with how an assembler and a linker work, for people who have never used one, and ends with worked examples that go from a program in two modules to a ROM cartridge. Every example in it was assembled and run under MSX-DOS2 while I wrote it, and every error message is listed in an appendix with an explanation of what causes it.
Where the names come from
Both names come from how Japanese swords are made. A tatara (たたら) is the clay furnace that turns iron sand and charcoal into raw steel. Tanren (鍛錬) is the forging that turns that steel into a blade. The assembler turns your source into object files, which are machine code but not yet a program, and the linker forges them into the finished program.
Get it
Tatara is free and open source, under the Apache License 2.0. You'll need an MSX2 or later with MSX-DOS2 or Nextor, or an emulator such as openMSX.
If you try it, I'd love to hear what you build with it, and if something doesn't work, please open an issue on GitHub.