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_term/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.
Program source is usually contained in files. The recommended file name suffixes (extensions) are
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 must 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.
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
- (This is the 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
- (This is the default). No output (but code may be loaded, see load option).
- eco
- output compiled code in eco format to a file whose suffix is .eco. 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 a file whose suffix is .asm. 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]).