Ide/IDE Tools/Command Line Linker

Introduction

The PDC Link Editor is a linker used to combine object (.obj) files, resource (.res) files and library modules (.lib files) into a single target executable file (.exe) or a dynamic-link library (dll).

The PDC Link Editor accepts the following types of input files:

• Object files and libraries in OMF format (32bit only).
• Object files in the Common Object File Format (COFF).
• Libraries in the Microsoft library format.
• Libraries in the archive format.
• Standard Windows resource files.
• Definition files (.DEF).

The number of input files is not limited. The PDC Linker can link mixed object files of OMF and COFF formats (with certain limitations on call rules) producing valid executable files. But it is not possible to mix 32bit and 64bit input files.

The PDC Link Editor can produce the following types of files:

• Windows 32bit or 64bit executable files.
• Windows 32bit or 64bit dynamic-link libraries (DLLs).
• Windows 32bit or 64bit import libraries for created DLLs.
• A linker map (.MAP) file. A map file is a text file that contains information about the generated image file.

Using the Linker

The linker can be used as a standalone executable that receives command line options and returns one of the following return codes on exit:

• 0 – if linking was successfully accomplished;
• 1 – if linking was terminated with errors;
• 2 – if linking was terminated because of some internal fatal linker errors;

You can use the standard errorlevel parameter in the if commands in batch files to process exit codes returned by the command line linker.

Command Line Syntax

The command line syntax is:

Vip6link.exe [options] [files] [@responce_file]

Here Vip6link.exe is the PDC linker executable file.

The simplest method of using the linker is to provide only the name of an object (.obj) file to be used, and accept defaults for all other parameters.

Invoking of the PDC Link Editor without arguments causes displaying of a short help screen.

A Linker command line can contain: linker options, object file names and library names to be linked (in any order), definition (.DEF) file names, and response file names. Any filenames can be surrounded by the double quotes. All defined options are applied to all linked files.

The - character should precede each option to distinguish it from a filename.

Anything you give on the command line not proceeded by the - character is taken as filenames.

If a value should follow an option, no spaces between the option name and the value can be specified.

Options are case sensitive.

PDC Link Editor scans options from left to right; if some options conflict, the linker assumes an option at the most right position in the argument list. If an option is non-actual for the target file, it is ignored.

If a directive specified in a definition (.DEF) file, performs the same functions as a specified command line option, then the linker uses the definition file directive, which overrides the command line option.

Some PDC Link Editor options take numeric arguments. When a number is specified, it is treated as an integer non-negative number. Numbers cannot be prefixed with a sign. The PDC Link Editor uses C language style of integer constant representation (but not including an integer suffix). A decimal number begins with a non-zero digit and consists of a sequence of decimal digit. An octal number consists of the prefix 0 optionally followed by a sequence of the digits from 0 to 7 only. A hexadecimal number consists of the prefix 0x or 0X followed by a sequence of the decimal digits and the letters from A through F (or from a through f) with values from 10 to 15 respectively. For example, 10 is a decimal number, 010 is an octal number with the decimal value 8, 0X10 is a hexadecimal number with the decimal value 16.

If an option (or option value) is followed by the '-' sign, then the option is turned OFF. On the contrary, when an option (or option value) is followed with a '+' then the option is turned ON.

@ResponceFileName indicates usage of a response file ResponceFileName.

Command Line Options

The linker understand the following options:

-TP[E]

The target file should be a Windows 32-bit executable file (PE). This is the default option. TP can be used also. (.EXE is the default extension.)

-TPD

The target file should be a Windows 32-bit dynamic-link library (DLL) file. The default is TPE (generate EXE).

-S{GUI|CUI|NOVIO}[:Major[.Minor]]

Specifies the OS type with which the target module should be compatible:

• GUI

  Uses windowing API (full window application or DLL).

• CUI

  Console application (compatible with windowing API).

• NOVIO

  Console application (INcompatible with windowing API).

• :Major.Minor

  OS system (Windows) major and minor versions. Lets you specify the identifier of the Windows version under which you expect your application will be run.

-O|o[OutFile]

The target module (the main output) file name. The default is out.exe or out.dll.

-L[ImpLibFile]

Create an import library in MS Library (OMF) format (compatible with BC). ImpLibFile specifies the import library name; the default is out.lib.

-l[ImpLibFile]

Create import library in archive (COFF) format (compatible with MSC) - only for Windows 32 executable file or DLL format (PE). ImpLibFile specifies the import library name; the default is out.lib.

-M|m[MapFile]

Generate an link map (.MAP) file with the name MapFile the default name is out.map. A map (.MAP) file is a text file that contains information about the generated image file.

-b[BaseAddrHexValue]

This option sets a base address for the module to BaseAddrHexValue. The default value (for executable files) is 0x400000.

BaseAddrHexValue specifies base address as hexadecimal value. For example: -b500000 means the base address 0x500000.

The operating system first attempts to load a program at its specified or the default base address. If sufficient space is not available, the system relocates the program.

Notice that some OS demands that the base address should be multiple of 64K.

-C

Case insensitive symbols.

-d

Generate the special section (for PDC Debugger).

-E[Symbol]

Set the module entry point to the specified Symbol.

-s[StackSize]

Sets the reserved stack size for the generated module to the specified StackSize number of bytes. Notice that this value cannot be increased while runtime.

-q

Do not write the header to the output (that will be empty when no error occurs).

-F|f[ResponceFileName]

Sets a name of an optional response file to ResponceFileName. The response file is a text file with one or more strings with options, which can be used as command line options for the PDC Link editor. Number of specified response files is unlimited.

-DefToImportLib [:ImportLibFileName]

Force the linker create in import library ImportLibFileName from the one specified definition (.DEF) file. No object files must be specified.

-V[OutFileName]

UNICODE output into the file OutFileName. This option has priority over the –eFileName option.

-e[FileName]

Set error messages output into the file FileName. When it is specified without a FileName then the linker will print error messages into stderr. (The default is stderr.)

-U[Major[.Minor]]

Sets the user specified major and minor module version, which will be generated into the target module. The default is 0.0.

-u[Symbol]

Set Symbol as undefined symbol. (Can be needed to extract a module from a library.) Resolve all undefined symbols to Symbol.

-t

Write the linkage time stamp into the target module header (the default is 0).

-W[I|M|U]

Warnings level. The warning level option determines, which runtime linker information will be reported. The option should be followed by any combination of the I, M, and U characters:

I - Print out undefined idle symbols (default).

M - Print out currently processed file and module names.

U - Print out all resolved undefined symbols.

For example, -WUM forces the linker reporting about all resolved undefined symbols and currently processed files and modules, but do not report about undefined idle symbols.

-64

Generate 64bit target.

Using Response Files

Response file is an optional text file that contains arguments that can be used in the PDC Link Editor command line.

For passing response file to the PDC Link editor the following syntax should be used:

Vip6Link.exe -FResponseFileName

where ResponseFileName is a response file name.

An argument -FResponseFileName causes the PDC Link Editor to scan arguments from the specified response file ResponseFileName. Response file arguments are substituted into the command line argument list instead of the argument with a response file name.

Arguments in the response file can be separated by the following white space characters (one or more):

• new-line,
• space,
• horizontal and vertical tab,
• form feed,
• line feed.

An argument containing white space characters (filenames) should be enclosed in the double quotation-marks; an enclosed argument should be placed onto one line (i.e. it cannot contain the new-line character).

Two non-separated arguments are concatenated into one.

The Response file can contain comment lines. The character # introduces a comment line if it is the first symbol of the line.

The Visual Prolog linker syntax allows using more than one response file specification in any position on the command line. Combinations of response files and command line operation are permissible. The only constraint upon them is that after all substitutions of response files, the result must be a valid command line. The response files that are combined must result in a valid sequence of responses, and cannot be nested.

Example

# Target: executable file for Windows 32, console application 
  -TP -SCUI
# Entry point
  -E_VIPStartUp@0
# Object files
  x1.obj x2.obj x3.obj
# Libraries
  "c:\Program Files (x86)\Visual Prolog Build7400\lib\VIP7Kernel.lib"
  "c:\Program Files (x86)\Visual Prolog Build7400\lib\VIP7Run.lib"
  "c:\Program Files (x86)\Visual Prolog Build7400\lib\VIP7init.lib"
  "c:\Program Files (x86)\Visual Prolog Build7400\lib\Win32.lib"

Invoking the Linker from the IDE

When you create a new Visual Prolog project using the Project Settings, you provide all the necessary project parameters.

The Project Settings generates a call of the Visual Prolog command line linker in the project build script when PDC Linker is chosen in the Linker Name option in the General tab of the Project Settings.

The IDE Make Facility uses these scripts when it generates the command line that is used to call the linker from the IDE to link the project.

The Project Settings can also be used to change the global project settings of an existing project. The Project Settings will then update the build script used to invoke the linker.

You can preview the command line for the linker call in the Project Settings dialog in the Build Script edit control of the Build Options tab.

If a script generated by the Project Settings does not meet all your demands, you can manually insert corrections into the default call of the PDC linker to accommodate options that cannot be set automatically from the Project Settings dialog.

Definition Files

A module-definition (.DEF) file provides additional input for linker operations.

The module-definition file describes the essential characteristics of an application or a library.

Definition File Format

If a symbol referenced in a module-definition file matches any reserved word (regardless of case), then it must be enclosed into quotation marks. Either the single quote or the double quote character may be used.

Apart from this restriction, format of the file is essentially free: aside from their actions in terminating comments, new line characters are treated simply as white space, having no syntactic significance.

Comments may be entered in the definition file by prefixing them with the ';' character. The comment extends until the end of the line on which it appears.

Only one of the directives NAME or LIBRARY can appear in a single definition file. If neither directive appears, NAME is assumed by default and the module is treated as an application.

Definition File Directives

We describe here the most important directives that can be used in definition files:

• DESCRIPTION - One-line description of module.
• EXPORTS - Establishes exported functions.
• IMPORTS - Establishes imported functions.
• LIBRARY - Names dynamic-link library. Does not create application.
• NAME - Assigns name to application. Does not create library.
• STACKSIZE - Establishes local-stack size in bytes.

DESCRIPTION

DESCRIPTION 'text'

This directive inserts the associated text into the application or library being linked. Maximum length of the text is 254 characters.

DESCRIPTION '(c) Copyright 1984-2012 Prolog Development Center A/S '

The example causes the copyright notice to be embedded into the application or library being linked.

EXPORTS

By default, functions within one module are hidden from all other modules at runtime. This directive makes specified functions available to other runtime modules.

EXPORTS
  function_definitions
  ...

The syntax for an export function_definition is:

ExtName [ = IntName ]

ExtName

The name of the function being defined, as it is known outside its own module.

IntName

The name as it appears inside the module. If no IntName is given, it is assumed to be the same as the ExtName.

Each function_definition must be on a separate line. The EXPORTS keyword can be on the same line as the first function_definition or on a preceding line.

EXPORTS
  GetString = StringIn

The example defines a function within the current module as being available to other modules: GetString is defined within the module as StringIn.

See also the #export preprocessor directive in the Exporting and Importing Classes topic in the Language Reference.

IMPORTS

This directive specifies all functions referenced in the current module that actually appear in other modules, by name and module.

IMPORTS
 [ Internal = ] module.funct
 ...

IMPORTS

The IMPORTS directive appears on a line by itself, followed by any number of import definitions.

Internal

Optional internal name.

module

A required module name.

funct

The function identifier, funct in the syntax description may be either the name listed in the EXPORTS definition of the exporting module, or an ordinal value; if it is an ordinal value, then the internal name is required. If the internal name is omitted and funct is a name, it is used as the internal name.

Each import definition consists of an optional internal name, and a required module name and function identifier pair.

IMPORTS
  read.CharInput
  NewString = read.GetString

The example defines two functions to be imported from a module or library named read into the current module. The first of these was listed by the EXPORTS directive of read as CharInput, and the other as GetString. Within this module, CharInput is known by that name, but GetString is referred to as NewString. See also the example for the EXPORTS directive.

See also the #externally preprocessor directive in the Exporting and Importing Classes topic in the Language Reference.

LIBRARY

This directive indicates that the produced target file is a dynamic-link library, and optionally assigns it a name.

LIBRARY [libname]

Only one of the directives NAME or LIBRARY can appear in a single definition file. If neither directive appears, NAME is assumed by default and the module is treated as an application.

Example:

LIBRARY
   mylib

The example defines a dynamic-link library named mylib. By default mylib is an output file name without suffix.

NAME

This directive indicates that the target file is an application, and optionally assigns it a name.

 NAME [appname]

Only one of the directives NAME or LIBRARY can appear in a single definition file. If neither directive appears, NAME is assumed by default and the module is treated as an application.

NAME myapp

The example defines an application named myapp. By default myapp is an output file name without suffix.

STACKSIZE

The STACKSIZE definition file directive reserves the stack size for the generated module to the specified number of bytes.

STACKSIZE nnn

The STACKSIZE directive performs the same functions as the command line option -s, but overrides it.

The following example sets stack size for the generated module to 100000 bytes, no matter what is specified on the command line when a linker is run.

STACKSIZE 100000

The value specified nnn must be an even number integer. By default, nnn is assumed to be decimal, but the C language conventions for hexadecimal and octal values can be also used if desired.