Chip 2002 May/Chip_2002-05_cd1.bin/chplus/cpp/3/Tools.exe/tlink32.txt

Text File | 1998-02-09 | 16KB | 347 lines

TLINK32 Help

TLink32 is a command-line tool that combines object modules (.OBJ files),
library modules (.LIB files), and resources to produce executable files (.EXE and .DLL files).
Because the compiler automatically calls a linker, you don't need to explicitly use a linker unless
you suppress the linking stage of compiling (see the -c compiler option).
TLINK32 and ILINK32 are invoked from the command line to link a configuration file called
TLINK32.CFG (ILINK32 uses ILINK32.CFG), an optional response file, and command-line
options to link object modules, libraries, and resources into an executable file.

Both TLINK32 and ILINK32 link 32-bit Windows code and use the 32-bit resource linker,
RLINK32.DLL.

The linker syntax controls how the linkers work. Linker command-line options are
case-sensitive. Unless specified, instructions and options for TLINK32 also apply to ILINK32.
The linkers can also use a configuration file called TLINK32.CFG for options that you'd
normally type at the command-line.

Syntax

TLINK32 | ILINK32 [@respfile][options] startup myobjs, [exe], [mapfile], [libraries], [deffile],
[resfile]

[@respfile]    A response file is an ASCII file that lists linker options and file names that you
would normally type at the command line. By placing options and files names in a response file,
you can save the amount of keystrokes you need to type to link your application.

[options] Linker options that control how the linker works. For example, options specify
whether to produce an .EXE or a DLL file. Linker options must be preceded by either a slash (/)
or a hyphen (-).

startup   A Borland initialization module for executables or DLLs that arranges the order of the
various segments of the program. Failure to link in 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.

myobjs    The .OBJ files you want linked. Specify the path if the files aren't in the current
directory. (The linker appends an .OBJ extensions if no extension is present.)

[exe]     The name you want given to the executable file (.COM, .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. (The linker assumes or appends an .EXE extensions
for executable files if no extension is present. It also assumes or appends a .DLL extension for
dynamic link libraries if no extension is present.)

[mapfile] 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). (The linker appends a
.MAP extensions if no extension is present.)

[libraries]    The library files you want included at link time. Do not use commas to separate
the libraries listed. If a file is not in the current directory or the search path (see the /L option)
then you must include the path in the link statement. (The linker appends a .LIB extension if no
extension is present.)

The order in which you list the libraries is very important; be sure to use the order defined in this
list:
      Code Guard libraries (if needed)
      List any of your own user libraries, noting that if a function is defined more than once,
the linker uses the first definition encountered
      If you're creating a DOS overlay, link the DOS overlay module OVERLAY.LIB
      DPMI libraries (DOS DPMI applications only)
      IMPORT.LIB (if you're creating an executable that uses the Windows API)

 Math libraries (if needed)
      Runtime libraries associated with your memory model and platform
[deffile] The module definition file for a Windows executable. If you don't specify a
module definition (.DEF) file and you have used the /Twe or /Twd option, the linker creates an
application based on default settings. (The linker appends a .DEF extension if no extension is
present.)
[resfile] A list of .RES files (compiled resource files) to bind to the executable. (The linker
appends an .RES extension if no extension is present.)

TLINK32 uses a configuration file called TLINK32.CFG for options that you would normally
type at the command line (note that configuration files can contain only options, not file names).
Configuration files let you save options you use frequently, so you do not have to continually
retype them.
TLINK32 looks for TLINK32.CFG in the current directory, then in the directory from which it
was loaded.
The following TLINK32.CFG file tells TLINK32 to look for libraries first in the ..\LIB directory
of your Borland compiler, 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).

;Sample TLINK32.CFG file

/Lc:\BORLANDC\LIB;c:\WINAPPS\LIB
/v /s

/Tpe

Note: If you specify command-line options in addition to those recorded in a configuration file,
the command-line options override any conflicting configuration options.

You can use response files with the command-line linkers to specify linker options.
Response files are ASCII files that list linker options and file names that you would normally
type at the command line. Response files allow you longer command lines than most operating
systems support, plus you don't have to continually type the same information. Response files
can include the same information as configuration files, but they also support the inclusion of file
names.
Unlike the command line, a response file can be several lines long. To specify an added line, end
a line with a plus character (+) and continue the command on the next line. Note that if a line
ends with an option that uses the plus to turn it on (such as /v+), the + is not 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:

TLINK32 /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.
Response files shipped with Ebony have an .RSP extension.
2.   Type TLINK32 @[path]RESFILE.RSP where RESFILE.RSP is the name of your
response file.

You can specify more than one response file as follows:

tlink32 /c @listobjs.rsp,myexe,mymap,@listlibs.rsp

Note: You can add comments to response files using semicolons; the linker ignores any text on a
line that follows a semicolon.

You can pass options and files to TLINK through the command-line compiler (BCC32.EXE) by
typing file names on the command line with explicit .OBJ and .LIB extensions. For example,

BCC32 mainfile.obj sub1.obj mylib.lib

links MAINFILE.OBJ, SUB1.OBJ, and MYLIB.LIB to produce the executable
MAINFILE.EXE.
Note: By default, BCC32 starts TLINK32 (or ILINK) with the files C0W32.OBJ, CW32.LIB,
and IMPORT32.LIB (initialization module, run-time library, and Windows import library). In
addition, both compilers always pass the linkers the /c (case-sensitive link) option.


TLINK32 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

TLINK32 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
------    ---       -----------

/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
seeks pages for loading based on this alignment value. The default is
/A:9, which means sections are aligned on 512-byte boundaries within
the executable file.

/B:xxxxxx (base address) specifies an image base address for an
application. If this option is used, internal fixups are removed from
the image, and the requested load address of the first object is set
to the hexadecimal number given with the option. All successive
objects are aligned on 64K linear address boundaries. This option
makes applications smaller on disk, and improves both load-time and
run-time performance since the operating system no longer has to apply
internal fixups. Because NT loads all .EXE images at 64K, you're
advised to link all .EXEs with /B:0x10000.

/c (case sensitivity) makes the case significant in public and
external symbols.

/Enn (maximum errors) specifies the maximum number of errors the
linker reports before terminating. /E0 (the default) reports an
infinite number of errors (that is, as many as possible).

/Gx (Goodies) are options where x can be
     n = Discard nonresident name table. (16-bit only)
     r = Transfer resident names to nonresident table. (16-bit only)
     m = (TLINK32) Put mangled names in map file; this can help you
         identify how names are mangled.

/i (uninitialized trailing segments) outputs uninitialized trailing
segments into the executable file even if the segments don't contain
data records.

/L (library search paths) lets you list directories for TLINK to
search if you don't type an explicit path for a library or the C or
C++ initialization module. TLINK searches the current directory first
(where you typed TLINK). For example:

     TLINK /Lc:\BC4\lib;c:\mylibs splash logo,,,utils .\logolib

first searches the current directory for UTILS.LIB, then searches
C:\BC4\LIB, then C:\MYLIBS. Because @WORD(LOGOLIB) explicitly names
the current directory, TLINK doesn't search the libraries specified
with the /L option to find LOGOLIB.LIB.

/M (map mangled) maps with mangled public names.

/n (ignore default libraries) ignores default libraries specified by
some compilers. Use this option when linking modules that are written
in another language.

/o (overlays) overlays code in all the modules or libraries that
follow the option on the command line (this option works for DOS
applications only). Use /o- on the command line to turn off overlays.
If you specify a class name after this option, all the segments in
that class are overlaid (you can do this for multiple classes). If you
don't specify any name after this option, all segments of classes
ending with CODE are overlaid. This option uses the default overlay
interrupt number of 3FH. To specify a different interrupt number, use
/o#xx, where xx is a two-digit hexadecimal number.

/P (pack code segments) combines as many code segments as possible in
one physical segment up to (and never greater than) the code-segment
packing limit. TLINK starts a new segment if it needs to. The default
code-segment packing limit is 8,192 bytes (8K). To change it, use /P=n
where n specifies the number of bytes between 1 and 65,536. You would
probably want the limit to be a multiple of 4K under 386 enhanced mode
because of the paging granularity of the system.

Although the optimum segment size in 386 enhanced mode is 4K, the
default code-segment packing size is 8K because typical code segments
are from 4K to 8K and 8K might pack more efficiently.

Because each maintained segment has some system overhead, code-segment
packing typically increases performance. /P- turns off code-segment
packing (useful if you've turned it on in the configuration file and
want to disable it for a particular link).

/s (detailed segment map) creates a map file with the same features as
the /m option, but adds a detailed segment map. If you don't specify
map file options (/m, /s, or /x), then the option Map File|Segments is
used. For each segment in each module, this map file includes the
address, length in bytes, class, segment name, group, module, and ACBP
information. If the same segment appears in more than one module, each
module appears as a separate line. Except for the ACBP field, the
information in the detailed segment map is self-explanatory.

The ACBP field encodes the A (alignment), C (combination), and B (big)
attributes into a set of four bit fields, as defined by Intel. TLINK
uses only three of the fields, the A, C, and B fields. The ACBP value
in the map is printed in hexadecimal. The following values of the
fields must be OR'ed together to arrive at the ACBP value printed.

Field                    Value     Description
-----                    -----     -----------
The A field (alignment)       00   An absolute segment.
                    20   A byte-aligned segment.
                    40   A word-aligned segment.
                    60   A paragraph-aligned segment.
                    80   A page-aligned segment.
                    A0   An unnamed absolute portion of
                         storage.

The B field (big)        00   Segment less than 64K.
                    02   Segment exactly 64K.

The C field (combination)     00   Cannot be combined.
                    08   A public combining segment.

With the /s option, public symbols with no references are flagged
"idle." An idle symbol is a publicly-defined symbol in a module that
wasn't referenced by an EXTDEF record by any other module included in
the link. For example, this fragment from the public symbol section of
a map file indicates that symbols Symbol1 and Symbol3 aren't
referenced by the image being linked:

     0002:00000874  Idle Symbol1
     0002:00000CE4       Symbol2
     0002:000000E7  Idle Symbol3

/S:xxxxxx (stack size) sets the application stack size in hexadecimal
where xxxxxx is a hexadecimal string. Specifying the stack size with
/S overrides any stack size setting in a module-definition file.

/Tpx (protected target) produces a protected mode .EXE (/Tpe) or .DLL
file (/Tpd).

/v (debugging information) includes debugging information in the
executable file. If this option is found anywhere on the command line,
debugging information is included in the executable file for all
object modules that contain debugging information. You can use the /v+
and /v- options to selectively enable or disable debugging information
on a module-by-module basis (but not on the same command line as /v).
For example, the command

     TLINK32 mod1 /v+ mod2 mod3 /v- mod4

includes debugging information for modules mod2 and mod3, but not for
mod1 and mod4.

/wxxx (warning control) turns on (/wxxx) or off (/w-xxx) TLINK
warnings, where xxx can be one of the following (defaults mean TLINK
will send the warning without you specifically turning it on):

Option         Description
------         -----------
bdl       Using based linking in DLLs (might cause the DLL to
          malfunction)

def       No .DEF file; using defaults

dpl       Warn duplicate symbol in .LIB

dup       Duplicate symbol (warning for .OBJs)

ent       No entry point

imt       Import doesn't match previous definition

srf       Self-relative fixup overflowed


/x (no map file) tells TLINK to not generate a map file. TLINK usually
creates map files that list segments in the program, the program start
address, and any TLINK warning or error messages (the Map
File|Segments option, which has no command-line option, is on by
default).