6.2 Compiler Invocation
The compiler is usually invoked by calling one of the following built-in
predicates:
-
compile(Source)
-
This is the standard compiler predicate.
Source is usually a file name, other forms are detailed below.
The contents of the file is compiled with the default compiler options.
- compile(Source, Options)
-
This is the standard compiler predicate.
Source is usually a file name, other forms are detailed below.
Options is a list of options to control the compilation process, see details below.
- [File1,...,FileN]
-
This predicate can be used as a shorthand for the
compile/1
predicate.
It accepts a list of files, which can be source files or precompiled files.
- compile_stream(Stream)
-
This predicate compiles a given, open stream up to its end
or to the end_of_file clause.
It can be used when the input file is already open,
e.g. when the beginning of the file does not contain
compiler input.
- compile_stream(Stream,Options)
-
Like compile_stream/1 but with options list.
- compile_term(Clauses)
-
This predicate is used to compile a given term,
usually a list of clauses and directives.
Unlike assert/1 it compiles
a static procedure,
and so it can be used to compile a procedure which is dynamically
created and then used as a static one.
- compile_term(Clauses,Options)
-
Like compile_stream/2 but with options list.
When using a development environment like
TkEclipse or Saros, the compiler is usually invoked implicitly via
menu options or buttons.
6.2.1 Source Files
Program source is usually contained in files. The recommended file
suffixes (extensions) are
-
.ecl for ECLiPSe specific source
- .pl for Prolog source
To compile a source files solver.ecl, any of the following forms is
acceptable:
?- compile('solver.ecl').
?- compile("solver.ecl").
?- compile("/home/joe/solver.ecl").
?- compile("/home/joe/solver").
?- compile(solver).
File names need to be single quoted (atom) or double quoted (string)
if they contain punctuation, blank space, or start with an upper case letter.
The .ecl extension can be omitted as long as no file without extension
is present. A .pl extension can be omitted as long as no file without
extension and no file with .ecl extension is present. The list of
accepted suffixes and their precedence is given by the global flag
prolog_suffix, see
get_flag/3.
The following shorthands can be used, but note that the last two forms
will load precompiled .eco files by preference, should they be present:
?- ['solver.ecl'].
?- ["solver.ecl"].
?- ["/home/joe/solver.ecl"].
?- ["/home/joe/solver"].
?- [solver].
If the source is given as library(Name), the predicates looks for the file
in the directories from the global flag library_path.
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.
?- [user].
main :- writeln(hello).
^D
tty compiled 72 bytes in 0.01 seconds
Yes (0.01 cpu)
?- main.
hello
Yes (0.00s cpu)
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 (or the end_of_file marker).
Using this feature, any ECLiPSe stream (file, socket, tty, string,
queue, pipe) can be used as the source for program text.
6.2.2 Main Compiler Options
The following compiler options affect the generated code:
-
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.
- 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.
The setting can be changed via an opt_level(Level) pragma in the code.
The following options determine what is being done with the compilation result:
-
load:
-
Determines whether the generated code is immediately loaded into memory,
ready for execution. 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. Possible values are:
-
none (default)
-
no output (but code may be loaded, see load option),
- 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 to File.
- 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.
- 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.
For other options see
compile/2.
For example, to compile a program without debugging support directly into
memory, use
?- compile(myprogram, [debug:off]).
The following command will create a precompiled file myprogram.eco from a
source file called myprogram.ecl (or myprogram.pl):
?- compile(myprogram, [output:eco]).