Ide/Command Line Tools

IDE
Environment Overview Projects Project Settings Project Tree Collaboration Options Creating new Project Items Text Editor Resource Editor Code Experts Debugger Command Line Tools Make Facility External Tools Messages and Errors Window TODO Window IDE Dialogs $(ProDir) Subdirectories Key Bindings

Command Line Compiler

Visual Prolog compiler is used to compile Visual Prolog source files to produce intermediate Visual Prolog files. These are:

• COFF format object files (.OBJ),
• debugger information files,
• browse information files
• etc.

Using the Compiler

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

• 0 – if compilation was successfully accomplished;
• 1 – if compilation was terminated with errors;
• 2 – if compilation was terminated due to some internal fatal compiler errors or command line options;

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

Command Line Syntax

The command line syntax is:

VIPCompiler [options] [files] [@responce_file]

A compiler command line can contain: compiler options, source file names (without wild chars) to be compiled (in any order), and response file names.

[options]

All defined options are applied to all source files.

Each option should be preceded by '/' or '-' characters to distinguish them from filenames.

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

Option names and value names can be truncated, but they must still be unambiguous.

If an option (or option value) is followed with a '-', 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.

When a number is specified, it is treated as an integer not negative number. Numbers cannot be prefixed with a sign. Numbers can be determined either as decimal (the sequence of decimal digits) or as hexadecimal (the sequence of hexadecimal digits that is prefixed with 0x).

[files]

Anything you give on the command line not preceded by '/' or '-' characters is taken as filenames.

Any filenames can be surrounded by the double quotes.

Filenames without extensions are assumed to name Prolog source files.

@responce_file

This option causes the compiler to read the specified responce_file file.

The file strings that are starting with the '#' symbol (exclusive of the leading spaces and tabulations) are ignored (they are considered as the comments). The compiler appends strings from the responce_file file; all new line symbols are replaced with spaces. The result is substituted into the command line string instead of the option @ itself.

After this substitution, the option parsing continues from the interrupted point. Any error during the processing the response file causes the terminal error of options parsing.

Nested response files are not allowed.

There is no restriction for the total number of the response files.

Command Line Options

The compiler understands the following options:

/Help

This option causes the compiler to print to the screen a short help about compiler options.

This help is printed also if no options or files are specified to the compiler.

/VERsion

When this option is switched ON, it causes output of extra information about the compiler version.

It is ignored in the Personal Edition version, where it is always ON.

/Goal:{PROC|DETerm}

This option determines a determinism mode of the program Goal section. It can be one of the following:

• PROC

  The Goal is assumed to be a procedure (this is the default).

• DETerm

  The Goal is assumed to be determ (deterministic).

/Check: {ALL|ON|RANge|NOne|OFF|INTegraloverflow|VARiable|STAck|FACts}
/NOCheck

This option determines, which types of checking will be generated by the compiler into object files; these checking will be executed during execution of a target program. It has the following keys that can be separated by commas:

• ALL | ON

  Generates the maximum level of checking. The default is /Check:all.

• RANge

  Generates checking that values of numeric domains are inside the boundaries (range) specified to domains.

• INTegraloverflow

  Generates checking for integral overflow during calculations. When this option is on, the compiler will generate code at each integral arithmetic operation to check if the operation results in integer overflow.

• NOne | OFF

  Generates the minimal level of checks during a program execution. The same as /NOCheck option.

• VARiable

  Assigns a special value to all predicate variables for additional checking of proper variable initialization.

• STAck

  Generates checks of the stack state after return from a predicate (determ or procedure).

  Catches errors in the case of incorrect usage of a calling conversion or others situations when the stack might be destroyed.

  Such cases appear mostly when predicates implemented not in Visual Prolog are used.

• FACts

  Generates checks of non-initialized facts and duplicated assert for determ facts.

Option Examples:

/Check:none is the same as /NOCheck or /Check:off

/Check:all is the same as /Check or nothing (since it is the default).

/MAXErrors:<N>

This option defines the maximum number of the compiler errors, which can be generated during the compilation of a separate compilation unit before the compiler will produce the error "Too many errors", which abnormally terminates the compilation with abnormal exit code.

The value "0" – suppresses the check for the number of generated errors.

The default value is -20.

/MAXWarnings:<N>

This option defines the maximum number of the compiler warnings, which can be generated during the compilation of a separate compilation unit before the compiler will produce the error "Too many warnings", which abnormally terminates the compilation with abnormal exit code. The value  0 – suppresses the check for the number of generated warnings.

The default value is 100.

If the option /Warning:AsError is defined, the compiler generates errors instead of warnings, and option /MAXWarnings is ignored.

/Include:[[<dir>;]*<dir>]

Specifies the directories the compiler will concatenate to the existing list of include directories.

The default include directory is the current directory.

This option determines directories in which the compiler will search include files, which are mentioned in the preprocessor #include directives specified in the compiler source files.

You can define more than one directory in one /Include option; such directories should be separated with the semicolon ';'. If more than one /Include option are used then the specified directories are appended to the list of include directories. The directories can be repeated.

The compiler tries to find a specified include source file in the following way:

• If the filename contains an absolute path, then this file should be included.
• Otherwise, the compiler searches for the specified include filename among the paths that had been defined by the /Include command line option. These paths are handled consequently as they are specified in the option. In the IDE, you can set these paths in the Include Directories in the Directories tab of the Project Settings dialog.

/Warnings: {ASError|ASWarning|NOthing|warning_name [ |-|*]}

This option determines, which warnings the compiler should produce.

Option /Warning can have the following values:

• ASWarning

  All warnings are treated as warnings (this is the default).

• ASError

  All warnings are treated warnings as errors.

• NOthing

  All warnings are suppressed.

• { warning_name | warning_number } [ warning_state ]

  where warning_state can be one of the following:

  + Treated as a warning (this is the default).

  - Suppressed (this warning will not be checked).

  * This warning will be treated as an error.

The first three values ASError, ASWarning, NOthing affect all warnings.

The syntax { warning_name | warning_number } [ warning_state ] can be used to set the compiler reaction for a separate warning. If warning_state is omitted, then it is treated by default as warning (i.e. ’+’ is assumed). Several option values separated with commas can be specified in one option.

The warning_name and warning_numbercan be the following:

• INVALDig | 212

  Value of digits (in the real domain declaration) is too large and is set to the maximal supported value. See also the error message c212.

• SCOPERef | 213

  A name in supports/predicates from/open/inherits equals to a scope name. See also the error message c213.

• ALREADYSup | 260

  Interface is already supported in a class declaration. See also the error message c260.

• SINGLEFact | 288

  Single fact does not have arguments. See also the error message c288.

• PREDRES | 259

  Predicate resolution is overridden. See also the error message c259.

• UNUSEDvar | 507

  Unused variable. See also the error message c507.

• UNUSEDEnt | 654 | 661 | 662

  Unused entity. See also the error messages c654, c661, c662.

• SCOPE | 214

  Duplicated name in supports/predicates from/open/inherits. See also the error message c214.

• RESOLve | 228

  Duplicated resolution in predicates from/resolve. See also the error message c228.

• PROCedure | 631

  Declared predicate mode does not correspond to the evaluated one. See also the error message c631.

• CONVersion |656

  Superfluous conversion. See also the error message c656.

• MORETHANonce | 313

  Variable is used more than one time. See also the error message c313.

• INITObject | 657

  Usage of not fully initialized object can lead to errors (it is turned off by the default). See also the error message c657.

Option Examples:

/W:aserror
/W:no,invaldig*, +scope
/W:-notgr
/Warn:631-

/Optimize:{ALL|None|FINal}

This option handles optimizations. Possible option values are:

• ALL

  Full optimization.

• None

  No optimizations.

• FINal

  Optimization of the last calls.

/Listing: ALL,NOne,MIN,Include,UNICode,STATistics,MEssage,Requires
/NOListing

This option determines, which information will be placed into a listing file. Errors are always printed into the listing file.

Whether warnings will be placed into the listing file or not is controlled by the /WARning option.

More than one value separated with commas can be used in one option. Possible option values are:

• ALL

  Maximal possible output.

• NOne

  No output at all.

• MIN

  The minimal possible output (nothing will be placed except for the mandatory). This is the default.

• Include

  Indications of #include directives.

• UNICode

  UNICODE output (ANSI by the default).

• STATistics

  Generates statistics information.

• MEssage

  Places indication of the #message directives.

• Requires

  Places indication of the #requires and #orrequires directives.

Examples:

/L:all
/L:min or /L
/L:all,message-
/NOL or /L:NO

/DEBug: {NONE|LINENO|FULL}
/NODEBug

The generate debug information option determines how detailed debugging information should be.

Possible option values are:

• NONE

  The compiler should not put the line number and the debugging information into the target file.

• LINENO

  The compiler should generate and put the line number information into the target file. This can be used to follow the execution debuggers.

• FULL

  The compiler should generate and put the line number and the debugging information into the target file. This works like LINENO and additionally generates information for the PDC Debugger. This is the default.

/OBjectdir: <dir>

In this option, you can specify a target object directory name.

/DEBUGDir: <dir>

In this option, you can specify a target directory for debugging information.

/PRO2C

When this option is specified, the compiler will generate C++ header file for each compiled compilation unit.

For instance, if you compile a package Test.pack, then the generated header file will have the name Test.pack.hpp.

Please notice, that this is an experimental feature. We very careful using generated .hpp files.

/PROFILE: {OFF | MIN | ON}

When this option is specified for a compiled module, you can use the profileCount class predicates from the profile package for this module.

/READOnlyterm

It should be always specified for the compiler, when it compiles modules of DLL targets, and it always should NOT be specified for the compiler, when it compiles modules of executable targets.

When this option is specified for a compiled module, then, as soon as a constant from this module becomes visible from any other module, this constant is copied from the read-only memory of the module (where it is ordinary stored) onto the writable memory of the other module, which calls the first module.

This copying of constants (defined in a DLL) from the DLL read-only memory into the memory of a module, which loads the DLL, should be done to avoid the following possible problem. An executable can load a DLL and an executable clause can receive a constant term from the DLL. Notice that without using of the /READOnlyterm option for the DLL modules, the constant will not be copied from the DLL read-only memory (where it is normally stored) into memory of the executable module, which calls this DLL (for the reason of performance). The executable only creates a pointer to the DLL memory block, which stories the referenced constant term. Now the executable can unload the DLL and then try to use the referenced constant term. Really the executable will try to access the DLL memory block referenced with the created pointer to the constant term, but now the unloaded DLL memory is UNACCESSIBLE to the executable and such attempt will probably lead to exception.

Therefore, when the compiler compiles modules, which will be used to build DLLs, the /ReadOnlyTerm option should be used. But, when the compiler compiles modules, which will NOT be used to build DLLs, then the /ReadOnlyTerm option should NOT be used (to increase the performance).

/WEAKTypecheck

When this option is specified, the compiler performs weaker type checks. It is turned off by the default. It can be used for the compatibility with the previous compiler versions. If new type errors appear for the project which was complied successfully before, then either these type errors should be corrected, or the option should be turned on.

/MACHine: {x86 | x64}

This option specifies the target platform (x86 - 32bit Windows, x64 - 64bit Windows).

Command Line Linker

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.