Qu-Prolog 10.8 Reference Manual - Getting Started

# 1 Getting Started

This section describes how to set up the required environment variables and briefly describes how to run the interpreter and compiler.

## 1.1 Environment Variables

The root directory of the Qu-Prolog tree contains the files `PROFILE_CMDS` and `LOGIN_CMDS` that can be used to define the required environment variables.

## 1.2 Data Areas

Qu-Prolog contains several data areas that store execution state information. The sizes of these areas can be set at runtime or when new threads are created. The data areas are described below.

The global stack (sometimes called the heap).

> The global stack stores the Qu-Prolog terms build during forward execution.

The scratch pad.

> The scratch pad is used for storing terms temporarily during the execution of `findall`, `setof` and `bagof` and for simplifying terms involving substitutions.

The local stack (environment stack).

> The local stack contains all the environments for the current execution state.

The choice point stack.

> The choice point stack contains all the choice points for the current execution state.

The binding trail.

> This trail is used to determine which variables should be reset to unbound on backtracking.

The other trail.

> Some Qu-Prolog data structures change values during computation and this trail is used to reset these data structures to their old values on backtracking. Such data structures include the delay list associated with a variable, the distinctness information associated with an object variable, the names of variables, and implicit parameters. It is also used to manage variable tags, reference counts for the dynamic database and `call_cleanup`.

The code area.

> The code area is used to store the static (compiled) code. It includes all the Qu-Prolog library code.

The string table.

> The string table stores all the strings used as the names of atoms.

The name table.

> The name table is a hash table used to associate variable names with variables.

The implicit parameter table.

> The implicit parameter table is a hash table that stores (pointers to) the current value of the implicit parameters.

The atom table.

> The atom table is a hash table that stores information about atoms.

The predicate table.

> The predicate table is a hash table that associates predicates (name and arity) with the code for the predicate.

## 1.3 Running the Interpreter

`qp` is the name of the Qu-Prolog interpreter. From a `Unix` shell, Qu-Prolog is started by typing:

`qp`

When the interpreter is ready to accept a query, it will prompt you with

`| ?-`

When the interpreter displays an answer it is accompanied with any delayed problems (constraints) relevant to the query. After the interpreter displays an answer to a query it expects input from the user. If the user enters a semi-colon then the interpreter will attempt to find another solution to the query. If the user enters a RETURN then the interpreter will prompt for a new query. If the user enters a comma then the interpreter will enter a new level where the user can extend the current query with more goals. Any variables in the original query and in the displayed answer to that query may be referenced in the extended query. The user may return to the previous level by entering a CONTROL-D at the prompt. The interpreter is able to maintain references to variables by using the variants of `read` and `write` that remember and generate variable names.

The available switches for the interpreter (and any Qu-Prolog runtime system) are as follows.

`-B size`

> Set the binding trail size to `size` K words. The default size is 32K.

`-O size`

> Set the other trail size to `size` K words. The default size is 32K.

`-i size`

> Set the implicit parameter table size to `size` entries. The system makes the size of the table the next power of two bigger than twice the supplied size. The default size is 10000.

`-b size`

> Set the recode database to `size` K words. The default size is 64K.

`-C size`

> Set the choice point stack to `size` K words. The default size is 64K.

`-e size`

> Set the environment stack to `size` K words. The default size is 64K.

`-h size`

> Set the heap (global stack) to `size` K words. The default size is 400K.

`-H size`

> Set the scratch pad to `size` K words. The default size is 10K.

`-n size`

> Set the name table to `size` entries. The system makes the size of the table the next power of two bigger than twice the supplied size. The default size is 10000.

`-z size`

> Set the thread table to `size` entries. The default size is 100. This switch determines the maximum number of threads that can be running at any time.

`-N server-name`

> Set the machine (IP address) on which the Pedro server is running to `server-name`. The default is the current machine (localhost).

`-P server-port`

> Set the port on which the Pedro server is listening to `server-port`. The default is 4550.

`-A process-symbol`

> Set the name of this process to `process-symbol`.

`-l initialization-file`

> Consult `initialization-file` before the interpreter starts.

`-g initial-goal`

> Execute `initial-goal` before the interpreter starts but after initialization file is loaded (if any).

An online manual `qp(1)` is available to explain the options available to the interpreter.

## 1.4 Running the Compiler

As well as running programs in interpreted mode, Qu-Prolog programs can be compiled for faster execution.

Declarations appearing in the source code of the form

`?- Decl.`

or

`:- Decl.`

are executed by the compiler and are also compiled for execution at load time. The exceptions to this are `index/3` and `compile_time_only/1` declarations which are executed by the compiler only.

`qc` is an interface to the Qu-Prolog compilation system. The system consists of a preprocessor, a term expander, a compiler, an assembler, and a linker. `qc` processes the supplied options and calls each component with the appropriate arguments in the sequence given above.

A common usage of `qc` is where the user supplies a Qu-Prolog source program. `qc` compiles the program and generates an executable. The executable is stored in two files. `exec_file` (e.g. `a.out`) contains the basic information about the executable and `exec_file.qx` (e.g. `a.out.qx`) has the essential data about the program. To run the executable, the user types in `exec_file`.

`qc` accepts several types of filename arguments.

Files ending with `.ql` are Qu-Prolog source programs.

Files ending with `.qi` indicates that the file has been preprocessed.

Files ending with `.qg` are taken to contain clauses after term expansion.

Files ending with `.qs` are Qu-Prolog assembly programs.

Object files have the suffix `.qo`.

The compiler also accepts byte-encoded files produced by the encoded write of Qu-Prolog. Encoded files must have `.qle` or `.qge` extensions and are encoded equivalents of `.ql` and `.qg` files.

The available switches for the compiler are as follows.

`-D macro`

> Define `macro` as 1 (one). This is the same as if a
> `#define macro 1`
> line appeared at the beginning of the `.ql` file being compiled.

`-E`

> Stop after running the preprocessor. The output is placed in the corresponding file suffixed `.qi`.

`-G`

> Stop after running the term expander. The output is placed in the corresponding file suffixed `.qg`.

`-R file`

> Supply the term expansion rules (in `file`) to the term expander.

`-S`

> Stop after running the compiler. The output is placed in the corresponding file suffixed `.qs`.

`-c`

> Stop after running the assembler. The default output file is the corresponding file suffixed `.qo`.

`-o exec_file`

> Name the object file if the `-c` switch is also supplied. Otherwise, name the executable. If `exec_file` is not supplied the default name for the executable is `a.out`.

`-r`

> Add `rlwrap` to the runtime system to provide history and command line editing. This is used for the interpreter. The runtime system (shell script) may need to be edited if `rlwrap` is to behave in a different way.

The `qp` switches are used to alter the size of different data areas for the compiler.

The `ql` switches (see below) fix the size of some of the data areas in the executable being generated.

The Qu-Prolog linker (`ql`) links `.qo` files to produce an executable.

The available switches for the linker are as follows.

`-a size`

> Set the size of the atom table to `size` entries. The system makes the size of the table the next power of two bigger than twice the supplied size. The default size is 10000.

`-d size`

> Set the code area to `size` K bytes. The default size is 400K bytes.

`-p size`

> Set the size of the predicate table to `size` entries The system makes the size of the table the next power of two bigger than twice the supplied size. The default size is 10000.

`-s size`

> Set the string table to `size` K bytes. The default size is 64K bytes.

An online manuals `qc(1)` and `ql(1)` is available to explain the options available to the compiler and linker.

## 1.5 Online Manuals

Included with the Qu-Prolog release is a `HTML` version of this manual. To access this version open the file `$QPHOME/doc/manual/MAIN.html` in a browser.

## 1.6 User Guide

The system is supplied with a User Guide (Technical Report 00-20) that introduces the basic concepts of Qu-Prolog and presents some example programs and sessions with the interpreter.

Example programs are supplied in the `examples` directory.

## 1.7 Windows Users

The Windows installer for Qu-Prolog updates the PATH variable to include the Qu-Prolog executables. All Qu-Prolog programs should be run from a Command Prompt window. In the manual Control-D is used for end-of-file. For Windows users, end-of-file is Control-Z followed by a Enter.

If the foreign function interface is required then the mingw compiler needs to be installed to manage the compilation and linking of C code.

Table of Contents | Getting Started | Syntax | Built-in Predicates | Standard Operators | Notation | Index