OPTION directive

The OPTION directive is used to specify options to the Watcom Linker. The format of the OPTION directive (short form OP) is as follows:

    OPTION option{,option}

Each option must be one of the following:

• ARTIFICIAL
• [NO]CACHE
• [NO]CASEEXACT
• CVPACK
• DOSSEG
• ELIMINATE
• HEAPSIZE=n
• LINEARRELOCS
• LONGLIVED
• MANGLEDNAMES
• MAP[=map_file]
• MAXERRORS=n
• NAMELEN=n
• NODEFAULTLIBS
• NORELOCS
• OFFSET=n
• OSNAME='string'
• PACKCODE=n
• PACKDATA=n
• PRIVILEGE=n
• QUIET
• REDEFSOK
• RESOURCE[=resource_file | 'string']
• STACK=n
• STATICS
• SYMFILE[=symbol_file]
• UNDEFSOK
• VERBOSE

where

map_file

is a file specification for the name of the map file. If no file extension is specified, a file extension of .map is assumed.

symbol_file

is a file specification for the name of the symbol file. If no file extension is specified, a file extension of .sym is assumed.

resource_file

is a file specification for the name of the resource file. No file extension is assumed.

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
      

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

The following sections describe the Watcom Linker options for this executable format.

ARTIFICIAL option

The ARTIFICIAL option should only be used if you're developing a Watcom C++ application. A Watcom C++ application contains many compiler-generated symbols. By default, the linker doesn't include these symbols in the map file. The ARTIFICIAL option can be used if you wish to include these compiler-generated symbols in the map file.

The format of the ARTIFICIAL option (short form ART) is as follows:

    OPTION ARTIFICIAL

CACHE option

The CACHE and NOCACHE options can be used to control caching of object and library files in memory by the linker. When neither the CACHE nor NOCACHE option is specified, the linker only caches small libraries. Object files and large libraries aren't cached. The CACHE and NOCACHE options can be used to alter this default behaviour. The CACHE option enables the caching of object files and large library files, while the NOCACHE option disables all caching.

The format of the CACHE option (short form CAC) is as follows:

    OPTION CACHE

The format of the NOCACHE option (short form NOCAC) is as follows:

    OPTION NOCACHE

When linking large applications with many object files, caching object files causes extensive use of memory by the linker. On virtual memory systems such as OS/2 and Windows NT, this can cause extensive page file activity when real memory resources have been exhausted. This can degrade the performance of other tasks on your system. For this reason, the OS/2 and Windows NT-hosted versions of the linker do not perform object file caching by default. This doesn't imply that object file caching isn't beneficial. If your system has lots of real memory, or the linker is running as the only task on the machine, object file caching can certainly improve the performance of the linker.

On single-tasking environments such as DOS, the benefits of improved linker performance outweighs the memory demands associated with object file caching. For this reason, object file caching is performed by default on these systems. If the memory requirements of the linker exceed the amount of memory on your system, the NOCACHE option can be specified.

The QNX operating system is a multi-tasking real-time operating system. However, it isn't a virtual memory system. Caching object files can consume large amounts of memory. This may prevent other tasks on the system from running, a problem that may be solved by using the NOCACHE option.

CASEEXACT option

The CASEEXACT option tells the Watcom Linker to respect case when resolving references to global symbols. That is, ``ScanName'' and ``SCANNAME'' represent two different symbols. By default, the Watcom Linker is case-insensitive; ``ScanName'' and ``SCANNAME'' represent the same symbol. The format of the CASEEXACT option (short form C) is as follows:

    OPTION CASEEXACT

If you have specified the CASEEXACT option in the default directive files wlink.lnk or wlsystem.lnk, it's possible to override this option by using the NOCASEEXACT option. The NOCASEEXACT option turns off case-sensitive linking. The format of the NOCASEEXACT option (short form NOCASE) is as follows:

    OPTION NOCASEEXACT

CVPACK option

This option is only meaningful when generating Microsoft Codeview debugging information. This option causes the linker to automatically run the Microsoft Debugging Information Compactor, CVPACK, on the executable that it has created. This is necessary to get the Codeview debugging information into a state where the Microsoft Codeview debugger will accept it. The linker doesn't run CVPACK by default since CVPACK isn't available for the OS/2 or QNX operating systems.

The format of the CVPACK option (short form CVP) is as follows:

    OPTION CVPACK

For more information on generating Codeview debugging information in the executable, see the ``DEBUG directive.''

DOSSEG option

The DOSSEG option tells the Watcom Linker to order segments in a special way. The format of the DOSSEG option (short form D) is as follows:

    OPTION DOSSEG

When the DOSSEG option is specified, segments are ordered in the following way:

1. all segments not belonging to group DGROUP with class CODE
2. all other segments not belonging to group DGROUP
3. all segments belonging to group DGROUP with class BEGDATA
4. all segments belonging to group DGROUP not with class BEGDATA, BSS or STACK
5. all segments belonging to group DGROUP with class BSS
6. all segments belonging to group DGROUP with class STACK

A special segment belonging to class BEGDATA is defined when linking with Watcom runtime libraries. This segment is initialized with the hexadecimal byte pattern 01, and is the first segment in group DGROUP so that storing data at location 0 can be detected.

Segments belonging to class BSS contain uninitialized data. Note that this only includes uninitialized data in segments belonging to group DGROUP. Segments belonging to class STACK are used to define the size of the stack used for your application. Segments belonging to the classes BSS and STACK are last in the segment ordering so that uninitialized data need not take space in the executable file.

When using Watcom runtime libraries, it isn't necessary to specify the DOSSEG option. One of the object files in the Watcom runtime libraries contains a special record that specifies the DOSSEG option.

If no DOSSEG option is specified, segments are ordered in the order they are encountered by the Watcom Linker.

When the DOSSEG option is specified, the Watcom Linker defines two special variables:

_edata

defines the start of the BSS class of segments

_end

defines the end of the BSS class of segments

Your program must not redefine these symbols.

ELIMINATE option

The ELIMINATE option can be used to enable the elimination of dead code. Dead code elimination is a process the linker uses to remove unreferenced segments from the application. The linker only removes segments that contain code; unreferenced data segments aren't removed.

The format of the ELIMINATE option (short form EL) is as follows:

    OPTION ELIMINATE

Linking C/C++ applications

Typically, a module of C/C++ code contains a number of functions. When this module is compiled, all functions are placed in the same code segment. It's unlikely that all the functions in a module are unreferenced, so the ELIMINATE option isn't very useful.

In order to maximize the effect of the ELIMINATE option, the zm compiler option is available to tell the Watcom C/C++ compiler to place each function in its own code segment. This allows the linker to remove unreferenced functions from modules that contain many functions.

Note that if a function is referenced by data, as in a jump table, the linker won't be able to eliminate the code for the function even if the data that references it's unreferenced.

Linking FORTRAN 77 applications

The Watcom FORTRAN 77 compiler always places each function and subroutine in its own code segment, even if they're contained in the same module. Therefore when linking with the ELIMINATE option the linker is able to eliminate code on a function/subroutine basis.

HEAPSIZE option (OS/2)

The HEAPSIZE option specifies the size of the heap required by the application. The format of the HEAPSIZE option (short form H) is as follows:

    OPTION HEAPSIZE=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
    

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

n specifies the size of the heap. The default heap size is 0 bytes. The maximum value of n is 65536 (64K) for 16-bit applications, and 4G for 32-bit applications, which is the maximum size of a physical segment. Actually, for a particular application, the maximum value of n is 64K or 4G less the size of group DGROUP.

LINEARRELOCS option (QNX)

The LINEARRELOCS option instructs the linker to generate offset fixups in addition to the normal segment fixups. The offset fixups allow the system to move pieces of code and data that were loaded at a particular offset within a segment to another offset within the same segment.

The format of the LINEARRELOCS option (short form LI) is as follows:

    OPTION LINEARRELOCS

Use this option only with Neutrino.

LONGLIVED option (QNX)

The LONGLIVED option specifies that the application being linked will reside in memory, or be active, for a long period of time (for example, background tasks). The memory manager, knowing an application is LONGLIVED, allocates memory for the application so as to reduce fragmentation.

The format of the LONGLIVED option (short form LO) is as follows:

    OPTION LONGLIVED

MANGLEDNAMES option

The MANGLEDNAMES option should only be used if you're developing a Watcom C++ application. Due to the nature of C++, the Watcom C++ compiler generates mangled names for symbols. A mangled name for a symbol includes the following:

• symbol name
• scoping information
• typing information

This information is stored in a cryptic form with the symbol. When the linker encounters a mangled name in an object file, it formats the above information and produces this name in the map file.

If you would like the linker to produce the mangled name as it appears in the object file, specify the MANGLEDNAMES option.

The format of the MANGLEDNAMES option (short form MANG) is as follows:

    OPTION MANGLEDNAMES

MAP option

The MAP option controls the generation of a map file. The format of the MAP option (short form M) is as follows:

    OPTION MAP[=map_file]

map_file

is a file specification for the name of the map file. If no file extension is specified, a file extension of .map is assumed.

By default, no map file is generated. Specifying this option causes the Watcom Linker to generate a map file. The map file is simply a memory map of your program. That is, it specifies the relative location of all global symbols in your program. The map file also contains the size of your program.

If no file name is specified, the map file has a default file extension of .map, and the same file name as the executable file. Note that the map file is created in the current directory even if the executable file name specified in the NAME directive contains a path specification.

Alternatively, a file name can be specified. The following directive instructs the Watcom Linker to generate a map file and call it myprog.map, regardless of the name of the executable file:

    option map=myprog

You can also specify a path and/or file extension when using the MAP= form of the MAP option.

MAXERRORS option

The MAXERRORS option can be used to set a limit on the number of error messages generated by the linker. Note that this doesn't include warning messages. When this limit is reached, the linker issues a fatal error and terminate.

The format of the MAXERRORS option (short form MAXE) is as follows:

    OPTION MAXERRORS=n

n

is the maximum number of error messages issued by the linker.

NAMELEN option

The NAMELEN option tells the Watcom Linker that all symbols must be uniquely identified in the number of characters specified or less. If any symbol fails to satisfy this condition, a warning message is issued. The warning message states that a symbol has been defined more than once.

The format of the NAMELEN option (short form NAMEL) is as follows:

    OPTION NAMELEN=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
    

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

Some computer systems, for example, require that all global symbols be uniquely identified in 8 characters. By specifying an appropriate value for the NAMELEN option, you can ease the task of porting your application to other computer systems.

NODEFAULTLIBS option

Special object module records that specify default libraries are placed in object files generated by Watcom compilers. These libraries reflect the memory and floating-point model that a source file was compiled for and are automatically searched by the Watcom Linker when unresolved symbols are detected. These libraries can exist in the current directory, in one of the paths specified in LIBPATH directives, or in one of the paths specified in the LIB environment variable.

Note that all library files that appear in a LIBRARY directive are searched before default libraries. The NODEFAULTLIBS option instructs the Watcom Linker to ignore default libraries. That is, only libraries appearing in a LIBRARY directive are searched.

The format of the NODefaultlibs option (short form NOD) is as follows:

    OPTION NODEFAULTLIBS

NORELOCS option (QNX)

The NORELOCS option specifies that no relocation information is to be written to the executable file. When the NORELOCS option is specified, the executable file can only be run in protected mode and won't run in real mode. In real mode, the relocation information is required; in protected mode, the relocation information isn't required unless your application is running at privilege level 0.

The format of the NORELOCS option (short form NOR) is as follows:

    OPTION NORELOCS

OFFSET option (QNX)

The OFFSET option specifies the offset in the program's segment in which the first byte of code or data is loaded. This option applies to 32-bit QNX applications only. The format of the OFFSET option (short form OFF) is as follows:

    OPTION OFFSET=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
      

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

n specifies the offset (in bytes) at which the program is loaded, and must be a multiple of 4K. The Watcom Linker rounds the value up to a multiple of 4K if it isn't already a multiple of 4K.

It's possible to detect NULL pointer references by linking the program at an offset that's a multiple of 4K (usually an offset of 4K is sufficient). option offset=4k When the program is loaded, the pages skipped by the OFFSET option aren't mapped. Any reference to an unmapped area (such as a NULL pointer) causes a page fault, preventing the NULL reference from corrupting the program.

OSNAME option

The OSNAME option can be used to set the name of the target operating system of the executable file generated by the linker. The format of the OSNAME option (short form OSN) is as follows:

    OPTION OSNAME='string'

where

string

is any sequence of characters.

The information specified by the OSNAME option is displayed in the creating a ? executable message. This is the last line of output produced by the linker, provided the QUIET option isn't specified. Consider the following example:

    option osname='SuperOS'

The last line of output produced by the linker is as follows:

creating a SuperOS executable

PACKCODE option

This option is intended for 16-bit segmented applications. By default, the Watcom Linker automatically groups logical code segments into physical segments. The PACKCODE option is used to specify the size of the physical segment. The format of the PACKCODE option (short form PACKC) is as follows:

    OPTION PACKCODE=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
    

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

n specifies the size of the physical segments into which code segments are packed. The default value of n is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To suppress automatic grouping of code segments, specify a value of 0 for n.

Note the following:

• Only adjacent segments are packed into a physical segment.
• Segments belonging to the same group are packed in a physical segment. Segments belonging to different groups aren't packed into a physical segment.
• Segments with different attributes aren't packed together unless they are explicitly grouped.

PACKDATA option

This option is intended for 16-bit segmented applications. By default, the Watcom Linker automatically groups logical far data segments into physical segments. The PACKDATA option is used to specify the size of the physical segment. The format of the PACKDATA option (short form PACKD) is as follows:

    OPTION PACKDATA=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
    

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

n specifies the size of the physical segments into which far data segments are packed. The default value of n is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To suppress automatic grouping of far data segments, specify a value of 0 for n.

Note the following:

• Only adjacent segments are packed into a physical segment.
• Segments belonging to the same group are packed in a physical segment. Segments belonging to different groups aren't packed into a physical segment.
• Segments with different attributes aren't packed together unless they are explicitly grouped.

PRIVILEGE option (QNX)

The PRIVILEGE option specifies the privilege level (0, 1, 2 or 3) at which the application runs. The format of the PRIVILEGE option (short form PRIV) is as follows:

    OPTION PRIVILEGE=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
    

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

The default privilege level is 0.

QUIET option

The QUIET option tells the Watcom Linker to suppress all informational messages. Only warning, error and fatal messages are issued. By default, the Watcom Linker issues informational messages. The format of the QUIET option (short form Q) is as follows:

    OPTION QUIET

REDEFSOK option

The REDEFSOK option tells the Watcom Linker to ignore redefined symbols, and to generate an executable file anyway. By default, warning messages are displayed, and an executable file is generated if redefined symbols are present.

The format of the REDEFSOK option (short form RED) is as follows:

    OPTION REDEFSOK

The NOREDEFSOK option tells the Watcom Linker to treat redefined symbols as an error, and not to generate an executable file. By default, warning messages are displayed, and an executable file is generated if redefined symbols are present.

The format of the NOREDEFSOK option (short form NORED) is as follows:

    OPTION NOREDEFSOK

RESOURCE option (QNX)

The RESOURCE option specifies the contents of the resource record in QNX executable files. The format of the RESOURCE option (short form RES) is as follows:

    OPTION RESOURCE 'string' | =resource_file

where

resource_file

is a file specification for the name of the resource file. No file extension is assumed.

string

is a sequence of characters that's placed in the resource record.

If a resource file is specified, the contents of the resource file are included in the resource record.

The resource record contains, for example, help information, and is displayed when the following command is executed.

use <executable>

QNX also provides the usemsg utility to manipulate the resource record of an executable file. Its use is recommended. This utility is described in the QNX Utilities Reference manual.

STACK option

The STACK option can be used to increase the size of the stack. The format of the STACK option (short form ST) is as follows:

    OPTION STACK=n

where

n

represents a value. The complete form of n is as follows:

    [0x]d{d}[k|m]
      

d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.

The default stack size varies for both 16-bit and protected-mode 32-bit applications depending on the executable format. You can determine the default stack size by looking at the map file that can be generated when an application is linked (OPTION MAP). During execution of your program, you may get an error message indicating your stack has overflowed. If you encounter such an error, you must link your application again, this time specifying a larger stack size using the STACK option. For example,

    option stack=8192

STATICS option

The STATICS option should only be used if you're developing a Watcom C or C++ application. The Watcom C and C++ compilers produce definitions for static symbols in the object file. By default, these static symbols don't appear in the map file. If you want static symbols to be displayed in the map file, use the STATICS option.

The format of the STATICS option (short form STAT) is as follows:

    OPTION STATICS

SYMFILE option

The SYMFILE option provides a method for specifying an alternate file for debugging information. The format of the SYMFILE option (short form SYMF) is as follows:

    OPTION SYMFILE[=symbol_file]

where

symbol_file

is a file specification for the name of the symbol file. If no file extension is specified, a file extension of .sym is assumed.

By default, no symbol file is generated; debugging information is appended at the end of the executable file. Specifying this option causes the Watcom Linker to generate a symbol file, which contains the debugging information generated by the Watcom Linker when the DEBUG directive is used. The symbol file can then be used by Watcom Debugger, wd. If no debugging information is requested, no symbol file is created, regardless of the presence of the SYMFILE option.

If no file name is specified, the symbol file has a default file extension of .sym and the same path and file name as the executable file. Note that the symbol file is placed in the same directory as the executable file.

Alternatively, a file name can be specified. The following directive instructs the Watcom Linker to generate a symbol file and call it myprog.sym, regardless of the name of the executable file.

    option symf=myprog

You can also specify a path and/or file extension when using the SYMFILE= form of the SYMFILE option.

Note the following:

• This option should be used to debug a DOS COM executable file. A DOS COM executable file must not contain any additional information other than the executable information itself, since DOS uses the size of the file to determine what to load.
• This option should be used when creating a Microsoft Windows executable file. Typically, before an executable file can be executed as a Microsoft Windows application, a resource compiler takes the Windows executable file and a resource file as input and combines them. If the executable file contains debugging information, the resource compiler strips the debugging information from the executable file. Therefore, debugging information must not be part of the executable file created by the Watcom Linker.

UNDEFSOK option

The UNDEFSOK option tells the Watcom Linker to generate an executable file even if undefined symbols are present. By default, no executable file is generated if undefined symbols are present.

The format of the UNDEFSOK option (short form U) is as follows:

    OPTION UNDEFSOK

VERBOSE option

The VERBOSE option controls the amount of information produced by the Watcom Linker in the map file. The format of the VERBOSE option (short form V) is as follows:

    OPTION VERBOSE

If the VERBOSE option is specified, the Watcom Linker lists, for each object file, all segments it defines and their sizes. By default, this information isn't produced in the map file.

The VERBOSE option can't be used in conjunction with the MODTRACE or SYMTRACE directives.

PATH directive

The PATH directive is used to specify the directories that are to be searched for object files appearing in subsequent FILE directives. When the PATH directive is specified, the current directory is no longer searched unless it appears in the PATH directive. The format of the PATH directive (short form P) is as follows:

    PATH path_name{:path_name}

where

path_name

is a path name.

Consider a directive file containing the following linker directives:

    path /math
    file sin
    path /stats
    file mean, variance

It instructs the Watcom Linker to process the following object files:

• /math/sin.o
• /stats/mean.o
• /stats/variance.o

It's also possible to specify a list of paths in a PATH directive. Consider the following example:

    path /math:/stats
    file sin

First, the Watcom Linker attempts to load the file /math/sin.o. If unsuccessful, the Watcom Linker attempts to load the file /stats/sin.o.

It's possible to override the path specified in a PATH directive by preceding the object file name in a FILE directive with an absolute path specification. An absolute path specification is one that begins with the ``/'' character. For example,

    path /math
    file sin
    path /stats
    file mean, /mydir/variance

The above directive file instructs the Watcom Linker to process the following object files:

• /math/sin.o
• /stats/mean.o
• /mydir/variance.o

REFERENCE directive

The REFERENCE directive is used to explicitly reference a symbol that isn't referenced by any object file processed by the linker. If any symbol appearing in a REFERENCE directive isn't resolved by the linker, an error message is issued for that symbol specifying that the symbol is undefined.

The REFERENCE directive can be used to force object files from libraries to be linked with the application. Also note that a symbol appearing in a REFERENCE directive isn't eliminated by dead code elimination. For more information on dead code elimination, see the section ``ELIMINATE option.''

The format of the REFERENCE directive (short form REF) is as follows:

    REFERENCE symbol_name{, symbol_name}

symbol_name

is the symbol for which a reference is made.

Consider the following example:

    reference domino

The symbol domino is searched for. The object module that defines this symbol is linked with the application. Note that the linker also attempts to resolve symbols referenced by this module.

SEGMENT directive

The SEGMENT directive is used to describe the attributes of code and data segments. The format of the SEGMENT directive (short form SEG) is as follows:

    SEGMENT seg_desc{,seg_desc}

where each seg_desc consists of a segment ID,

    'seg_name' | CLASS 'class_name' | TYPE [CODE | DATA]

followed by one or more segment attributes:

    EXECUTEONLY | EXECUTEREAD | READONLY | READWRITE

where

seg_name

is the name of the code or data segment whose attributes are being specified.

class_name

is a class name. The attributes are assigned to all segments belonging to the specified class.

EXECUTEONLY

(short form EXECUTEO) specifies that the segment can only be executed. This attribute should only be specified for code segments. This attribute shouldn't be specified if it's possible for the code segment to contain jump tables, which is the case with the Watcom C, C++ and FORTRAN 77 optimizing compilers.

EXECUTEREAD

(short form EXECUTER) specifies that the segment can only be executed and read. This is the default for code segments. This attribute should only be specified for code segments.

READONLY

(short form READO) specifies that the segment can only be read. This attribute should only be specified for data segments.

READWRITE

(short form READW) specifies that the segment can be read and written. This is the default for data segments. This attribute should only be specified for data segments.

SORT directive

The SORT directive is used to sort the symbols in the ``Memory Map'' section of the map file. By default, symbols are listed on a per module basis in the order the modules were encountered by the linker. That is, a module header is displayed followed by the symbols defined by the module.

The format of the SORT directive (short form SO) is as follows:

    SORT [GLOBAL] [ALPHABETICAL]

If the SORT directive is specified without any options, as in the following example, the module headers are displayed each followed by the list of symbols it defines, sorted by address.

    sort

If only the GLOBAL sort option (short form GL) is specified, as in the following example, the module headers won't be displayed, and all symbols are sorted by address.

    sort global

If only the ALPHABETICAL sort option (short form ALP) is specified, as in the following example, the module headers are displayed, each followed by the list of symbols it defines sorted alphabetically.

    sort alphabetical

If both the GLOBAL and ALPHABETICAL sort options are specified, as in the following example, the module headers won't be displayed, and all symbols are sorted alphabetically.

    sort global alphabetical

If you're linking a Watcom C++ application, mangled names are sorted by using the base name. The base name is the name of the symbol as it appeared in the source file. See the section ``MANGLEDNAMES option'' for more information on mangled names.

SYMTRACE directive

The SYMTRACE directive instructs the Watcom Linker to print a list of all modules that reference the specified symbols. The format of the SYMTRACE directive (short form SYMT) is as follows:

    SYMTRACE  symbol_name{,symbol_name}

where

symbol_name

is the name of a symbol.

The information is displayed in the map file. Consider the following example:

wlink system op map file test lib math symt sin, cos

The Watcom Linker lists, in the map file, all modules that reference the symbols sin and cos.

---

The SYMTRACE directive can't be used in conjunction with the VERBOSE option.

---

SYSTEM directive

There are three forms of the SYSTEM directive (short form SYS):

• a system definition directive
• a system deletion directive
• a system processing directive

System-definition directive

The first form of the SYSTEM directive is called a system definition directive. It allows you to associate a set of linker directives with a specified name called the system name. This set of linker directives is called a system definition block. The format of a system definition directive is as follows:

    SYSTEM BEGIN system_name {directive} END

where

system_name

is a unique system name.

directive

is a linker directive.

A system definition directive can't be specified within another system definition directive.

System-deletion directive

The second form of the SYSTEM directive is called a system deletion directive. It allows you to remove the association of a set of linker directives with a system name. The format of a system deletion directive is as follows:

    SYSTEM DELETE system_name

where

system_name

is a defined system name.

System-processing directive

The third form of the SYSTEM directive is as follows:

    SYSTEM system_name

where

system_name

is a defined system name.

When this form of the SYSTEM directive is encountered, all directives specified in the system definition block identified by system_name are processed.

Example

Let's consider an example that demonstrates the use of the SYSTEM directive. The following linker directives define a system called statistics:

    system begin statistics
        form qnx
        libpath /libs
        library stats, graphics
        option stack=8k
    end

They specify that a statistics application is to be created by using the libraries stats.lib and graphics.lib. These library files are located in the directory /libs. The application requires a stack size of 8K, and a QNX executable is generated.

Suppose the linker directives in the above example are contained in the file stats.lnk. If we wish to create a statistics application, we can issue the following command:

    wlink @stats system statistics file myappl

As demonstrated by the above example, the SYSTEM directive can be used to localize the common attributes that describe a class of applications.

The system deletion directive can be used to redefine a previously defined system. Consider the following example:

    system begin at_dos
        libpath %WATCOM%\lib286
        libpath %WATCOM%\lib286\dos
        format dos ^
    end
    system begin n98_dos
        sys at_dos ^
        libpath %WATCOM%\lib286\dos\n98
    end
    system begin dos
        sys at_dos ^
    end

If you wish to redefine the definition of the dos system, you can specify the following set of directives:

    system delete dos
    system begin dos
        sys n98_dos ^
    end

This effectively redefines a dos system to be equivalent to a n98_dos system (NEC PC-9800 DOS), rather than the previously defined at_dos system (AT-compatible DOS).

Special system names

There are two special system names. When the linker has processed all object files and the executable file format hasn't been determined, and a system definition block hasn't been processed, the directives specified in the 286 or 386 system definition block are processed. The 386 system definition block is processed if a 32-bit object file has been processed. Furthermore, only a restricted set of linker directives is allowed in a 286 and 386 system definition block. They are as follows:

• FORMAT
• LIBFILE
• LIBPATH
• LIBRARY
• NAME
• OPTION
• RUNTIME (for Phar Lap executable files only)
• SEGMENT (for OS/2 and QNX executable files only)

Comment (#) directive

The # directive is used to mark the start of a comment. All text from the # character to the end of the line is considered a comment. The format of the # directive is as follows:

    # comment

where

comment

is any sequence of characters.

The following directive file illustrates the use of comments:

    file main, trigtest

    # Use my own version of "sin" instead of the
    # library version.

    file mysin
    library /math/trig

Include (@) directive

The @ directive instructs the Watcom Linker to process directives from an alternate source. The format of the @ directive is as follows:

    @directive_var

or

    @directive_file

where

directive_var

is the name of an environment variable. The directives specified by the value of directive_var are processed.

directive_file

is a file specification for the name of a linker directive file. A file extension of .lnk is assumed if no file extension is specified.

The environment variable approach to specifying linker directives allows you to specify commonly used directives without having to specify them each time you invoke the Watcom Linker. If the environment variable WLINK is set as in the following example,

    export WLINK=debug all option map, verbose library math
    wlink @WLINK

each time the Watcom Linker is invoked, full debugging information is generated, a verbose map file is created, and the library file math.lib is searched for undefined references.

A linker directive file is useful, for example, when the linker input consists of a large number of object files, and you don't want to type their names on the command line each time you link your program. Note that a linker directive file can also include other linker directive files.

Let the file memos.lnk be a directive file containing the following lines:

    system qnx386
    name memos
    file memos
    file actions
    file read
    file msg
    file prompt
    file memmgr
    library /termio/screen
    library /termio/keyboard

Consider the following example:

wlink @memos

The Watcom Linker is instructed to process the contents of the directive file memos.lnk. The executable image file is called memos.qnx. The following object files are loaded from the current directory:

• memos.o
• actions.o
• read.o
• msg.o
• prompt.o
• memmgr.o

If any unresolved symbol references remain after all object files have been processed, the library files screen.lib and keyboard.lib in the directory /termio are searched (in the order listed).

Note the following:

1. In the above example, we didn't provide the file extension when the directive file was specified. The Watcom Linker assumes a file extension of .lnk if none is present.
2. It isn't necessary to list each object file and library with a separate directive. The following linker directive file is equivalent:

       system qnx386
       name memos
       file memos,actions,read,msg,prompt,memmgr
       library /termio/screen,/termio/keyboard
       
   

   However, if you want to selectively specify what debugging information should be included, the first style of directive file is easier to use. This is illustrated in the following sample directive file:

       system qnx386
       name memos
       debug lines
       file memos
       debug all
       file actions
       debug lines
       file read
       file msg
       file prompt
       file memmgr
       debug
       library /termio/screen
       library /termio/keyboard
       
   

3. Information for a particular directive can span directive files. This is illustrated in the following sample directive file:

       system qnx386
       file memos, actions, read, msg, prompt, memmgr
       file @dbgfiles
       library /termio/screen
       library /termio/keyboard
       
   

   The directive file dbgfiles.lnk contains, for example, those object files that are used for debugging purposes.

Memory requirements

The Watcom Linker uses all available memory when linking an application. It's possible for the size of the image being linked to exceed the amount of memory available in your machine, particularly if the image file is to contain debugging information. For this reason, a temporary disk file is used when all available memory is used by the Watcom Linker.

Normally, the temporary file is created in the current working directory. However, by defining the TMPDIR environment variable to be a directory, you can tell the Watcom Linker where to create the temporary file. This can be particularly useful if you have a RAM disk. Consider the following definition of the TMPDIR environment variable:

export TMPDIR=/tmp

The Watcom Linker creates the temporary file in the directory /tmp.