root/trunk/UPGRADING.txt

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

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


Upgrading from Logtalk 1.x
==========================

Logtalk 2.x is not compatible with programs written for Logtalk 1.x.
However, you should be able to translate most programs to make them 
run under Logtalk 2.x. Most of the examples provided with Logtalk 1.x 
have been rewritten to run under Logtalk 2.x. You may use them as 
translation examples.


Upgrading from a previous Logtalk 2.x versions
==============================================

Changes in the Logtalk compiler between releases may render Prolog config 
files from older versions incompatible with new ones. You may need to update 
your local Logtalk user files by running e.g. the "cplgtdirs" shell script.

If your Logtalk programs depend on some of the example files, it is
advisable that you check your code against the new version before 
throwing away the older release.

Logtalk source files will need to be recompiled because of the changes 
done in the version 2.5.0 to improve message sending performance.

Logtalk version 2.7.0 provides the first cut of the Logtalk standard library.
Most examples have been rewritten to take advantage of the library.

Logtalk version 2.8.0 introduces a small change on the logtalk_compile/1-2 
and logtalk_load/1-2 predicates that may imply updating your loader utility
files: the first argument is now always a list of entities even if we want 
to compile or load a single entity.

Logtalk version 2.9.0 changes compiled code functors postfixes from "_sdcl" 
and "_sdef" to  "_idcl" and "_idef", implying recompilation of all objects, 
protocols, and categories.

Logtalk version 2.10.0 changes some of the semantics of object dynamic 
predicates. See the release notes for a description of the changes.

Logtalk version 2.14.4 removes the definition of the deprecated built-in 
predicate logtalk_version/3 (use current_logtalk_flag/3 instead).

Logtalk version 2.14.5 changes compiled code in order to correct a bug 
where sending messages such as true/0 to an unknown object will succeeded 
instead of throwing the expected exception, implying recompilation of all 
objects, protocols, and categories.

Logtalk version 2.14.7 changes compiled code in order to optimize the 
code generated by the compilation of dynamic predicate clauses.

Logtalk version 2.15.0 changes the "authors" key in  the directive info/1 to 
"author". All the XSLT, DTD, and XSD files have been update to conform to 
this change. If you use the directive info/1 in your programs, you will need 
to apply this change to take advantage of automatic generation of documenting 
files.

Logtalk version 2.15.3 changes the format of the runtime entity tables, 
implying recompilation of all objects, protocols, and categories.

Logtalk version 2.15.6 renamed the compiler flag "named_anonymous_vars" to 
"underscore_variables" and changed the possible option values form "on/off" to 
"dont_care/singletons".

Logtalk 2.16.0 improves support for the declaration and use of operators 
local to objects and categories. Recompilation of any objects and categories 
containing operator declarations is needed in order to take advantage of the 
improvements made.

Logtalk 2.16.1 now checks for attempts to redefined built-in Logtalk control 
constructs when compiling source files. These checks may generate compilation 
errors on files containing bugs that are not detected on previous versions of 
the compiler.

Logtalk version 2.16.2 changed the possible option values of the read-only 
compiler flag "startup_message" to "none", "banner", and "flags". Default 
value is "flags" (print both banner and default flag values).

Logtalk version 2.17.1 removes predicate nth/3 from library entities listp, 
list, and difflist (replaced by the predicates nth0/3 and nth1/3).

Logtalk version 2.20.0 updates the semantics of the uses/1 entity directive 
to accept as argument a single object identifier (this change is needed in 
order to ensure compatibility with the new uses/2 predicate directive).

Logtalk version 2.21.2 adds a new clause to the code generated when compiling 
entity in order to support the new alias/1 predicate property, implying 
recompilation of all objects, protocols, and categories.

Logtalk version 2.22.0 adds support for using the notation <library>(<file>) 
when compiling and loading source files. Logtalk applications using this new 
notation will need to be modified in order to run in previous Logtalk versions.
In addition, the exceptions generated by the predicates logtalk_compile/1-2 
and logtalk_load/1-2 have been updated to take into account this new feature. 

Logtalk version 2.22.2 adds stricter checking for the documenting directives 
(info/1 and info/2), which can lead to compilation errors on entities which 
compiled successfully on previous Logtalk versions.

Logtalk version 2.22.5 adds new predicates to all config files (consult the 
release notes for details). If you are using custom config files, be sure to 
update them by coping the definition of the new predicates.

Logtalk version 2.23.0 features new, optimized implementations of the database
built-in methods, implying the recompilation of all objects, protocols, and 
categories.

Logtalk version 2.25.0 drops support for source metafiles and .mlgt file name 
extension as this version features a new, file-based compiler supporting the 
definition of any number of entities in a single file. Older code using source 
metafiles will need to rename the file name extensions from .mlgt to .lgt.

Logtalk version 2.25.1 updates the compiler to generate XML documenting files 
whose names always contain the arity of the entity identifier appended at the 
end (using the format "_arity"). This change implied updates to the lgt2xml.* 
and lgt2html.* shell scripts which render them incompatible with the XML files 
generated by previous Logtalk versions.

Logtalk version 2.27.0 changes representation of declared predicates in order 
to support the new predicate property non_terminal/1, implying recompilation 
of all objects, protocols, and categories.

Logtalk version 2.27.1 optimizes the generation of predicate definition and 
declaration linking clauses, resulting in small performance improvements and 
in space savings for the Prolog code generated when compiling Logtalk entities.
Recompilation of all objects, protocols, and categories is necessary in order 
to take advantage of this optimizations.

Logtalk 2.28.0 changes representation of meta-predicates, implying the 
recompilation of all objects, protocols, and categories that define them.
In addition, in order to close some security holes where meta-predicates 
could be used to bypass predicate scope declarations, meta-predicates that 
use closures must be re-implemented to use the new call/N Logtalk built-in 
predicate. The directive metapredicate/1 is now deprecated, the directive 
meta_predicate/1 should be used instead. There are also changes to the 
config files that render the Logtalk runtime incompatible with the config 
files of previous versions.

Logtalk 2.29.0 makes some incompatible changes to the experimental support 
for multi-threading programming that may imply updating any application that 
uses the multi-threading predicates. The default value of the compiler flag 
events/1 is now off. Applications using event-driven programming must either 
turn this flag on or compile source files with the events(on) option. The 
library protocol "event_handlersp" is now deprecated; new code should use 
instead the built-in "monitoring" protocol. The new support for "threaded" 
and "synchronized" entity properties implies recompilation of all objects 
and categories.

Logtalk 2.29.2 removes the built-in predicate threaded_discard/1.

Logtalk 2.29.5 adds a new compiler option, "reload", whose default value is 
defined in the config files. This makes previous config files incompatible 
with this new Logtalk version.

Logtalk 2.30.0 adds two new compiler options, "xmldir" and "tmpdir", allowing 
a per-project definition of directories for storing XML documenting files and 
for storing intermediate compilation files (e.g. Prolog files). Removed from 
the config files the predicate '$lgt_alt_directory'/2. Older config files are 
incompatible with this new Logtalk version.

Logtalk 2.30.6 renamed the compiler flags "supports_break_predicate", 
"supports_encoding_dir", and "underscore_vars" to, respectively, 
"break_predicate", "encoding_directive", and "underscore_variables". Changed 
the possible values of the "encoding_directive" compiler option (see manual).
Older config files are not compatible with this new Logtalk version.

Logtalk 2.30.7 adds a new compiler flag "context_switching_calls".
Older config files are not compatible with this new Logtalk version.

Logtalk 2.31.0 changes the "imports" relation between categories to the 
relation "extends". The relation "imports" is now only used for objects 
importing categories. This version renames the predicate property "alias/1" 
to "alias_of/1" in order to disambiguate its meaning. This version also 
changes compiler hook support; you will need to update your code if you're 
using hook objects and hook predicates. Moreover, Logtalk source files will 
need to be recompiled because of the changes done in this version to improve 
updating runtime bookkeeping tables when loading new entities.

Logtalk 2.31.2 changes the valid values for the encoding/1 directive from 
the SWI-Prolog original values to atoms complying with the IANA standard. 
Old values are deprecated but still recognized for compatibility with older 
Logtalk releases (see the config files of YAP and SWI-Prolog).

Logtalk 2.31.3 changes the predicate used to load Prolog files, adding an 
additional argument that represents a list of load/compile options (notably,
encoding/1). Older config files are incompatible with this new Logtalk 
version.

Logtalk version 2.31.6 changes representation of loaded categories in order 
to correct a bug in the use of the :/1 control construct, therefore implying 
recompilation of all categories.

Logtalk 2.32.0 adds a new compiler option, multifile_directive, to all config 
files. Older config files are incompatible with this new Logtalk version.

Logtalk version 2.32.1 changes representation of loaded entities therefore 
implying recompilation of all source files.

Logtalk version 2.32.2 changes the internal predicate used in the processing 
of "super" calls, changes the implementation of complementing categories,  
changes the possible values of the read-only compiler flag "break_predicate",
and changes the way proprietary Prolog meta-predicates and control constructs 
are declared, therefore implying the recompilation of all objects.