3ba8483607
git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@1032 b08c6af1-5177-4d33-ba66-4b1c6b8b522a
349 lines
21 KiB
HTML
349 lines
21 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<?xml-stylesheet type="text/css" href="../styles.css" ?>
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
|
|
<title>Logtalk user manual: installing and running Logtalk</title>
|
|
<link rel="stylesheet" href="../styles.css" type="text/css" />
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="navtop">
|
|
<a href="../index.html">contents</a> > <a href="index.html">user manual</a>
|
|
</div>
|
|
|
|
<h1>Installing and running Logtalk</h1>
|
|
|
|
<h2>Installing Logtalk<a name="installing"></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. Users wishing to use the Logtalk library and Logtalk examples will need write access to the respective directories.
|
|
</p>
|
|
|
|
<h4>Mac OS 8.x, 9.x</h4>
|
|
|
|
<p>
|
|
The Macintosh version is included in the file <code>lgt2xxx.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>.
|
|
</p>
|
|
|
|
<h4>MacOS X, BSD, Linux, Unix</h4>
|
|
|
|
<p>
|
|
The MacOS X/BSD/Linux/Unix version is included in the file <code>lgt2xxx.tar.gz</code>. In order to decompress and install the system you may use the following commands:
|
|
</p>
|
|
<pre>
|
|
% gunzip lgt2xxx.tar.gz
|
|
% tar -xvf lgt2xxx.tar
|
|
</pre>
|
|
<p>
|
|
This will create a sub-directory named <code>lgt2xxx</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>lgt2xxx.zip</code>. The file can be decompressed using an utility like <code>unzip</code>:
|
|
</p>
|
|
<pre>
|
|
unzip lgt2xxx.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>Directories and files organization<a name="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>template.config</code> - template configuration file</dd>
|
|
<dd><code>...</code> - specific configuration files</dd>
|
|
<dt><code>examples</code></dt>
|
|
<dd><code>NOTES</code> - short description of the provided examples</dd>
|
|
<dd><code>bricks</code></dd>
|
|
<dd><dl>
|
|
<dd><code>NOTES</code> - example description and other notes</dd>
|
|
<dd><code>SCRIPT</code> - step by step example tutorial</dd>
|
|
<dd><code>bricks.loader</code> - loader utility file for the example objects</dd>
|
|
<dd><code>...</code> - bricks example source files</dd>
|
|
</dl></dd>
|
|
<dd><code>...</code> - other examples</dd>
|
|
<dt><code>library</code></dt>
|
|
<dd><code>NOTES</code> - short description of the library contents</dd>
|
|
<dd><code>all.loader</code> - loader utility file for all library entities</dd>
|
|
<dd><code>...</code> - library source files</dd>
|
|
<dt><code>manuals</code></dt>
|
|
<dd><code>NOTES</code> - notes on the provided documentation</dd>
|
|
<dd><code>bibliography.html</code> - bibliography</dd>
|
|
<dd><code>glossary.html</code> - glossary</dd>
|
|
<dd><code>index.html</code> - root document for all documentation</dd>
|
|
<dd><code>...</code> - other documentation files</dd>
|
|
<dt><code>wenv</code></dt>
|
|
<dd><code>NOTES</code> - notes on the text editors syntax configuration files providing syntax coloring for editing Logtalk source files</dd>
|
|
<dd><code>...</code> - syntax configuration files</dd>
|
|
<dt><code>xml</code></dt>
|
|
<dd><code>NOTES</code> - notes on the automatic generation of XML documentation files</dd>
|
|
<dd><code>logtalk.css</code> - cascade style sheet file for the HTML output of the XSLT conversion of the XML files</dd>
|
|
<dd><code>logtalk.dtd</code> - Document Type Description file describing the structure of the XML files</dd>
|
|
<dd><code>lgthtml.xsl</code> - transformation style sheet to output HTML code from the XML files</dd>
|
|
<dd><code>...</code> - other XML related files</dd>
|
|
</dl>
|
|
|
|
<h3>Configuration files<a name="configs"></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 <a href="../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>Logtalk compiler and runtime<a name="compiler"></a></h3>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Library<a name="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>Examples<a name="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>Logtalk source files<a name="entities"></a></h3>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Loader utility files<a name="loaders"></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 <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> or <a title="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>
|
|
|
|
<h2>Running a Logtalk session<a name="running"></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>Starting Logtalk<a name="starting"></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>
|
|
<li>Load the Logtalk compiler/preprocessor and runtime files contained in the <code>compiler</code> subdirectory.</li>
|
|
</ol>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Compiling and loading your programs<a name="compiling"></a></h3>
|
|
|
|
<p>
|
|
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
|
|
<a title="Consult reference manual" href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a>:
|
|
</p>
|
|
<pre>
|
|
| ?- logtalk_compile([source_file1, source_file2, ...]).
|
|
</pre>
|
|
<p>
|
|
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).
|
|
</p>
|
|
<p>
|
|
To compile to disk and also load into memory the source files we can use the Logtalk built-in predicate <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a>:
|
|
</p>
|
|
<pre>
|
|
| ?- logtalk_load([source_file1, source_file2, ...]).
|
|
</pre>
|
|
<p>
|
|
This predicate works in the same way of the predicate <code>logtalk_compile/1</code> but also loads the compiled files to memory.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3>Compiler option flags<a name="options"></a></h3>
|
|
|
|
<p>
|
|
The <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> and <a title="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 <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="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:
|
|
</p>
|
|
<pre>
|
|
| ?- logtalk_compile(Files, Options).
|
|
</pre>
|
|
<p>
|
|
or:
|
|
</p>
|
|
<pre>
|
|
| ?- logtalk_load(Files, Options).
|
|
</pre>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
You can use the following options:
|
|
</p>
|
|
<dl>
|
|
<dt><code>unknown(Option)</code></dt>
|
|
<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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>singletons(Option)</code></dt>
|
|
<dd>Controls the singleton variable warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code> (not recommended).</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>underscore_vars(Option)</code></dt>
|
|
<dd>Controls the interpretation of variables that start with an underscore (excluding the anonymous variable) that occur once in a term as either don't care variables or singleton variables. Possible option values are <code>dont_care</code> and <code>singletons</code> (the usual default). Note that, depending on your Prolog compiler, the <code>read_term/3</code> built-in predicate may report variables that start with an underscore as singleton variables. There is no standard behavior, hence this option.</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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>portability(Option)</code></dt>
|
|
<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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>xml(Option)</code></dt>
|
|
<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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>xmlspec(Option)</code></dt>
|
|
<dd>Defines the XML documenting files specification format. Possible option values are <code>dtd</code> (for the DTD specification; the usual default) and <code>xsd</code> (for the XML Schema specification).</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>doctype(Option)</code></dt>
|
|
<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 or XSD file (respectively, <code>logtalk.dtd</code> or <code>logtalk.xsd</code>), residing in the same directory as the XML file. Other possible values are <code>web</code> (DOCTYPE reference points to an web location, either <code>http://www.logtalk.org/xml/1.0/logtalk.dtd</code> or <code>http://www.logtalk.org/xml/1.0/logtalk.xsd</code>) and <code>standalone</code> (no DOCTYPE reference in the XML documenting files).</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>xsl(File)</code></dt>
|
|
<dd>Sets the XSLT file to be used with the automatically generated XML documenting files. The default value is <code>lgtxml.xsl</code>.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>report(Option)</code></dt>
|
|
<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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>iso_initialization_dir(Option)</code></dt>
|
|
<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>
|
|
</dl>
|
|
<dl>
|
|
<dt><code>smart_compilation(Option)</code></dt>
|
|
<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>
|
|
</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>
|
|
</dl>
|
|
|
|
<p>
|
|
We may also change the default options values from the ones loaded from the config file by using the <a title="Consult reference manual" href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> built-in predicate. For example:
|
|
</p>
|
|
<pre>
|
|
| ?- set_logtalk_flag(xml, off).
|
|
</pre>
|
|
<p>
|
|
The current values of the default flags can be enumerated using the <a title="Consult reference manual" href="../refman/builtins/current_logtalk_flag2.html"><code>current_logtalk_flag/2</code></a> built-in predicate:
|
|
</p>
|
|
<pre>
|
|
| ?- current_logtalk_flag(xml, Value).
|
|
|
|
Value = off
|
|
yes
|
|
</pre>
|
|
|
|
<h3>Smart compilation of source files<a name="smart"></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:
|
|
</p>
|
|
<pre>
|
|
| ?- set_logtalk_flag(smart_compilation, on).
|
|
</pre>
|
|
<p>
|
|
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).
|
|
</p>
|
|
|
|
<h2>Using Logtalk for batch processing<a name="batch"></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.
|
|
</p>
|
|
<p>
|
|
To supress printing of the Logtalk startup banner and default flags, set the option <code>startup_message</code> in the config file that you are using to <code>none</code>.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<div class="navbottom">
|
|
<a href="configuration.html">previous</a> | <a href="../glossary.html">glossary</a> | <a href="programming.html">next</a>
|
|
</div>
|
|
|
|
<div class="copyright">
|
|
Copyright © <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> — <a href="http://www.logtalk.org">Logtalk.org</a>
|
|
</div>
|
|
|
|
<div class="footer">
|
|
<p><span class="bleft"><a href="http://validator.w3.org/check/referer">XHTML</a> + <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a></span><span class="bright">Last updated on: March 29, 2004</span></p>
|
|
</div>
|
|
</body>
|
|
</html>
|