.\" ------------------------------ sec2.t ------------------------------ .sh 1 "Getting Started" .pp This section is intended to give a broad overview of the SB-Prolog system, so as to enable the new user to begin using the system with a minimum of delay. Many of the topics touched on here are covered in greater depth in later sections. .sh 2 "The Dynamic Loader Search Path" .pp In SB-Prolog, it is not necessary for the user to load all the predicates necessary to execute a program. Instead, if an undefined predicate \fIfoo\fR is encountered during execution, the system searches the user's directories in the order specified by the environment variable SIMPATH until it finds a directory containing a file \fIfoo\fR whose name is that of the undefined predicate. It then dynamically loads and links the file \fIfoo\fR (which is expected to be a byte code file defining the predicate \fIfoo\fR), and continues with execution; if no such file can be found, an error message is given and execution fails. This feature makes it unnecessary for the user to have to explicitly link in all the predicates that might be necessary in a program: instead, only those files are loaded which are necessary to have the program execute. This can significantly reduce the memory requirements of programs. .pp The key to this dynamic search-and-load behaviour is the SIMPATH environment variable, which specifies the order in which directories are to be searched. It may be set by adding the following line to the user's .\fIcshrc\fR file: .(l setenv SIMPATH \fIpath\fR .)l where \fIpath\fR is a sequence of directory names separated by colons: .(l \fIdir\fR\*<1\*>:\fIdir\fR\*<2\*>: ... :\fIdir\*\fR .)l and \fIdir\*\fR are \fIfull path names\fR to the respective directories. For example, executing the command .(l setenv SIMPATH .:$HOME/prolog/modlib:$HOME/prolog/lib .)l sets the search order for undefined predicates to the following: first, the directory in which the program is executing is searched; if the appropriate file is not found in this directory, the directories searched are, in order, ~/prolog/modlib and ~/prolog/lib. If the appropriate file is not found in any of these directories, the system gives an error message and execution fails. .pp The beginning user is advised to include the system directories (listed in the next section) in his SIMPATH, in order to be able to access the system libraries (see below). .sh 2 "System Directories" .pp There are four basic system directories: cmplib, lib, modlib and sim. \fIcmplib\fR contains the Prolog to byte code translator; \fIlib\fR and \fImodlib\fR contain library routines. The \fIsrc\fR subdirectory in each of these contains the corresponding Prolog source programs. The directory \fIsim\fR contains the simulator, the subdirectory \fIbuiltin\fR contains code for the builtin predicates of the system. .pp It is recommended that the beginning user include the system directories in his SIMPATH, by setting SIMPATH to .(l C .\|:\|\fISBP\fR/modlib\|:\|\fISBP\fR/lib\|:\|\fISBP\fR/cmplib .)l where \fISBP\fR denotes the path to the root of the SB-Prolog system directories. .sh 2 "Invoking the Simulator" .pp The simulator is invoked by the command .(l sbprolog \fIbc_\|\^file\fR .)l where \fIbc_\|\^file\fR is a byte code file resulting from the compilation of a Prolog program. In almost all cases, the user will wish to interact with the SB-Prolog \fIquery evaluator\fR, in which case \fIbc_\|file\fR will be \fI$readloop\fR, and the command will be .(l sbprolog \fIPATH\fR/\e$readloop .)l where \fIPATH\fR is the path to the directory containing the command interpreter \fI$readloop\fR. This directory, typically, is \fImodlib\fR (see Section 2.2 above). .pp The command interpreter reads in a query typed in by the user, evaluates it and prints the answer(s), repeating this until it encounters an end-of-file (the standard end-of-file character on the system, e.g. ctrl-D), or the user types in \fIend_\|of_\|file\fR or \fIhalt\fR. .pp The user should ensure that the the directory containing the executable file \fIsim\fR (typically, the system directory \fIsim\fR: see Section 2.2 above) is included in the shell variable \fIpath\fR; if not, the full path to the simulator will have to be specified. .pp In general, the simulator may be invoked with a variety of options, as follows: .(l sbprolog \-\fIoptions\fR \fIbc_\|\^file\fR or sbprolog \-\fIoption\fR\*<1\*> \-\fIoption\fR\*<2\*> ... \-\fIoption\*\fR \fIbc_\|\^file\fR .)l The options recognized by the simulator are described in Section 4.2. .pp When called with a byte code file \fIbc_\|\^file\fR, the simulator begins execution with the first clause in that file. The first clause in such a file, therefore, should be a clause without any arguments in the head (otherwise, the simulator will attempt to dereference argument pointers in the head that are really pointing into deep space, and usually come to a sad end). If the user is executing a file in this manner rather than using the command interpreter, he should also be careful to include the undefined predicate handler `_\|\fI$undefined_\|pred\fR'/1, which is normally defined in the file \fImodlib/$init_\|sys.P\fR. .(x b (L) _\|$undefined_\|pred/1 .)x .sh 2 "Executing Programs" .pp There are two ways of executing a program: a source file may be compiled into a byte-code file, which can then be loaded and executed; or, the source file may be interpreted via \fIconsult\fR. The system supports full integration of compiled and interpreted code, so that some predicates of a program may be compiled, while others may be interpreted. However, the unit of compilation or consulting remains the file. The remainder of this section describes each of these procedures in more detail. .sh 3 "Compiling Programs" .pp The compiler is invoked through the Prolog predicate \fIcompile\fR. It translates Prolog source programs into byte code that can then be executed on the simulator. .(x b (L) compile/1 .)x .(x b (L) compile/2 .)x .(x b (L) compile/3 .)x .(x b (L) compile/4 .)x The compiler may be invoked as follows: .(l | ?- compile(\fIInFile\fR [, \fIOutFile\fR ] [, \fIOptionsList\fR ]). or | ?- compile(\fIInFile\fR, \fIOutFile\fR, \fIOptionsList\fR, \fIPredList\fR). .)l where optional parameters are enclosed in brackets. \fIInFile\fR is the name of the input (i.e. source) file; \fIOutFile\fR is the name of the output file (i.e. byte code) file; \fIOptionsList\fR is a list of compiler options, and \fIPredList\fR is a list of terms \fIP\fR/\fIN\fR denoting the predicates defined in \fIInFile\fR, where \fIP\fR is a predicate name and \fIN\fR its arity. .pp The input and output file names must be Prolog atoms, i.e. either begin with a lower case letter and consist only of letters, digits, dollar signs and underscores; or, be enclosed within single quotes. If the output file name is not specified, it defaults to \fIInFile\fB.out\fR. The list of options, if specified, is a Prolog list, i.e. a term of the form .(l [ \fIoption\fR\*<1\*>, \fIoption\fR\*<2\*>, ..., \fIoption\*\fR ]. .)l If left unspecified, it defaults to the empty list [\^]. \fIPredList\fR, if specified, is usually given as an uninstantiated variable; its principal use is for setting trace points on the predicates in the file (see Sections 6 and 8). Notice that \fIPredList\fR can only appear in \fIcompile\fR/4. .pp A list of compiler options appears in Section 8.3. .sh 3 "Loading Byte Code Files" .lp Byte code files may be loaded into the simulator using the predicate \fIload\fR: .(l | ?- load(\fIByteCode_\|File\fR). .)l where \fIByteCode_\|File\fR is a Prolog atom (see Section 3.1) that is the name of a byte code file. .(x b (B) load/1 .)x .pp The \fIload\fR predicate invokes the dynamic loader, which carries out a search according to the sequence specified by the environment variable SIMPATH (see Section 2.1). It is therefore not necessary to always specify the full path name to the file to be loaded. .pp Byte code files may be concatenated together to produce other byte code files. Thus, for example, if \fIfoo1\fR and \fIfoo2\fR are byte code files resulting from the compilation of two Prolog source programs, then the file \fIfoo\fR, obtained by executing the shell command .(l cat foo1 foo2 > foo .)l is a byte code file as well, and may be loaded and executed. In this case, loading and executing the file \fIfoo\fR would give the same result as loading \fIfoo1\fR and \fIfoo2\fR separately, which in turn would be the same as concatenating the original source files and compiling this larger file. This makes it easier to compile large programs: one need only break them into smaller pieces, compile the individual pieces, and concatenate the resulting byte code files together. .sh 3 "Consulting Programs" .pp Instead of compiling a file to generate a byte code file which then has to be loaded, a program may be executed interpretively by ``consulting'' the corresponding source file: .(x b (L) consult/1 .)x .(x b (L) consult/2 .)x .(l | ?- consult(\fISourceFile\fR [, \fIOptionList\fR ] ). or | ?- consult(\fISourceFile\fR, \fIOptionList\fR, \fIPredList\fR). .)l where \fISourceFile\fR is a Prolog atom which is the name of a file containing a Prolog source program; \fIOptionList\fR is a list of options to consult; and \fIPredList\fR is a list of terms \fIP\fR/\fIN\fR, where \fIP\fR is a predicate name and \fIN\fR its arity, specifying which predicates have been consulted from \fISourceFile\fR; its principal use is for setting trace points on the predicates in the file (see Section 6). Notice that \fIPredList\fR can only appear in \fIconsult\fR/3. .pp At this point, the options recognized for \fIconsult\fR are the following: .lp \fBfirst\fR .ip If on, causes each clause read in to be added as the first clause of the database (so that effectively, the clauses appear in the reverse order as in the source file). Default: off. .lp \fBindex\fR .ip If on, causes an index to be generated on the first argument of each predicate. Default: off. .ip \fBindex(N)\fR If on, causes an index to be generated on the N\*[th\*] argument of each predicate. Default: off. .ip \fBq\fR ``quick''. If on, invokes a consultation algorithm that is simpler and more efficient than the general one. However, the code generated with the simpler algorithm may not be correct if there are repeated variables within compound terms in the body of the clause, e.g. in .(l p(X) :\- q([X, X]). .)l Default: off. .ip \fBt\fR ``trace''. Causes a trace point to be set on any predicate in the current file that does not already have a trace point set. .ip \fBv\fR ``verbose''. Causes information regarding which predicates have been consulted to be printed out. Default: off. .lp In addition to the above, the options specified for the macro expander are also recognized (see Section 10)). .pp It is important to note that SB-Prolog's \fIconsult\fR predicate is similar to that of Quintus Prolog, and behaves like C-Prolog's \fIreconsult\fR. This means that if a predicate is defined across two or more files, consulting them will result in only the clauses in the file consulted last being used. .sh 2 "Execution Directives" .pp Execution directives may be specified to \fIcompile\fR and \fIconsult\fR through :\-/1. If, in the read phase of \fIcompile\fR or \fIconsult\fR, a term with principal functor :\-/1 is read in, this term is executed directly via \fIcall\fR/1. This enables the user to dynamically modify the environment, e.g. via \fIop\fR declarations (see Section 3.2), \fIassert\fRs etc. .(x b (P) :\-/1 .)x .pp A point to note is that if the environment is modified as a result of an execution directive, the modifications are visible only in that environment. This means that consulted code, which runs in the environment in which the source program is read in (and which is modified by such execution directives) feel the effects of such execution directives. However, byte code resulting from compilation, which, in general, executes in an environment different from that in which the source was compiled, does not inherit the effects of such directives. Thus, an \fIop\fR declaration can be used in a source file to change the syntax and allow the remainder of the program to be parsed according to the modified syntax; however, these modifications will not, in general, manifest themselves if the byte code is executed in another environment. Of course, if the byte code is loaded into the same environment as that in which the source program was compiled, e.g. through .(l | ?- compile(foo, bar), load(bar). .)l the effects of execution directives will continue to be felt. .\" -------------------- end of sec2.t -------------------- .