tlink.txt

tasm source document descript

/*************************************************************************/
                                 TLINK.TXT
                               TURBO ASSEMBLER

This file contains details on using TLINK with TASM.

--------------------------------------------------------------------
                        TABLE OF CONTENTS
                        - - - - - - - - -
   TLINK basics
      TLINK.CFG
      Response files
   TLINK options
   Module-definition file reference
      CODE statement
      DATA statement
      DESCRIPTION statement
      EXETYPE statement
      EXPORTS statement
      IMPORTS statement
      LIBRARY statement
      NAME statement
      SEGMENTS statement
      STACKSIZE statement
      STUB statement
      Module-definition file defaults

--------------------------------------------------------------------

TLINK and TLINK32 are command-line tools that combine object modules
(.OBJ files) and library modules (.LIB files) to produce executable
files. The IDE uses built-in versions of the linkers. Because the
compiler automatically calls the linker, you don't need to use TLINK
unless you suppress the linking stage of compiling (see the -c
compiler option). Unless otherwise specified, instructions and options
for TLINK also apply to TLINK32.


TLINK basics
============
TLINK uses a configuration file called TLINK.CFG (TLINK32.CFG for
TLINK32), a response file (optional), and command-line options to
link object modules, libraries, and resources into an executable file
(.EXE or .DLL). The IDE linker uses the options specified in the
Project Options dialog box in the Linker section. The syntax for
TLINK is:

TLINK [@respfile][options] startupfile myobjs, exename, [mapfile],
[mylibs] runtimelib [import], [deffile], [resfiles]


  o  'options' are TLINK options that control how TLINK works.
     For example, options specify whether to produce an .EXE
     or a DLL file. TLINK options must be preceded by either
     a slash (/) or a hyphen (-). To turn off a default option,
     place a hyphen after the option (for example, -P-).

  o  'startupfile' is a Borland initialization module for
     executables or DLLs that arranges the order of the various
     segments of the program. The initialization module must appear
     first in the object file list. If it isn't first, the program
     segments might not be placed in memory properly, which could
     cause some frustrating program bugs. Failure to link the correct
     initialization module usually results in a long list of error
     messages telling you that certain identifiers are unresolved,
     or that no stack has been created.

  o  'myobjs' are the .OBJ files you want linked. Specify the path
     if the files aren't in the current directory.

  o  'exename' is the name you want given to the executable file
     (.EXE or .DLL). If you don't specify an executable file name,
     TLINK derives the name of the executable by appending .EXE or
     .DLL to the first object file name listed. Be sure you give an
     explicit name for the executable file name on the TLINK command
     line. Otherwise, your program name will be something like
     C02.EXE--which probably isn't what you wanted.

  o  'mapfile' (optional) is the name you want given to the map
     file. If you don't specify a name, the map file name is
     given the same as exefile (but with the .MAP extension).

  o  'mylibs' (optional) are the library files you want included at
     link time. If these files aren't in the current directory or
     the search path (see the /L option) then you must include their
     paths.

  o  'runtimelib' is the Borland run-time library. If no libraries
     are included, none are linked.

  o  'importlib' is the Windows import library, which provides
     access to the Microsoft Windows API functions.

  o  'deffile' is the module-definition file (.DEF) for a Windows
     executable. If you don't specify a .DEF file, TLINK creates
     an application based on default settings.

  o  'resfiles' are a list of .RES files to bind to the executable.


TLINK assumes or appends these extensions to file names that have
none:

  o  .OBJ for object files

  o  .EXE for executable files

  o  .DLL for dynamic-link libraries

  o  .MAP for map files

  o  .LIB for library files

  o  .DEF for module-definition files

  o  .RES for resource files


TLINK.CFG
---------
TLINK uses a configuration file called TLINK.CFG (or TLINK32.CFG) for
options that you'd normally type at the command-line (note that
TLINK.CFG can only be options, not file names). Configuration files
let you save options you use frequently, so that you don't have to
continually retype them.

TLINK looks for TLINK.CFG in the current directory, then in the
directory from which TLINK was loaded.

The following TLINK.CFG file tells TLINK to look for libraries first
in the directory C:\BC4\LIB and then in C:\WINAPPS\LIB, to include
debug information in the executables it creates, to create a detailed
segment map, and to produce a Windows executable (.EXE not .DLL).

	TLINK				TLINK32
	-----				-------
	/Lc:\bc4\lib;c:\winapps\lib	/Lc:\bc4\lib;c:\winapps\lib
	/v /s				/v /s
	/Twe				/Tpe


Response files
--------------
Response files are ASCII files of options and file names for TLINK.EXE
(and TLINK32.EXE) that you would normally type at the command line.
Response files let you have a longer command line than most operating
systems allow. Response files can include the same information as
configuration files (command-line options), but they can also contain
file names.

Unlike the command line, a response file can be several lines long. To
use more than one line in your response file, end each line with a
plus character (+). Note that if a line ends with an option that uses
the plus to turn it on (such as /v+), the + isn't treated as a line
continuation character (to continue the line, use /v++).

If you separate command-line components (such as .OBJ files from .LIB
files) by lines in a response file, you must leave out the comma used
to separate them on the command line. For example:

	/c c0ws+
	   myprog,myexe
	   mymap
	   mylib cws

leaves out the commas you'd have to type if you put the information on
the command line:

	TLINK /c c0ws myprog, myexe, mymap, mylib cws

To use response files:

 1) Type the command-line options and file names into an ASCII text
    file and save the file.

 2) Type TLINK @[path]RESFILE.RSP, where RESFILE.RSP is the name
    of your response file.

You can specify more than one response file as follows:

	TLINK /c @listobjs, myexe, mymap, @listlibs

If you use a response file in addition to command-line options, the
command-line options will override any options in the response file.
For example, if you include -v in a response file, but you use -v- at
the command-line, TLINK uses the command-line option -v-.


TLINK options
=============
Unless otherwise specified, options work with both TLINK and TLINK32.
Options are case-sensitive and must be preceded by either a slash (/)
or a hyphen (-). To turn off a default option, place a hyphen after
the option at the command-line (for example, -P- or /P-). You can
place options anywhere in the command line. You don't need spaces
after options (/m/f/c is the same as /m  /f  /c), but you must
separate options and files with a space.

The following table lists the TLINK options. A more detailed
explanation of options follows the table.

Option	For		Description
------	---		-----------
/3	16-bit		Accepts and links 32-bit code produced by TASM
			or a compatible assembler.

/ax	32-bit		Specifies application type, where
			/aa targets Windows applications
			/ap targets console applications.

/A:dd	16/32-bit	Specifies page alignment within .EXE file.

/B:xxx	32-bit	Specifies image base address (in hexadecimal).

/c	16/32-bit	Treats case as significant in symbols.

/C	16-bit		Treats case as significant in EXPORTS and
			IMPORTS section of module-definition file.

/d	16-bit		Warns you if there are duplicate symbols in
			libraries.

/E	16-bit		Enables processing of extended dictionaries in
			libraries.

/Enn	32-bit		Specifies maximum errors before termination.

/e	16-bit		Ignores extended dictionaries in libraries.
			This is the opposite of the /E option.

/f	16-bit		Inhibits optimization of far calls to near
			data.

/Gn	16-bit		Discard nonresident name table.

/Gr	16-bit		Transfer Resident names to nonresident names
			table.

/Gm	16/32-bit	Put Mangled names in map file.

/i	16-bit		Initializes all segments.

/l	16-bit		Includes source line numbers (lowercase L).

/L	16/32-bit	Specifies library search paths.

/m	16/32-bit	Creates map file with publics.

/n	16-bit		Don't use default libraries.

/o	16-bit		Overlays modules or libraries.

/P	16-bit		Packs code segments.

/R	16-bit		Sends options to RLINK.EXE. Possible
			options are /Re, /Rk, /Rl, /m, /Rp, and /Rv.

/Rexxx	32-bit		Renames the executable to xxx.

/S:xxx	32-bit		Specifies stack size (in hexadecimal).

/s	16-bit		Creates detailed map of segments.

/t	16-bit		Creates a tiny-model DOS .COM file.

/Tdx	16-bit		Specifies application target, where
			/Tde means build a DOS .EXE file.

/Tpx	32-bit		Specifies application target, where
			/Tpe means build a 32-bit .EXE file.
			/Tpd means build a 32-bit DLL.

/Twx	16-bit		Specifies Windows 3.x target application,
			where
			/Twe builds a Windows .EXE file.
			/Twd builds a Windows DLL.

/v	16/32-bit	Includes full symbolic debug information.

/wxxx	32-bit		Enable or disable warnings.

/x	16/32-bit	Doesn't create a map file.

/ye	16-bit		Uses expanded memory for swapping.

/yx	16-bit		Configures TLINK's use of extended memory
			swapping.


/3 (32-bit code) lets you link 32-bit DOS object modules produced by
TASM or a compatible assembler. This option increases the memory
requirements for TLINK and slows down linking.

/a (application type) lets you specify the type of EXE image:

  o  /aa targets Windows applications.

  o  /ap targets console applications that can be run in a window.

/A:dd (align pages) specifies page alignment for code and data within
the executable file where dd must be a decimal power of 2. For
example, if you specify an alignment value of /A:12, the sections in
the image are stored on 4096-byte boundaries. The operating system