Installing and running Logtalk

Installing Logtalk

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.

Mac OS 8.x, 9.x

The Macintosh version is included in the file lgt2xx.sea.bin, a MacBinary encoded, self-extracting archive. Your web browser should automatically decode the file, giving you a .sea self-extracting archive that you double-click to install Logtalk. If not, drag and drop the .bin file in a utility like StuffIt Expander or MacBinaryII+.

MacOS X, BSD, Linux, Unix

The MacOS X/BSD/Linux/Unix version is included in the file lgt2xx.tar.gz. In order to decompress and install the system you may use the following commands:

    % gunzip lgt2xx.tar.gz
    % tar -xvf lgt2xx.tar

This will create a sub-directory named lgt2xx in your current directory.

OS/2, Windows 95/98/NT/ME/2000

The OS/2 and Windows 95/98/NT/ME/2000 version is included in the file lgt2xx.zip. The file can be decompressed using an utility like unzip:

    unzip lgt2xx.zip

Other operating systems

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.

Directories and files organization

In the Logtalk installation directory, you will find the following files and directories:

LICENSE - Logtalk user license

QUICK_START - Quick start instructions for those that do not like to read manuals

README - several useful information

RELEASE_NOTES - release notes for this version

UPGRADING - instructions in how to upgrade your programs to the current Logtalk version

compiler

NOTES - notes on the current status of the compiler

... - compiler source files

configs

NOTES - notes on the provided configuration files

template.config - template configuration file

... - specific configuration files

examples

NOTES - short description of the provided examples

bricks

NOTES - example description and other notes

SCRIPT - step by step example tutorial

bricks.loader - loader utility file for the example objects

... - bricks example source files

... - other examples

library

NOTES - short description of the library contents

all.loader - loader utility file for all library entities

... - library source files

manuals

NOTES - notes on the provided documentation

bibliography.html - bibliography

glossary.html - glossary

index.html - root document for all documentation

... - other documentation files

wenv

NOTES - notes on the text editors syntax configuration files providing syntax coloring for editing Logtalk source files

... - syntax configuration files

xml

NOTES - notes on the automatic generation of XML documentation files

logtalk.css - cascade style sheet file for the HTML output of the XSLT conversion of the XML files

logtalk.dtd - Document Type Description file describing the structure of the XML files

lgthtml.xsl - transformation style sheet to output HTML code from the XML files

... - other XML related files

Configuration files

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 template.config file.

Since most Prolog compilers are moving closer to the ISO Prolog standard [ISO 95], it is advisable that you try to use a recent version of your Prolog compiler of choice.

Logtalk compiler and runtime

The compiler 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.

Library

Starting from version 2.7, Logtalk contains a standard library of useful objects, categories, and protocols. Read the corresponding NOTES file for details about the library contents.

Examples

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 SCRIPT that contains cases of simple utilization. Some examples may depend on other examples and library objects to work properly. Read the corresponding NOTES file for details before running an example.

Logtalk source files

Each Logtalk entity (object, category or protocol) is contained in a text file named after the entity. The extension .lgt is normally used. The Logtalk preprocessor compiles these files to plain Prolog, replacing the .lgt extension with .pl (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.

Loader utility files

Most examples directories contain a Prolog utility file that can be used to load all included source files. These loader utility files are named <dir name>.loader and should be consulted like any ordinary Prolog file.

Usually these files contain a call to the Logtalk built-in predicates logtalk_load/1 or logtalk_load/2, wrapped inside an initialization/1 directive (to ensure ISO compatiblity). For instance, if your code is split in three Logtalk source files named source1.lgt, source2.lgt, and source3.lgt, then the contents of your loader file will be:

    :- initialization(
        logtalk_load([
            source1,
            source2,
            source3])).

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 set the working directory 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.

Running a Logtalk session

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.

Starting Logtalk

To start a Logtalk session just:

Start Prolog.
Load the appropriate configuration file for your compiler. Configuration files for most common Prolog compilers can be found in the configs subdirectory.
Load the Logtalk compiler/preprocessor and runtime files contained in the compiler subdirectory.

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 lgt_load_prolog_code/1 in the corresponding configuration file.

Compiling and loading your programs

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 logtalk_compile/1:

    | ?- logtalk_compile([source_file1, source_file2, ...]).

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 logtalk_load/1:

    | ?- logtalk_load([source_file1, source_file2, ...]).

This predicate works in the same way of the predicate logtalk_compile/1 but also loads the compiled files to memory.

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 logtalk_load/1 predicate (see the description above). Consulting or compiling the loader file will then compile and load all your Logtalk entities into memory.

Compiler option flags

The logtalk_load/1 and logtalk_compile/1 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 logtalk_load/2 or the logtalk_compile/2 built-in predicates. These two predicates accept a list of options affecting how a Logtalk source file is compiled and loaded:

    | ?- logtalk_compile(Files, Options).

or:

    | ?- logtalk_load(Files, Options).

In fact, the logtalk_load/1 and logtalk_compile/1 predicates are just shortcuts to the extended versions called with the default compiler options.

You can use the following options:

unknown(Option): Controls the unknown entity warnings, resulting from loading an entity that references some other entity that is not currently loaded. Possible option values are warning (the usual default) and silent.

singletons(Option): Controls the singleton variable warnings. Possible option values are warning (the usual default) and silent (not recommended).

underscore_vars(Option): 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 dont_care and singletons (the usual default). Note that, depending on your Prolog compiler, the read_term/3 built-in predicate may report variables that start with an underscore as singleton variables. There is no standard behavior, hence this option.

misspelt(Option): Controls the misspelt calls warnings. Possible option values are warning (the usual default) and silent (not recommended).

lgtredef(Option): Controls the Logtalk built-in predicates redefinition warnings. Possible option values are warning (the usual default) and silent.

plredef(Option): Controls the Prolog built-in predicates redefinition warnings. Possible option values are warning (can be very verbose if your code redefines a lot of Prolog built-in predicates) and silent (the usual default).

portability(Option): Controls the calling of non-ISO defined built-in predicates warnings. Possible option values are warning and silent (the usual default).

xml(Option): Controls the automatic generation of documenting files in XML format. Possible option values are on (the usual default) and off.

xmlspec(Option): Defines the XML documenting files specification format. Possible option values are dtd (for the DTD specification; the usual default) and xsd (for the XML Schema specification).

doctype(Option): Sets the DOCTYPE reference in the automatically generated XML documenting files. The default value is local, that is, the DOCTYPE reference points to a local DTD or XSD file (respectively, logtalk.dtd or logtalk.xsd), residing in the same directory as the XML file. Other possible values are web (DOCTYPE reference points to an web location, either http://www.logtalk.org/xml/1.0/logtalk.dtd or http://www.logtalk.org/xml/1.0/logtalk.xsd) and standalone (no DOCTYPE reference in the XML documenting files).

xsl(File): Sets the XSLT file to be used with the automatically generated XML documenting files. The default value is lgtxml.xsl.

report(Option): Controls reporting of each compiled or loaded object, category, or protocol (including compilation and loading warnings). Possible option values are on (the usual default) and off (silent compilation and loading).

iso_initialization_dir(Option): Controls the use of the initialization/1 directive in the Logtalk generated Prolog code. Possible option values are true (if the Prolog compiler supports the ISO definition of the directive) and false (if the Prolog compiler either does not implement the directive or if the implementation does not conform to the ISO standard).

smart_compilation(Option): 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 on and off (the usual default).

code_prefix(Option): Enables the definition of prefix for all functors of Logtalk generated Prolog code. Option value must be an atom. Default value is ''.

We may also change the default options values from the ones loaded from the config file by using the set_logtalk_flag/2 built-in predicate. For example:

    | ?- set_logtalk_flag(xml, off).

The current values of the default flags can be enumerated using the current_logtalk_flag/2 built-in predicate:

    | ?- current_logtalk_flag(xml, Value).

    Value = off
    yes

Smart compilation of source files

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.

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:

    | ?- set_logtalk_flag(smart_compilation, on).

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).

Using Logtalk for batch processing

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 startup_message 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 report in the used config file.

previous | glossary | next