Ide/IDE Tools/Command Line Compiler

From wiki.visual-prolog.com

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).