root/trunk/configs/NOTES.txt

================================================================
Logtalk - Open source object-oriented logic programming language
Release 2.33.3

Copyright (c) 1998-2008 Paulo Moura.        All Rights Reserved.
Logtalk is free software.  You can redistribute it and/or modify
it under the terms of the "Artistic License 2.0" as published by 
The Perl Foundation. Consult the "LICENSE.txt" file for details.
================================================================


This file contains some notes about the config files provided. If you
improve or correct some of these files, or write new ones for other
Prolog compilers, please send me a copy. It is impossible for me to 
individually test Logtalk under all combinations of compatible Prolog 
versions and operating-system versions (or, for that mater, to own a 
copy of each one of these compilers). For some of these Prolog compilers 
I only have the manuals available on-line.

As a general rule, always try to use the latest version of your Prolog 
compiler of choice. For Prolog compilers with long release cycles, this 
may imply use of development versions. Most Prolog compilers are moving 
towards better ISO Standard compatibility and, as a consequence, improved 
Logtalk compatibility.

Most of the suggestions you will find in this file for integrating Logtalk 
with specific Prolog compilers are already implemented and available in the 
"integration" directory of the Logtalk distribution.


template config file

    template.config

    If a config file for your favorite Prolog is not available, use this 
    file as a template for writing one. For each predicate in the file, 
    check if it is built-in in your Prolog, available in a library, or if 
    you can write a better definition.


ALS Prolog 3.1

    als.config

    Only a few tests have been done with this compiler. One known problem: an
    ALS bug in operator handling that make calls like "\+ ::Pred" be 
    interpreted like "::(\+ Pred)" instead of "\+ (::Pred)". A workaround is 
    to replace all occurrences of "\+ ::Pred" by "\+ (::Pred)" and all 
    occurrences of "\+ Obj::Pred" by "\+ (Obj::Pred)". Please report any other 
    problems that you might find. Don't forget to use the cd/1 predicate to 
    set the working directory before loading the library or an example. Consult 
    the file builtins/comp_d10.pro in the ALS Prolog installation directory in 
    order to get the definition of predicate numbervars/3 needed by the Logtalk 
    built-in debugger. Supports smart compilation of source files. Does not 
    support the "altdirs" compiler flag.


Amzi! Prolog 7.6.1 and later versions

    amzi.config

    For Amzi! Prolog 7.6.1 and later versions. You need to patch the Logtalk 
    compiler (the "compiler/logtalk.pl" file) by searching for all calls of 
    ':'/2 and wrap them inside call/1. For better performance, use the Amzi! 
    "acmp" command-line compiler to compile the files "configs/amzi.config",
    "compiler/logtalk.pl", and "libpaths/libpaths.pl" and then load the 
    resulting ".plm" files using the predicate load/1 (you will need first 
    to change the extension of the config file to either ".pl" or ".pro" and 
    to edit the "libpaths.pl" file by following the instructions on the 
    "libpaths/NOTES.txt" file).
    
    One potential problem is that the compiler definition of the compare/3 
    built-in predicate returns the atom == instead of = for identical terms 
    (contrary to every other Prolog compiler!). Search the library files for 
    all calls of the compare/3 predicate and make the necessary changes.
    The built-in sort/2 predicate does not eliminate duplicates, which may 
    result in problems with some of the examples. Don't forget to use the 
    chdir/1 predicate to set the working directory before loading a library 
    or an example.


B-Prolog 7.1 and later versions

    b.config

    For B-Prolog 7.1 and later versions. Don't forget to use the chdir/1 
    predicate to set the working directory before loading the library or 
    an example. Note that this configuration file redefines the B-Prolog 
    ::/2 finite-domain built-in predicate (you may use the alternative 
    in/2 predicate instead).

    Some of the B-Prolog built-in predicates (e.g. set_to_list/2 or (@=)/2) 
    are not core predicates and can be redefined by the user. The predicate 
    predicate_property/2 does not return the property "built_in" for these 
    predicates. The solution is to encapsulate calls to these predicates 
    within objects and categories using the Logtalk {}/1 control construct.

    You can generate a new Prolog top level that includes the config file, the
    Logtalk compiler/runtime, and the library paths file by doing something 
    like:

        | ?- set_prolog_flag(redefined, off).

        | ?- compile(['configs/b.config', 'compiler/logtalk.pl', 'libpaths/libpaths.pl']).
    
    These calls will result in the creation of three files, "b.config.out", 
    "logtalk.out", and "libpaths.out". Place these files on the $BPDIR 
    directory and then copy the "bp" script to a "bplgt" file and modify it 
    by adding the names of the three *.out files after the "$BPDIR/bp.out" 
    file (prefixing them with $BPDIR/). You will probably need to increase 
    the sizes of the code areas on the "bplgt" script if you run into 
    out-of-memory errors with complex applications.


Bin-Prolog 8.x~10.x

    bin.config

    Start BinProlog using "bp -l4". You will need to create project files to 
    workaround the restriction of only one top-level file per interactive 
    session. For instance, the project file for the "metapredicates" example
    will look like (in the Unix version):
    
        :- ['$LOGTALKUSER/configs/bin.config'].
        :- ['$LOGTALKHOME/compiler/logtalk.pl'].
        
        :- ['$LOGTALKUSER/examples/metapredicates/meta.pl'].
        :- ['$LOGTALKUSER/examples/metapredicates/sort1.pl'].
        ...
    
    You will probably want to have a project file including only the config
    and the pre-processor/runtime files (logtalk.pl) in order to compile the
    examples using logtalk_compile/1-2 (do NOT use logtalk_load/1-2 or the 
    provided loader files). Don't forget to call the cd/1 predicate to set 
    the working directory before compiling the library or an example. 
    Supports smart compilation of source files.

    Updated and tested with help of Arun Majumdar.


CIAO Prolog 1.8p2 and later versions

    ciao.config
    ciao_aux.config

    The "ciao.config" file is just a loader file containing two include/1 
    directives which load the "ciao_aux.config" and the Logtalk compiler/
    runtime. You must edit the contents of the file ciao.config to match 
    your operating system (the include directive arguments are file paths 
    that differ between operating systems).

    The definition of the predicate '$lgt_predicate_property'/2 in the file 
    "ciao_aux.config" is a bit of a hack, but should enable you to run the 
    Logtalk companion examples and to try out your own Logtalk programs. 

    You need to patch the Logtalk compiler (compiler/logtalk.pl) and comment
    out the multifile declaration for the predicate logtalk_library_path/2 
    in order to use library notation for loading library and example files.

    Don't forget to call the cd/1 predicate to set the working directory 
    before compiling the library or an example (you will need first to 
    load the library system that exports the cd/1 predicate by calling the 
    goal use_module(library(system)). Supports smart compilation of source 
    files.


CxProlog 0.97.2 or later versions

    cx.config

    Developed and tested with the help of the CxProlog author, Artur Miguel
    Dias.


ECLiPSe 5.10#26 or later versions

    eclipse5.config
    eclipse5iso.config

    There are two configs files for this compiler. The first one, named 
    "eclipse5.config", should be used when, for some reason, you don't want 
    to load the "iso" library. The second file, "eclipse5iso.config" contains 
    a call to load the "iso" library. Both config files may be used with
    ECLiPSe 5.10#26 or later versions.

    You should use the "eclipse5iso.config" config file whenever possible.
    The "eclipse5.config" config file may not contain all the necessary 
    definitions for ISO Prolog predicates that are needed for compiling 
    Logtalk itself, the Logtalk library, or the Logtalk examples. On the 
    other hand, some of the ECLiPSE features (e.g. array notation) are not 
    available when using the "iso" library.

    There is a clash between Logtalk and ECLiPSe regarding the ::/2 operator.
    You may still use the ::/2 operator defined on the ECLiPSe constraint 
    solver libraries by using explicit module qualification by writing 
    "{library:(Var::Domain)}" (replace "library" by the actual library name; 
    the {}/1 control construct allows you to bypass the Logtalk compiler).

    For improved performance, add the following calls to the top of all the 
    files in the "compiler" sub-directory:
    
        :- pragma(system).
        :- pragma(nodebug).

    These calls disables debugging support for the Logtalk compiler/runtime 
    Prolog code and mark the Logtalk predicates as built-ins. Make sure that 
    the library top-level is loaded if you want to use the Logtalk built-in 
    debugger.

    Adopted from a config file written and tested with help of Taner Bilgic 
    for Logtalk 1.x. Don't forget to use the cd/1 predicate to set the working 
    directory before loading the library or an example. Supports smart 
    compilation of source files.

    With this Prolog compiler, avoid reloading Logtalk source files declaring 
    and defining dynamic predicates. Due to the semantics of the ECLiPSe 
    built-in predicate compile/1, new clauses for dynamic predicates are 
    appended to the old ones instead of replacing them.


ECLiPSe 6.0#37 or later versions

    eclipse6.config
    eclipse6iso.config

    (see comments above about ECLiPSe 5.10 version)


GNU Prolog 1.3.0 and later versions

    gnu.config

    GNU Prolog supports the ISO Prolog standard. No problems expected. You 
    can generate a new Prolog top level that includes the config file and 
    the Logtalk compiler/runtime by doing something like:

        % cd $LOGTALKHOME
        % mv configs/gnu.config configs/gnu.pl

    Edit the compiler/logtalk.pl file and add the line ":- built_in." to 
    the top. Then:

        % gplc -o logtalk configs/gnu.pl compiler/logtalk.pl
        % mv logtalk /usr/local/bin/

    This way, every time you want to work with Logtalk you will just need 
    to type:

        % logtalk

    Don't forget to use the change_directory/1 predicate to set the working 
    directory before loading the library or an example. Supports smart 
    compilation of source files.

    On startup, you may get a warning about a suspicious predicate, {}/1.
    You may safely ignore this warning. Warnings may also be printed 
    regarding multifile directives. You can also safely ignore these 
    warnings.


IF/Prolog 5.1 and later versions

    if.config

    IF/Prolog 5.1 supports the ISO Prolog standard. No problems expected.
    Don't forget to use the cd/1 predicate to set the working directory 
    before loading the library or an example. Supports smart compilation 
    of source files. Does not support the "altdirs" compiler flag.


JIProlog 3.0.2-6 and later versions

    ji.config

    Written with the help of the JIProlog author (but if you find any Logtalk 
    problem please report it to me). Don't forget to use the cd/1 predicate to 
    set the working directory before loading the library or an example. Some 
    examples may not compile or run due to work in progress regarding ISO 
    Prolog standard compliance. Supports smart compilation of source files.


K-Prolog 5.1.2a and and later 5.1.x versions

    k5.config

    K-Prolog 5.1.2a supports the ISO Prolog standard. No problems expected. 
    Config file written and tested with the help of Nobukuni Kino. Don't 
    forget to use the cd/1 predicate to set the working directory before 
    loading the library or an example. Supports smart compilation of source 
    files.


K-Prolog 6.0.4 and later versions

    k6.config

    K-Prolog 6.0.4 supports the current ISO Prolog standard and features 
    from the draft core revision proposal. Don't forget to use the cd/1 
    predicate to set the working directory before loading the library or 
    an example. Supports smart compilation of source files.


LPA MacProlog32 1.25

    lpamac.config

    This is my old Prolog development environment. Two known problems: (1) an
    LPA bug in operator handling that make calls like "\+ ::Pred" be 
    interpreted like "::(\+ Pred)" instead of "\+ (::Pred)". A workaround is 
    to replace all occurrences of "\+ ::Pred" by "\+ (::Pred)"; (2) If you call 
    the \+ operator in your code the writeq/1 built-in don't always output a 
    space after the operator resulting in calls like "\+(...)". Because \+ is 
    not defined as a predicate this will fail. Don't forget to use the dvol/1 
    predicate to set the working directory before loading an example.
    Due to the size of the Logtalk pre-processor file, you must load it by 
    using the consult/1 predicate instead of using the File:Open menu option.
    Be aware that this configuration file redefines some built-ins that
    you may use in your own programs. You must be careful to not consult the 
    config file twice. Supports smart compilation of source files. Does not 
    support the "altdirs" compiler flag.


LPA WinProlog32 4.0x

    lpawin.config

    Written with the help of the LPA support team. Of course, if you find any 
    bugs please direct your flames to me ;-). Be aware that this configuration 
    file redefines some built-ins that you may use in your programs. Don't 
    forget to use the chdir/1 predicate to set the working directory before 
    loading the library or an example. Be careful to not consult the config 
    file twice. Supports smart compilation of source files. Does not support 
    the "altdirs" compiler flag.


MasterProlog 4.1

    master.config

    Written with the help of the MasterProlog support team (but if you find 
    any Logtalk problem please report it to me). 
    If in the MasterProlog version that you are using the implementation of 
    the close/1 predicate does not follow the ISO standard, you will have to 
    apply the following patch to the Logtalk pre-processor: replace every 
    call of close(...) with fclose(...).  Does not support the "altdirs" 
    compiler flag.


Open Prolog 1.1b5

    open.config

    Limited test done. Please report any problems that you may find.
    Don't forget to use the set_folder/1 predicate to set the working 
    directory before loading the library or an example. Does not support 
    the "altdirs" compiler flag.


PrologII+ 4.5 and later versions

    prologII.config

    Written and tested with the help of Claude Lai from PrologIA. You need
    to apply the following patches to the Logtalk pre-processor/runtime:
    Search and replace every instance of "quoted(true)" with "quoted(:true)";
    "open(File, write, Stream)" with "open(File, :write, Stream)",
    "catch(close(Stream), _, true)" with "catch(close(Stream), _, :true)",
    "open(File, read, Stream)" with "open(File, :read, Stream, [eof_action(eof_code)])".
    Remember that you need to use the set_import_dir/1 built-in predicate to
    set the working directory before loading the library or an example.
    Does not support the "altdirs" compiler flag.


Qu-Prolog 8.1 and later versions

    qu.config

    In order to compile and load both the config file and the Logtalk compiler,
    the following sequence of steps is advised. First make a copy of the config 
    file:

        % cd $LOGTALKHOME/configs; cp qu.config qu.ql

    Second, start Qu-Prolog using adequate switches. For example:

        % qp -T 16 -s 2048 -d 1024 -h 2000

    Third, compile and load the config file using:

        | ?- fcompile('qu.ql', [assemble_only(true)]), load(qu).

    Next, compile and load the Logtalk compiler:

        | ?- chdir('../compiler/'), fcompile('logtalk.pl', [assemble_only(true), string_table(256)]), load(logtalk).

    Finally, compile and load the library paths file:

        | ?- chdir('../libpaths/'), fcompile('libpaths.pl', [assemble_only(true)]), load(libpaths).

    Don't forget to use the chdir/1 predicate to set the working directory 
    before loading the library or an example.

    Written and tested with the help of Peter Robinson.


Quintus Prolog 3.3~3.5

    quintus.config

    Written and tested with help of a friend of mine, Paulo Urbano, for a 
    previous version. Adopted (but not tested) for the current release by
    using information available on-line in the internet. You need to patch 
    the Logtalk compiler due to the different argument order of the built-in 
    predicates read_term/3 and open/4: for all calls of both predicates, 
    exchange the last two arguments. Don't forget to use the unix(cd(Dir)) 
    predicate to set the working directory before loading the library or an 
    example. Supports smart compilation of source files.


SICStus Prolog 3.8~3.12.x

    sicstus3.config
    
    For versions 3.8.x~3.12.x. The config file sets the flag language to 
    iso, but that is only recommended and should not be needed to run Logtalk.
    No problems expected although not fully tested. Don't forget to use the 
    SICStus working_directory/2 predicate to set the working directory before 
    loading the library or an example. Supports smart compilation of source 
    files.

    If you want SICStus Prolog to automatically load Logtalk at startup, then 
    add the following lines to your ~/.sicstusrc or ~/.sicstus.ini initialization
    file:
    
        :- compile('$LOGTALKUSER/configs/sicstus3.config').
        :- compile('$LOGTALKHOME/compiler/logtalk.pl').
        :- compile('$LOGTALKUSER/libpaths/libpaths.pl').

    Consult the SICStus Prolog documentation for further information on the 
    ~/.sicstusrc and ~/.sicstus.ini user initialization files.


SICStus Prolog 4.0.x

    sicstus4.config

    Config file for the SICStus Prolog 4.0 version (tested with the MacOS X 
    version and the Windows beta version).


SWI Prolog 5.6.44 and later versions

    swi.config
    swihook.pl
    xpcehook.pl
    swi_set_logtalk_context.pl

    No problems expected. Please report any problem found (with a solution 
    if possible). Don't forget to use the cd/1 predicate to set the working 
    directory before loading the library or an example. Supports smart 
    compilation of source files. To improve the integration between Logtalk 
    and SWI-Prolog edit the compiler/logtalk.pl file and add the line 
    ":- system_module." to the top of the file. You may also load the file 
    configs/swihook.pl in order to be able to load Logtalk entities using 
    SWI-Prolog load_files/2 and consult/1 predicates.

    If you want SWI-Prolog to automatically load Logtalk at startup, then 
    add the following lines to your pl.ini (on Windows):

        :- ['drive:\\path to logtalk user folder\\configs\\swi.config'].
        :- ['drive:\\path to logtalk installation\\compiler\\logtalk.pl'].
        :- ['drive:\\path to logtalk installation\\libpaths\\libpaths.pl'].

     or to your .plrc (on MacOS X, Linux, Unix, and similar systems):
    
        :- ['$LOGTALKUSER/configs/swi.config'].
        :- ['$LOGTALKHOME/compiler/logtalk.pl'].
        :- ['$LOGTALKUSER/libpaths/libpaths.pl'].

    See the SWI-Prolog documentation for further information on the .plrc 
    and pl.ini user initialization files.

    The config file sets the "iso" SWI-Prolog flag to "true". This setting 
    may improve compatibility of Logtalk code across different back-end 
    Prolog compilers buy may also cause compatibility problems with some 
    SWI-Prolog libraries. Comment out the corresponding set_prolog_flag/2 
    call if necessary.

    If you intend to use Logtalk and XPCE at the same time, you may load the 
    configs/xpcehook.pl file in order to support Logtalk message sending goals 
    as XPCE call-back goals.

    See the comments in the "swi_set_logtalk_context.pl" file itself for a 
    description of its functionality.

    With multi-threading support turned on, you may get an harmless message
    when halting the system regarding threads that wouldn't die: you can 
    suppress the message on POSIX systems by using "% swilgt 2> /dev/null".


XSB 3.1 and later versions

    xsb.config

    Don't forget to use the cd/1 predicate to set the working directory 
    before loading the library or an example. Supports smart compilation 
    of source files. Support for the Logtalk multi-threading features 
    requires XSB CVS version.


YAP 5.1.3 and later versions

    yap.config

    Don't forget to use the cd/1 predicate to set the working directory 
    before loading the library or an example. Supports smart compilation 
    of source files. Support for the Logtalk multi-threading features 
    requires YAP CVS version.