[ Predicate Database and Compiler | Reference Manual | Alphabetic Index ]

compile(++Source, ++Options)

Compile specified file, or list of files, with given options

Source: Source file name (atom or string) or structure stream(Stream)
Options: List of compiler options (name:value pairs)

Description

Compiles the specified ECLiPSE source file or list of source files, with the given options. See below for a detailed description of the options.

Source Location

The atom or string File must be instantiated to a legitimate specification for an existing file except for the suffix. The predicate tries to add to it the source suffixes from the list specified in the global flag prolog_suffix, and look for an existing and readable file. As soon as a file is found which exists, it is taken as the input file name. The default source suffixes are empty suffix, .ecl and .pl.

If File is of the form library(Name), the predicates looks for the file in the directories from the library_path flag.

If File is the special atom 'user', the source will be taken from the current 'input' stream, i.e. will usually generate a prompt at which clauses can be typed in. In this case, input must be terminated either by typing CTRL-D (on Unix), CTRL-Z + RETURN (on Windows), or with the single atom end_of_file, followed by a fullstop/period.

If File is the special form stream(Stream), then the source is taken from the given stream (which must be already opened). The stream content is compiled until the end of stream, but the stream is not closed.

When File is not in the current directory, ECLiPSe first changes the current directory to that of the file. Consequently, recursive compile/1 calls inside compiled files can use relative pathnames. This makes it possible to compile the top program files from any directory and still use only local file names inside. At the end of the compilation, the current directory is changed back to the initial one. This has the side effect that all calls to cd/1 in queries in the compiled file are ignored.

Option Syntax

Options is a possibly empty list of OptionName:OptionValue pairs.

Code Generation Options

debug:: This option (off/on) determines whether the resulting code contains debugging information. If off, subgoals of the compiled predicates will not be visible to the debugger, the code will be significantly smaller, and slightly faster. The default value is taken from the global flag debug_compile. The setting can be changed via a pragma (debug/nodebug) in the code.
expand_goals:: This option (off/on, default taken from global flag goal_expansion) determines whether inlining (a.k.a. goals macros) is performed. The default value is taken from the global flag goal_expansion. The setting can be changed via a pragma (expand/noexpand) in the code. Should only be switched off if a problem with inlining is suspected, or to get a debugger trace that is closer to the source code.
opt_level:: Currently the integer 0 or 1, with 1 the default. Setting this to 0 will disable certain compiler optimizations and usually reduce performance.

Output Options

load:

When loading is requested, the abstract machine code produced by the compiler gets assembled and loaded into memory as executable code. Values for the 'load' option are:

all (default): Load and replace code in memory, create/re-create all modules, interpret pragmas, and execute all directives and queries.
none: Do not load any code into memory, do not execute queries, but interpret pragmas and execute directives. Do not re-create modules, but create new ones and erase them again after compilation.
new: Do not overwrite any code in memory, but load new predicates. Do not execute queries, but interpret pragmas and execute directives. Do not re-create modules, but create new ones and erase them again after compilation. For existing modules, erase pragmas.

output:

The abstract machine code which is the result of the compilation can be output in various forms. Values for 'output' option (default: none):

none: no output (but code may be loaded, see load option),
asm: output compiled code in asm format to input file with .asm suffix. This format represents the code as WAM code that can be loaded back into ECLiPSe using the assembler (lib(asm)).
asm(File): output compiled code in asm format to File.
eco: output compiled code in eco format to input file with .eco suffix This format can be loaded using ensure_loaded/1 or the compiler itself.
eco(File): output compiled code in eco format,
print: print resulting WAM code to the output stream,
print(Stream): print WAM code to Stream,
listing: print WAM code to input file with .lst suffix,
listing(File): print WAM code to File,

outdir:

Value is the destination directory for all output files. The default is the empty string "", meaning that all output files go into the same directory as the corresponding input file.

Information Options

verbose:: This option controls whether the compiler produces any log messages to the log_output stream. The value is a positive integer. Level 0 is the most silent, 1 is quiet, 2 is verbose. Level 1 produces a log of all compiled predicates. Default: 0.
warnings:: Controls (on/off) whether warnings are printed during compilation. Default: on. The setting can be changed via a pragma (warnings/nowarnings) in the code.

Expert Options

expand_clauses:: This option (off/on, default:on) determines whether clause macros, such as DCGs and delay clauses are being expanded. Should not be switched off.
print_normalised:: Print result of the normalisation pass (on/off, default:off).
print_indexes:: Print result of indexing analysis (on/off, default:off).
print_lifetimes:: Print result of the variable lifetime analysis (on/off, default:off).
print_raw_code:: Print annotated WAM code before register allocation (on/off, default:off).
print_final_code:: Print annotated WAM code after register allocation (on/off, default:off).
skip:: This option (off/on, default:off) determines whether all compiled predicates have their 'skip' flag set by default. This means that subgoals of these predicates will be hidden in the debugger trace, unless the flag is reset at runtime. The setting can be changed via a pragma (skip/noskip) in the code.
srcroot:: This is used to make the compilation result (e.g. .eco files) independent of absolute source file names: when the option is set to a non-empty string, wich is a parent directory of a source file, the source file property of the compiled predicates will be set as a pathname relative to the given root directory.
system:: This option (off/on, default:off) causes all compiled predicates to have their type-flag set to 'built_in'. This is used for compiling system files. Same effect as a system-pragma in the code.

Compiling Modules

In the absence of module-directives (module/1,3) within the file, the file content is compiled into the module from which compile/2 itself was called. This context module may be modified using the @/2 notation, i.e. compile(File,Options)@Module. Existing static predicates will be redefined, and clauses for dynamic predicates appended to the existing ones (unless the 'load' option requests otherwise).

If the compiled file contains module directives (module/1,3), these specify to which module(s) the compiled code belongs. Module directives are effective from the point where they occur until the next module directive, or until the end of file. If a module directive refers to a module that exists already, this module is erased and redefined (unless the 'load' option requests otherwise).

For backward compatibility with older ECLiPSe versions, we allow a module name in place of the Options-list. If this module does not exist, compile/2 will create such a module and compile the content of file into this module, as with compile(File)@Module.

In addition to the exceptions listed below, any exception can occur during compilation, because general code may be executed in directives (:-/2), file queries (?-/2), macro transformations and inline expansion code.

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault: Either File or Options is not instantiated.
(5) type error: File is instantiated, but not to a valid source specification.
(5) type error: Options is not a valid options list, nor a module name.
(61) inconsistent tool redefinition: A predicate that was already defined is later declared to be a tool.
(62) inconsistent procedure redefinition: Illegal attempt to change a predicate's properties like: tool, dynamic, demon, parallel, calling convention.
(82) trying to access a locked module: The module in which the clauses should be compiled is locked.
(94) trying to redefine an existing imported procedure: There is already am imported predicate of the same name.
(130) illegal clause head: The head of a clause is not an atom or a compound term.
(131) illegal goal in clause body: A subgoal in the body of a clause is not an atom, a compound term or a variable.
(134) procedure clauses are not consecutive: The clauses of a procedure are not consecutive.
(136) trying to redefine a built-in predicate: Attempt to redefine a built-in predicate without declaring it first.
(137) trying to redefine a procedure with another type: A procedure which was previously referenced as built-in or external is now defined as a regular one, or vice versa.
(139) compiled or dumped file message: This event is invoked at the end of each compiled file, by default it prints the compilation time and size of compiled code.
(143) compiled query failed: A query in the compiled file has failed. This is by default ignored and the compilation continues.
(145) procedure being redefined in another file: A procedure is being redefined in another file than the original one.
(147) compilation aborted: This event is raised just before a compilation is aborted because of an error.
(148) bad pragma: An unrecognised pragma was used in the code.
(171) File does not exist :: File does not exist.

Examples

    ?- compile(myfile, [debug:off]).

    ?- compile("MyFile.ecl", [output:eco]).

    ?- compile("MyFile", [verbose:1,opt_level:0]).