View source for Ide/IDE Tools/Command Line Linker

From wiki.visual-prolog.com
You do not have permission to edit this page, for the following reasons:
The action you have requested is limited to users in the group: emailconfirmed.
You must confirm your email address before editing pages. Please set and validate your email address through your user preferences.
You can view and copy the source of this page.
<noinclude>[[Category:Ide]]</noinclude>
=== Introduction ===

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

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:
*<vp>0</vp> – if linking was successfully accomplished;
*<vp>1</vp> – if linking was terminated with errors; 
*<vp>2</vp> – if linking was terminated because of some internal fatal linker errors;

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

=== Command Line Syntax ===

The command line syntax is:
<vipbnf>Vip6link.exe [options] [files] [@responce_file]</vipbnf>

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 <vp>-</vp> character should precede each option to distinguish it from a filename.

Anything you give on the command line not proceeded by the <vp>-</vp> 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 <vp>0</vp> optionally followed by a sequence of the digits from <vp>0</vp> to <vp>7</vp> only. A hexadecimal number consists of the prefix <vp>0x</vp> or <vp>0X</vp> followed by a sequence of the decimal digits and the letters from <vp>A</vp> through <vp>F</vp> (or from <vp>a</vp> through <vp>f</vp>) 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 '<vp>-</vp>' sign, then the option is turned OFF. On the contrary, when an option (or option value) is followed with a '<vp>+</vp>' then the option is turned ON.

<vpbnf>@<ResponceFileName></vpbnf> indicates usage of a response file <vpbnf><ResponceFileName></vpbnf>.

=== 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). <vpbnf><ImpLibFile></vpbnf> 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). <vpbnf><ImpLibFile></vpbnf> specifies the import library name; the default is '''out.lib'''.

'''-M|m[MapFile]'''
:Generate an link map (.'''MAP''') file with the name <vpbnf><MapFile></vpbnf> 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 <vpbnf><BaseAddrHexValue></vpbnf>. The default value (for executable files) is <vp>0x400000</vp>.
:<vpbnf><BaseAddrHexValue></vpbnf> specifies base address as hexadecimal value. For example: <vp>-b500000</vp> means the base address <vp>0x500000</vp>.
:<br/>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 <vpbnf><Symbol></vpbnf>.

'''-s[StackSize]'''
:Sets the reserved stack size for the generated module to the specified <vpbnf><StackSize></vpbnf> 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 <vpbnf><ResponceFileName></vpbnf>. 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 <vpbnf><ImportLibFileName></vpbnf> from the one specified definition (.'''DEF''') file. No object files must be specified.

'''-V[OutFileName]'''
:UNICODE output into the file <vpbnf><OutFileName></vpbnf>. This option has priority over the '''–eFileName''' option.

'''-e[FileName]'''
:Set error messages output into the file <vpbnf><FileName></vpbnf>. When it is specified without a <vpbnf><FileName></vpbnf> 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 <vp>0.0</vp>.

'''-u[Symbol]'''
:Set <vpbnf><Symbol></vpbnf> as undefined symbol. (Can be needed to extract a module from a library.) Resolve all undefined symbols to <vpbnf><Symbol></vpbnf>.

'''-t'''
:Write the linkage time stamp into the target module header (the default is <vp>0</vp>).

'''-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:

<vipbnf>Vip6Link.exe -FResponseFileName</vipbnf>

where <vpbnf><ResponseFileName></vpbnf> is a response file name.

An argument <vpbnf>-F<ResponseFileName></vpbnf> causes the PDC Link Editor to scan arguments from the specified response file <vpbnf><ResponseFileName></vpbnf>. 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 <vp>#</vp> 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'''
<vip># 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"</vip> 

=== 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 '<vp>;</vp>' 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'''
<vipbnf>DESCRIPTION 'text'</vipbnf>
:This directive inserts the associated text into the application or library being linked. Maximum length of the text is 254 characters.
<vipbnf>DESCRIPTION '(c) Copyright 1984-2012 Prolog Development Center A/S '</vipbnf>
: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.
<vipbnf>EXPORTS
  function_definitions
  ...</vipbnf>

:The syntax for an export <vp>function_definition</vp> is:
<vipbnf><ExtName> [ = <IntName> ]</vipbnf>
:'''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 <vpbnf><IntName></vpbnf> is given, it is assumed to be the same as the <vpbnf><ExtName></vpbnf>.

:Each <vp>function_definition</vp> must be on a separate line. The '''EXPORTS''' keyword can be on the same line as the first <vp>function_definition</vp> or on a preceding line.
<vipbnf>EXPORTS
  <GetString> = <StringIn></vipbnf>

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

:See also the <vp>#export</vp> 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.
<vipbnf>IMPORTS
 [ <Internal> = ] module.funct
 ...</vipbnf>

:'''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, <vp>funct</vp> 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 <vp>funct</vp> 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.
<vipbnf>IMPORTS
  read.<CharInput>
  <NewString> = read.<GetString></vipbnf>

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

:See also the <vp>#externally</vp> 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.
<vipbnf>LIBRARY [libname]</vipbnf>

: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:
<vipbnf>LIBRARY
   mylib</vipbnf>

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

'''NAME'''
:This directive indicates that the target file is an application, and optionally assigns it a name.
<vipbnf> NAME [appname]</vipbnf>

: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.
<vipbnf>NAME myapp</vipbnf>

:The example defines an application named <vp>myapp</vp>. By default <vp>myapp</vp> 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.
<vipbnf>STACKSIZE nnn</vipbnf>

:The '''STACKSIZE''' directive performs the same functions as the command line option <vp>-s</vp>, 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.
<vipbnf>STACKSIZE 100000</vipbnf>

:The value specified <vp>nnn</vp> must be an even number integer. By default, <vp>nnn</vp> is assumed to be decimal, but the C language conventions for hexadecimal and octal values can be also used if desired.
Return to Ide/IDE Tools/Command Line Linker.
Retrieved from "https://wiki.visual-prolog.com/index.php?title=Ide/IDE_Tools/Command_Line_Linker"
View source for Ide/IDE Tools/Command Line Linker

Search

Navigation

external links

collaboration

Personal tools

Views
