Chapter 22
Link files

A link file holds the words of a TANREN command line, the names of the object files and the options, in a text file. tanren @prog reads the file PROG.LNK and takes its words as if they had been typed where @prog stands. A link file has no limit of 127 characters (section 21.5), and it keeps the list of a program’s modules in one place, with comments, so that every link uses the same list.

22.1 A first link file

This link file links the program of chapter 21:

; PROG.LNK - the two modules of the example program. 
 
main            ; the start of the program: it must come first 
sub             ; greet 
 
/o:prog.com     ; the output file
 

It names the two object files, MAIN.TRO and SUB.TRO, and the output file, PROG.COM. The command line names only the link file:

A:\>tanren @prog 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
2 modules, 16 records, ends at EOF. 
Wrote PROG.COM, 0100-0125 (38 bytes), entry 0100. 
A:\>prog 
Hello from TANREN.
 

22.2 Writing a link file

A link file is a text file, written with any editor. It holds the same words as a command line, with these rules:

• Words are separated by spaces, tabs or the ends of lines. A line can hold one word, several, or none: ONELINE.LNK, which holds main sub /o:one.com on a single line, does the same as PROG.LNK, except for the name of the output file.
• A semicolon starts a comment, which runs to the end of the line. A comment can have a line of its own or follow the words of a line.
• An object file named without an extension gets .tro, as on the command line.
• Options are words like any other, and can be anywhere in the file.
• The file ends at its last character, or at a Ctrl+Z if it has one. The last line does not need to end with a line end.

The name after @ gets .lnk if it has no extension, so tanren @prog and tanren @prog.lnk read the same file. TANREN opens the link file with the name as written, in the current directory unless the name includes a path.

22.2.1 A program too big for the command line

TATARA itself is made of nineteen modules, and is linked with this link file (its first lines, a comment, are left out here):

tatara.tro                              ; the driver 
cmdline.tro srcline.tro fields.tro      ; the front 
dirtab.tro macros.tro expand.tro        ; directives and macros 
cond.tro expr.tro                       ; conditionals and expressions 
symtab.tro optab.tro insn.tro           ; the tables and the back end 
emit.tro objout.tro errs.tro 
 
msxdos.tro strutil.tro alloc.tro hash.tro       ; shared
 

The names of the nineteen object files alone take 198 characters, with a space between each, far more than the 127 of a command line. With the link file, the command that makes TATARA.COM is short:

tanren /o:build\tatara.com @tatara.lnk
 

The comments also say what each group of modules is, which a command line cannot.

22.3 Link files and the command line

The words of a link file take the place of the @ word, so a command line can mix them with names and options of its own. TANREN then treats every word the same, whether it was typed or read from the file.

• The order of the modules is the order of the words, as always (section 21.1). SUBONLY.LNK names only sub. tanren main @subonly puts MAIN.TRO first, and tanren @subonly main puts SUB.TRO first:

  A:\>tanren main @subonly 
  ... 
  Wrote MAIN.COM, 0100-0125 (38 bytes), entry 0100. 
  A:\>tanren @subonly main /o:rev.com 
  ... 
  WARNING: REV.COM is entered at 0100, not at 0109. 
  2 modules, 16 records, ends at EOF. 
  Wrote REV.COM, 0100-0125 (38 bytes), entry 0109.
   
  

  REV.COM starts with the code of greet, and TANREN warns about it (section 21.1).

• Options can come before or after the @ word. tanren /p:4000 @prog /o:high.bin starts the code at 4000h and writes HIGH.BIN.

• An option given twice: the last one counts. PROG.LNK has /o:prog.com, so a /O: after @prog replaces it, and one before is replaced by it:

  A:\>tanren @prog /o:other.com 
  ... 
  Wrote OTHER.COM, 0100-0125 (38 bytes), entry 0100. 
  A:\>tanren /o:first.com @prog 
  ... 
  Wrote PROG.COM, 0100-0125 (38 bytes), entry 0100.
   
  

• Only one link file can be named on a command line, and a link file cannot name another.

TANREN looks for the object files that a link file names in the link file’s own directory first. Chapter 23 describes where it looks.

22.4 Messages

Table 22.1 lists the messages about link files. They come before the banner, because TANREN reads the link files before it starts. The messages call a link file a “file list”.

A module named twice, for example on the command line and again in the link file, is found while linking: its public names are defined twice (chapter 27).