<h1><aclass="back"title="Return to index"href="index.html#installing">Installing and running Logtalk</a></h1>
<hr/>
<h2><aclass="back"title="Return to index"name="installing"href="index.html#installing_installing">Installing Logtalk</a></h2>
<p>
The Logtalk system can be installed in any directory that is accessible to the user. The installation process consists merely in decompressing an archive file that will lead to a new directory with the structure/contents described below. The decompression process naturally depends on the operative system that you are using.
The Macintosh version is included in the file <code>lgt2xx.sea.bin</code>, a <code>MacBinary</code> encoded, self-extracting archive. Your web browser should automatically decode the file, giving you a <code>.sea</code> self-extracting archive that you double-click to install Logtalk. If not, drag and drop the <code>.bin</code> file in a utility like <code>StuffIt Expander</code> or <code>MacBinaryII+</code>.
The Linux/Unix version is included in the file <code>lgt2xx.tar.gz</code>. In order to decompress and install the system we can use the following commands:
</p>
<pre>
% gunzip lgt2xx.tar.gz
% tar -xvf lgt2xx.tar
</pre>
<p>
This will create a sub-directory named <code>lgt2xx</code> in your current directory.
</p>
<h4>OS/2, Windows 95/98/NT/ME/2000</h4>
<p>
The OS/2 and Windows 95/98/NT/ME/2000 version is included in the file <code>lgt2xx.zip</code>. The file can be decompressed using an utility like <code>unzip</code>:
</p>
<pre>
unzip lgt2xx.zip
</pre>
<h4>Other operating systems</h4>
<p>
Almost all files in the Logtalk distribution are text files. The only difference between the source files, other than the compressing formats, is the end-of-line codes: Macintosh uses a carriage return, Unix uses a line feed, OS/2, Windows 95/NT uses both a carriage return and a line feed. This should make it easier to install Logtalk under other operating systems.
</p>
<h3><aclass="back"title="Return to index"name="organization"href="index.html#installing_organization">Directories and files organization</a></h3>
<p>
In the Logtalk installation directory, you will find the following files and directories:
</p>
<dl>
<dt><code>LICENSE</code> - Logtalk user license</dt>
<dt><code>QUICK_START</code> - Quick start instructions for those that do not like to read manuals</dt>
<dt><code>README</code> - several useful information</dt>
<dt><code>RELEASE_NOTES</code> - release notes for this version</dt>
<dt><code>UPGRADING</code> - instructions in how to upgrade your programs to the current Logtalk version</dt>
<dt><code>compiler</code></dt>
<dd><code>NOTES</code> - notes on the current status of the compiler</dd>
<dd><code>...</code> - compiler source files</dd>
<dt><code>configs</code></dt>
<dd><code>NOTES</code> - notes on the provided configuration files</dd>
<dd><code>...</code> - other XML related files</dd>
</dl>
<h3><aclass="back"title="Return to index"name="configs"href="index.html#installing_configs">Configuration files</a></h3>
<p>
Logtalk includes several configuration files for most academic and commercial Prolog compilers. If a configuration file is not available for the compiler that you intend to use, then you need to build a new one, starting from the included <code>template.config</code> file.
</p>
<p>
Since most Prolog compilers are moving closer to the ISO Prolog standard <ahref="../bibliography.html#ISO95">[ISO 95]</a>, it is advisable that you try to use a recent version of your Prolog compiler of choice.
</p>
<h3><aclass="back"title="Return to index"name="compiler"href="index.html#installing_compiler">Logtalk compiler and runtime</a></h3>
The <code>compiler</code> sub-directory contains the Prolog source file(s) that implement the Logtalk preprocessor/compiler and the Logtalk runtime. The compiler and the runtime may be split in two (or more) separate files or combined in a single file, depending on the Logtalk release that you are installing.
<h3><aclass="back"title="Return to index"name="library"href="index.html#installing_library">Library</a></h3>
<p>
Starting from version 2.7, Logtalk contains a standard library of useful objects, categories, and protocols. Read the corresponding <code>NOTES</code> file for details about the library contents.
</p>
<h3><aclass="back"title="Return to index"name="examples"href="index.html#installing_examples">Examples</a></h3>
<p>
Logtalk 2.x contains new implementations of some of the examples provided with previous 1.x versions. The sources of each one of these examples can be found included in a subdirectory with the same name, inside the directory examples. The majority of these examples include a file named <code>SCRIPT</code> that contains cases of simple utilization. Some examples may depend on other examples and library objects to work properly. Read the corresponding <code>NOTES</code> file for details before running an example.
</p>
<h3><aclass="back"title="Return to index"name="entities"href="index.html#installing_entities">Logtalk source files</a></h3>
Each Logtalk entity (object, category or protocol) is contained in a text file named after the entity. The extension <code>.lgt</code> is normally used. The Logtalk preprocessor compiles these files to plain Prolog, replacing the <code>.lgt</code> extension with <code>.pl</code> (the default Prolog extension). If your Prolog compiler expects the Prolog source filenames to end with a specific, different extension, you can set it in the corresponding configuration file.
<h3><aclass="back"title="Return to index"name="loaders"href="index.html#installing_loaders">Loader utility files</a></h3>
<p>
Most examples directories contain a Prolog utility file that can be used to load all included source files. These loader utility files are named <code><dir name>.loader</code> and should be consulted like any ordinary Prolog file.
</p>
<p>
Usually these files contain a call to the Logtalk built-in predicates <atitle="Consult reference manual"href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> or <atitle="Consult reference manual"href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a>, wrapped inside an <code>initialization/1</code> directive (to ensure ISO compatiblity). For instance, if your code is split in three Logtalk source files named <code>source1.lgt</code>, <code>source2.lgt</code>, and <code>source3.lgt</code>, then the contents of your loader file will be:
</p>
<pre>
:- initialization(
logtalk_load([
source1,
source2,
source3])).
</pre>
<p>
These loader files may not work without modifications depending on the way your Prolog compiler deals with folders/directories. Most of the time you will need to <strong>set the working directory</strong> to be the one that contains the loader file in order to get the example source files loaded. Unfortunately, there is no portable way for us to do that from inside Logtalk due to differences between operating systems and lack of adequate operating system access support in some Prolog compilers.
</p>
<hr/>
<h2><aclass="back"title="Return to index"name="running"href="index.html#installing_running">Running a Logtalk session</a></h2>
<p>
We run Logtalk inside a normal Prolog session, after loading the needed files. Logtalk extends but does not modify your Prolog compiler. We can freely mix Prolog queries with the sending of messages and our programs can be made of both normal Prolog clauses and object definitions.
</p>
<h3><aclass="back"title="Return to index"name="starting"href="index.html#installing_starting">Starting Logtalk</a></h3>
<p>
To start a Logtalk session just:
</p>
<ol>
<li>Start Prolog.</li>
<li>Load the appropriate configuration file for your compiler. Configuration files for most common Prolog compilers can be found in the <code>configs</code> subdirectory.</li>
Note that the both configuration files and compiler/preprocessor files are Prolog source files. The predicate called to load (and compile) them depends on your Prolog compiler. In case of doubt, consult your Prolog compiler reference manual or take a look at the definition of the predicate <code>lgt_load_prolog_code/1</code> in the corresponding configuration file.
Your programs will be made of source files containing your objects, protocols and categories. After changing the Prolog working directory to the one containing your files, you can compile them to disk by calling the Logtalk built-in predicate
This predicate runs the preprocessor on each argument file and, if no fatal errors are found, outputs Prolog source files that can then be consulted or compiled in the usual way by your Prolog compiler. Note that the predicate argument must be a list of entity names, not file names (or paths).
To compile to disk and also load into memory the source files we can use the Logtalk built-in predicate <atitle="Consult reference manual"href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a>:
Both predicates expect an entity name or a list of entity names (atoms) as an argument. The Logtalk source file name extension, as defined in the configuration file, should be omitted.
If you have more than a few source files then you may want to use a loader utility file containing the calls to the <code>logtalk_load/1</code> predicate (see the description above). Consulting or compiling the loader file will then compile and load all your Logtalk entities into memory.
The <atitle="Consult reference manual"href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> and <atitle="Consult reference manual"href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a> always use the set of default compiler option flags specified in the Logtalk configuration files. Although the default options cover the usual cases, you may want to use a different set of options while compiling or loading some of your Logtalk source files. This can be accomplished by using the <atitle="Consult reference manual"href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <atitle="Consult reference manual"href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates. These two predicates accept a list of options affecting how a Logtalk source file is compiled and loaded:
In fact, the <code>logtalk_load/1</code> and <code>logtalk_compile/1</code> predicates are just shortcuts to the extended versions called with the default compiler options.
<dd>Controls the unknown entity warnings, resulting from loading an entity that references some other entity that is not currently loaded. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>.</dd>
<dd>Controls the singleton variable warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code> (not recommended unless you have already checked your code and want to avoid false singletons warnings like some Prolog compilers report for variables that start with an underscore).</dd>
</dl>
<dl>
<dt><code>misspelt(Option)</code></dt>
<dd>Controls the misspelt calls warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code> (not recommended).</dd>
</dl>
<dl>
<dt><code>lgtredef(Option)</code></dt>
<dd>Controls the Logtalk built-in predicates redefinition warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>.</dd>
</dl>
<dl>
<dt><code>plredef(Option)</code></dt>
<dd>Controls the Prolog built-in predicates redefinition warnings. Possible option values are <code>warning</code> (can be very verbose if your code redefines a lot of Prolog built-in predicates) and <code>silent</code> (the usual default).</dd>
<dd>Controls the calling of non-ISO defined built-in predicates warnings. Possible option values are <code>warning</code> and <code>silent</code> (the usual default).</dd>
<dd>Controls the automatic generation of documenting files in XML format. Possible option values are <code>on</code> (the usual default) and <code>off</code>.</dd>
<dd>Sets the DOCTYPE reference in the automatically generated XML documenting files. The default value is <code>local</code>, that is, the DOCTYPE reference points to a local DTD file (<code>logtalk.dtd</code>). Other possible values are <code>web</code> (DOCTYPE reference points to the web location <code>http://www.logtalk.org/xml/1.0/logtalk.dtd</code>) and <code>standalone</code> (no DOCTYPE reference in the XML documenting files).</dd>
<dd>Controls reporting of each compiled or loaded object, category, or protocol (including compilation and loading warnings). Possible option values are <code>on</code> (the usual default) and <code>off</code> (silent compilation and loading).</dd>
<dd>Controls the use of the <code>initialization/1</code> directive in the Logtalk generated Prolog code. Possible option values are <code>true</code> (if the Prolog compiler supports the ISO definition of the directive) and <code>false</code> (if the Prolog compiler either does not implement the directive or if the implementation does not conform to the ISO standard).</dd>
<dd>Controls the use of smart compilation of source files to avoid recompiling files that are unchanged since the last time they are compiled. Possible option values are <code>on</code> and <code>off</code> (the usual default).</dd>
<dd>Toggles the interpretation of variables that start with an underscore as named anonymous variables. Possible option values are <code>on</code> and <code>off</code> (the usual default).</dd>
</dl>
<dl>
<dt><code>code_prefix(Option)</code></dt>
<dd>Enables the definition of prefix for all functors of Logtalk generated Prolog code. Option value must be an atom. Default value is ''.</dd>
We may also change the default options values from the ones loaded from the config file by using the <atitle="Consult reference manual"href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> built-in predicate. For example:
The current values of the default flags can be enumerated using the <atitle="Consult reference manual"href="../refman/builtins/current_logtalk_flag2.html"><code>current_logtalk_flag/2</code></a> built-in predicate:
<h3><aclass="back"title="Return to index"name="smart"href="index.html#installing_smart">Smart compilation of source files</a></h3>
<p>
If the Prolog compiler that you are using supports retrieving of file modification dates, then you can turn on smart compilation of source files to avoid recompiling files that have not been modified since last compilation.
</p>
<p>
Smart compilation of source files is usually off by default. You can turn it on by changing the default flag value in the configuration file, by using the corresponding compiler option with the compiling and loading built-in predicates, or, for the remaining of a working session, by using the call:
Some caveats that you should be aware. First, some warnings that might be produced when compiling a source file will not show up if the corresponding object file is up-to-date because the source file is not being (re)compiled. Second, if you are using several Prolog compilers with Logtalk, be sure to perform the first compilation of your source files with smart compilation turned off: the intermediate Prolog files generated by the Logtalk preprocessor may be not compatible across Prolog compilers or even for the same Prolog compiler across operating systems (due to different end-of-line characters).
<h2><aclass="back"title="Return to index"name="batch"href="index.html#installing_batch">Using Logtalk for batch processing</a></h2>
<p>
If you use Logtalk for batch processing, you probably want to supress most, if not all, banners, messages, and warnings that are normally printed by the system.
To supress printing of the Logtalk startup banner and default flags, turn off the option <code>startup_message</code> in the config file that you are using.
To supress printing of compiling and loading messages (including compiling warnings but not error messages), turn off the option <code>report</code> in the used config file.
