[ Predicate Database and Compiler | Reference Manual | Alphabetic Index ]
Compile specified file, or list of files, with given options
- Source file name (atom or string) or structure stream(Stream)
- List of compiler options (name:value pairs)
Compiles the specified ECLiPSE source file or list of source files,
with the given options. See below for a detailed description of the
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
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
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
Options is a possibly empty list of OptionName:OptionValue pairs.
Code Generation Options
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.
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.
Currently the integer 0 or 1, with 1 the default. Setting this to 0
will disable certain compiler optimizations and usually reduce performance.
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.
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.
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.
The abstract machine code which is the result of the compilation can
be output in various forms. Values for 'output' option (default: none):
no output (but code may be loaded, see load option),
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)).
output compiled code in asm format to File.
output compiled code in eco format to input file with .eco suffix
This format can be loaded using ensure_loaded/1 or the compiler
output compiled code in eco format,
print resulting WAM code to the output stream,
print WAM code to Stream,
print WAM code to input file with .lst suffix,
print WAM code to File,
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.
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.
Controls (on/off) whether warnings are printed during compilation.
The setting can be changed via a pragma (warnings/nowarnings) in the code.
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 result of the normalisation pass (on/off, default:off).
Print result of indexing analysis (on/off, default:off).
Print result of the variable lifetime analysis (on/off, default:off).
Print annotated WAM code before register allocation (on/off, default:off).
Print annotated WAM code after register allocation (on/off, default:off).
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.
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
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.
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.
This predicate is sensitive to its module context (tool predicate, see @/2).
- (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.
?- compile(myfile, [debug:off]).
?- compile("MyFile.ecl", [output:eco]).
?- compile("MyFile", [verbose:1,opt_level:0]).
compile / 1, compile_stream / 1, compile_term / 1, compile_term / 2, ensure_loaded / 1, lib / 1, use_module / 1, pragma / 1, fcompile : fcompile / 1