The PrologJ Compiler

Overview

The PrologJ system includes a compiler that can translate Prolog source file into a Java .class file, which can be loaded into the Prolog system at run time, or can be used by other Java .class files (either compiled from Prolog source code or written directly in Java), or can be run as a stand-alone application (perhaps in conjunction with other .class files).

The compilation process turns a Prolog source file into a single Java class whose name is the same as the base name of the source file (name minus the .pro file type). (This requires that the base name of any Prolog source file that is to be compiled must be a legal Java class name.)

The compiled file contains a translation of each clause appearing in the source file. Though it would be unusual to do so, it is legal to compile a file that contains no clause definitions, in which case the compiled file still contains the other components discussed below.

The compiled file may contain a main method and/or one or more entry points callable from Java code, if the source file contains, respectively, a :- main/1 directive or one or more :- entry/1 directives.

In addition to the above, the compiled file also contains a static initializer method that is run by the JVM when the class file is loaded. The static initializer performs the following tasks in the order indicated:

• For each predicate for which the source file contained one or more clauses, it either adds the clause definitions to an existing predicate of that functor and arity (assuming it allows multifile definition) or it creates a new predicate of that functor and arity. As a result, a predicate that is defined in a compiled file that has been loaded can be accessed from other compiled files or from the interpreter. Note that an implication of this is that if a given predicate is defined in multiple source files (and allows multifile defintion), the order of the clauses for the predicate will depend on the order in which the compiled files are loaded.
• If the source file contained any :- ensure_loaded/1 directive(s), it loads the specified file(s), unless already loaded.
• If the source file contained any :- initialization/1 directives, it causes the indicated goal(s) to be called.

The compiled code makes use of various classes defined in the PrologJ implementation. For this reason, the file prologj.jar must always be in the classpath when the compiled file is used.

Running the Compiler

The PrologJ compiler can be started in one of three ways. Note that these are similar to the ways that one starts the interpreter. When starting from the command line, the interpreter or compiler is run depending on whether or not any file(s) to compile are specified on the command line.

• By running the prologj.jar file as an application in the platform-specific way (typically by double-clicking it), and then using the Compiler menu to specify one or more files to compile.
   
• By issuing a command at the command line that starts the interpreter, with the -w[indow] option specified, and then using the Compiler menu to specify one or more files to compile.
   
• By issuing the following command at the command line, or embedded in a script:

  	java -jar prologj.jar [ options ] file[s]
  	

  (where options are discussed below, and file[s] are the name(s) of one or more Prolog source files to be compiled)

Regardless of how the compiler is started, the :- set_prolog_flag/3 directive may be included in the source code to specify any special flag settings needed.

If the compiler is started up by using the Compiler menu in the console window, the Library Components menu may be used to specify what predicates are considered to be built-in predicates in the code being compiled, and the Flags menu may be used to specify the initial settings of the flags, before actually running the compiler. Additional items in the Compiler menu control various other aspects of the compilation process. These are all documented in the documentation for the console window.

If the compiler is started up from the command line or a script, the following options may be specified. Each option name may be abbreviated to as little as just its first letter. Note that these options are similar to those available when starting the interpreter, but not identical. The compiler is started just when one or more files are specified on the command line; otherwise the interpreter is started.

• -l[ibrary] libraries
   
  Controls what built-in predicate categories are available to the code being compiled. The parameter libraries is some combination of the letters corresponding to the predicate categories desired, or - to use just the subset of core predicates that are common to both ISO and "traditional" Prolog. Note that the availability of built-in predicates is governed by any -l[ibrary] option in effect when the code is compiled; the run-time setting of this option has no effect on how the compiled code interprets predicates.
   
  If this command option is not specified, all built-in predicate categories are available .
   
• -f[lags] flags
   
  Controls the initial setting of the flags that are in effect while reading a source file. The source file may change the flag settings with a :- set_prolog_flag/2 directive. This option has no effect on the flag settings when the program is executed; to control this, the program must execute a call of the built-in predicate set_prolog_flag/2. The parameter flags is one of the following:
   
  • s specifies initial flag settings to produce behavior that conforms strictly to the defaults specified in the ISO standard.
  • r specifies a "relaxed" version of the ISO settings which might be more useful in conjunction with code development using the interpreter. With these settings, an attempt to call an undefined predicate results in a warning, rather than an error; and the rules pertaining to predicate contiguity, appearance in multiple source files, and dynamic and public predicates are not enforced.
  • t specifies "traditional" behavior consistent with [ Clocksin and Mellish 1994 ]. With these settings, an attempt to call an undefined predicate results in simple failure, rather than an error or a warning; the rules pertaining to predicate contiguity, appearance in multiple source files, and dynamic and public predicates are not enforced; and the operator / means integer division when both of its arguments are integers.
   
  If this command option is not specified, the flags are set in accordance with the defaults specified in the ISO standard.
   
• -j[ava]
   
  The compilation process first translates the Prolog source file into a Java file. If this option is not specified, then the Java file is compiled with javac to produce a .class file, and then the Java file is deleted. If this option is specified, the compilation process stops with the creation of the Java file, which is not deleted, but rather is left in the current working directory, or in a different directory if specified by the -d[irectory] option.
   
• -v[erbose]
   
  Requests verbose compilation. A line is printed for each clause, and for each entry, initialization, main, or package directive processed. In addition, if the -j[ava] option is not present, then javac is invoked with the -verbose option as well.
   
• -d[irectory] path
   
  
  • path must name a writable directory.
     
  Controls where the compiled code is placed. A java source file produced by compilation is put in the directory specified. A Java class file may be placed in a subdirectory if the source file contains a :- package/1 directive.
   
  If this option is not present, the compiled code (.java source file or .class file) is placed in the current working directory or a subdirectory of it.

If the compiler is started up from the command line or a script, each file must be a full specification for one file to be compiled. It must include the .pro extension. (This is consistent with the requirements for javac and most other language compilers.) The file is sought in the current working directory; if it is located somewhere else the parameter must include a suitable path specification.

Dealing with Code Size Limitations

When compiling a very large source file, it is possible that the resultant java file may cause a code size overflow error during compilation by javac. In this case, the source file should be broken up into smaller files that are compiled separately. (The main file can cause the others to be loaded by use of the :- ensure_loaded/1 directive.)

Copyright © 2005 - Russell C. Bjork. See the file See file COPYING in the root directory for copyright information.