.mt 5
.mb 6
.pl 66
.ll 64
.po 10
.hm 2
.fm 2
.ce
Description of LINK-68
.sp 
.pp 0
LINK-68 is the new enhanced linker for CP/M-68K.  The major new feature is 
the ability to link overlayed programs. 
.sp 2
1.  Overlay Scheme
.pp
LINK-68 supports a simple tree-structured overlay scheme.  Only one overlay 
from a given level is memory-resident at a time.  An overlay can 
reference a symbol in a direct descendant or in any ancestor.  An  
overlay cannot reference a symbol in a sibling overlay or in an overlay 
more than one level down in the tree.  
.pp
The lowest allowed level is five levels below the root.  The maximum 
number of overlays is 255.
.pp
All global static data is in the root, no matter where it is originally 
defined.
.sp 2
2.  Command Line
.pp
The command line for LINK-68 has almost the same format as for LINK-86, as 
described in sections 7 and 8 of the Programmer's Utilities Guide 
for CP/M-86.  The main differences are in the available options.  The 
format for specifying options and overlay structures is the same.  Parens 
enclose overlay specifications, and square brackets enclose options.
.pp 
Anything after a backslash on a command line is ignored.
.pp
If you just type 'LINK68' without any command line, the linker lists the 
options.  The following is a list of the options for LINK-68.  
.pp
ABSOLUTE
.pp
.in 5
Tells the linker to generate an absolute file 
with no relocation bits.  The default is a relocatable program.
.pp
.ti -5
ALLMODS
.pp
All modules from a library are loaded, whether or not they are referenced.  
The default is to only load referenced library modules.
.pp
.ti -5
BSSBASE
.pp
Sets the base for the uninitialized data segment in discontiguous 
programs.  The default value is 
the first even word after the DATA segment.  This option is not 
allowed when linking overlayed programs.
.pp
.ti -5
COMMAND
.pp
Specifies that the following named file contains 
the rest of the command line.  
The linker ignores the rest of the main command line and does not return 
to it.  Nested command files are not allowed.
.pp
.ti -5
DATABASE
.pp
Specifies the start of the DATA segment in discontiguous programs.  The 
default is the first even word after the TEXT segment.  This option 
is not allowed when linking overlayed programs.
.pp
.ti-5
IGNORE
.pp
Ignore 16-bit address overflow.  This is like the -i option in LO68.
.pp
.ti -5
INCLUDE
.pp
Instructs the linker to load an unreferenced module from a 
library.  The format for this option is:
.sp
.ti 10
filename [INCLUDE [module name]]
.pp
.ti -5
LOCALS
.pp
Tells the linker to put local symbols in the symbol table.  The default is 
no local symbols.  This option only applies from the point in the command 
line that it appears.  The NOLOCALS switch turns this option off.  Use them 
in combination to put local symbols from specific files in the symbol table.
.pp
Local symbols starting with 'L' are always ignored.
.pp
.ti -5
NOLOCALS
.pp
See LOCAL.
.pp
.ti-5
SYMBOLS
.pp
Put the symbol table in the output file.  The default is no symbol table.
.pp
.ti -5
TEMPFILES
.pp
Specifies the drive to use for temporary files.  The default is the 
currently logged-in drive.  This option must preceed any input files on 
the command line.
.pp
.ti -5
TEXTBASE
.pp
Specifies the base for the TEXT segment.  The default is 0.  This option 
is allowed with overlayed programs, but the DATABASE and BSSBASE options 
are not allowed when linking overlayed programs.
.in 0
.sp 
.pp
The following are examples of command lines for LINK-68.  Notice that an 
option name can be abreviated to its shortest unambiguous form.  Addresses 
are always in hex.
.in 5
.sp
.nf
LINK68 [SYM, TEM[D:] FOOBAZ = FOOMAIN, FOOLIB 
.SP
LINK68 [COM[INP.JNK	\\ CLOSING BRACKETS ARE NOT NEEDED 
.sp
LINK68 [ABS, TEX[500]] P.68K = ST.O,P.O[LO],LIB.A[NOL],(V1.O),(V2.O)
.fi
.in 0
.sp 2
3.  Format of an Overlay File
.pp
An overlay file has the same format as a regular a.out-format file.  The 
header "magic" word is always 601AH.  The file can be either absolute or 
relocatable.  The overlay's symbols are in the root file, if the SYMBOLS 
options is used.
.pp
An overlay file can have any type, but the default type is O68.
.pp
To specify that a block of BSS space is to be in the root instead of in the 
overlay's BSS segment, generate an external symbol for the space and give 
the symbol a value equal to the number of bytes required.  The space will 
be allocated on an even boundary in the root's BSS segment.  If more than 
one module specify static storage with the same name, the largest size is 
used for allocation.
.pp
The BSS size for the root file is set to contain the area into which the 
overlays are loaded.  The symbol _end is resolved to the top of the 
overlay area. 
.sp 2
4.  Overlay Manager
.pp
The overlay manager should be transparent to your program, except for the 
time required to read in the overlay.  Write the modules as if you were 
going to load everything in one file.  Make sure to include the files 
containing the overlay handler and loader in the root.