yap-6.3/Logtalk/INSTALL

=================================================================
Logtalk - Object oriented extension to Prolog
Release 2.27.0

Copyright (c) 1998-2006 Paulo Moura.  All Rights Reserved.
=================================================================


This file contains detailed instructions for installing and configuring 
Logtalk. You should also consult the "scripts/NOTES" file for a description 
of a set of shell scripts that might be used for Logtalk installation on 
some operating-systems and for easy Logtalk integration with popular 
Prolog compilers.

Note that the broad compatibility of Logtalk, both with Prolog compilers and 
operating-systems, together with all the possible user scenarios, means that 
installation can vary from very simple by running a couple of scripts to the 
need of patching both Logtalk and Prolog compilers to workaround the lack of 
strong Prolog standards.


1. LOGTALK BASIC INSTALLATION

Installing Logtalk can be as simple as decompressing the downloaded archive 
and copying the resulting directory to a suitable location. This location 
depends on the working environment and on the number of users. The Logtalk 
directory can reside in any user accessible location. Whenever possible, it 
is recommended that Logtalk be installed by a user with administrative rights, 
as described below. This leads to a setup where each Logtalk user may freely 
try and modify the provided examples, library, and configuration files with 
the option of, at any time, restoring the files to its original state by 
simply running one of the provided scripts.


* Installing for a single user with no administrative rights:

In the case of a single user with no administrative rights, the Logtalk 
directory may simply be copied to the user home directory.


* Installing for one or more users by a user with administrative rights:

In the case of installation by a user with administrative rights, the Logtalk 
directory can be copied to any location that its accessible by all the users 
(assuming that copying the Logtalk directory to each user home directory is, 
for some reason, not feasible or desired).

The "scripts" sub-directory contains shell scripts for easy installation of 
Logtalk on MacOS X, Windows, Linux, and Unix-like (POSIX) operating systems 
(see the "scripts/NOTES" file for details).

>> POSIX systems installation (starting from the Logtalk directory):

	% cd scripts
	% sudo ./lgt_install.sh

>> Windows installation (starting from the Logtalk directory):

	C:\logtalk> cd scripts
	C:\logtalk> cscript lgt_install.js
	RESTART

The "scripts/lgt_install.*" installation scripts make all files read-only in 
order to avoid user tempering. This is a convenient setup for computer labs, 
given that making directories world-writable is a security risk.


2. SETTING LOGTALK ENVIRONMENT VARIABLES

You need to set two environment variables, LOGTALKHOME and LOGTALKUSER. The 
environment variable LOGTALKHOME should point to the Logtalk installation 
directory. The environment variable LOGTALKUSER should point to a directory 
in your home directory where you want to store the user-specific Logtalk files
(for example, ~/logtalk). Both environment variables may be set for all users 
by a user with administration privileges. The two environment variables can 
have the same value if you are the only Logtalk user on your computer and if 
you have full permissions to the Logtalk installation directory. In addition, 
you may want to add the Logtalk sub-directory "xml", which contains useful 
scripts for processing XML documenting files, to your execution path.

>> POSIX systems:

If you use a csh shell, add the following line to your ~/.cshrc file:

	setenv LOGTALKHOME /your/logtalk/installation/directory
	setenv LOGTALKUSER $HOME/logtalk
	setenv PATH $PATH:$LOGTALKHOME/xml:$LOGTALKHOME/scripts

If you use a bash shell, add the following lines to your ~/.profile file:

	LOGTALKHOME=/your/logtalk/installation/directory
	LOGTALKUSER=$HOME/logtalk
	PATH=$PATH:$LOGTALKHOME/xml:$LOGTALKHOME/scripts
	export PATH LOGTALKHOME LOGTALKUSER

When using the provided shell script for installing Logtalk, a symbolic link 
to the Logtalk installation directory is automatically created. The link is 
named "logtalk". In this case, you may use this symbolic link to define the 
LOGTALKHOME environment variable in order to avoid breaking it when upgrading 
Logtalk.

>> Windows systems:

In Windows 2000/XP, environment variables are defined using the System 
properties control panel. If you are a system administrator, the "scripts/
lgt_install.js" JScript install script sets the LOGTALKHOME environment 
variable for all users and also sets the LOGTALKUSER environment variable 
for the administrator user running the script.


3. CREATING NEW PROLOG TOP-LEVELS FOR AUTOMATIC LOADING OF LOGTALK

Most Prolog compilers allows the user to define an initialization file that 
is automatically consulted at startup. This initialization file may contain 
directives for loading other files, such as the Logtalk configuration file 
and the Logtalk compiler. The "$LOGTALKHOME/scripts" sub-directory contains 
several scripts (named "make_*lgt.*") for automating the creation of these 
initialization files for some Prolog compilers. In addition, be sure to read 
the "configs/NOTES" file notes on the Prolog compilers that you intend to use.
There are also "makeall_lgt.*" scripts that try to run all the individual
"make_*lgt.*" scripts:

>> POSIX systems:

	% cd $LOGTALKHOME/scripts
	% sudo ./makeall_lgt.sh

>> Windows:

	C:\> cd %LOGTALKHOME%\scripts
	C:\> cscript makeall_lgt.js

This assumes that your favorite Prolog compilers are supported by the 
"make_*lgt.*" scripts. If that is not the case, don't worry: just follow 
the steps described in the "QUICK_START" file.


4. COPYING THE LOGTALK USER-MODIFIABLE FILES TO USERS HOME DIRECTORIES

If you installed Logtalk on your home directory, then skip this step if you 
have set both Logtalk environment variables (LOGTALKHOME and LOGTALKUSER) to 
point to the same directory.

Each user must make a local copy of the Logtalk user-modifiable files to its 
home directory. This setup allows each user to easily and independently 
customize Logtalk to its needs. These copies can be easily made by instructing
end-users to simply run the shell scripts "cplgtdirs.*" (which are described 
in the "scripts/NOTES" file).

>> POSIX systems:

	% cplgtdirs

>> Windows:

	C:\> cplgtdirs

The local copies made by the "cplgtdirs" scripts have both read and write 
permissions for the user running the script. When used with one of the 
Prolog compilers for which an integration script is provided on the "scripts"
directory, this setup as the advantage of allowing each end-user to 
independently customize default compilation options and library paths.


5. SETTING LIBRARY PATHS

In Logtalk, a library is simply a directory containing source files. Library 
paths can be declared using a dynamic predicate. This allows compiling and 
loading of libraries and library files to be performed without worries about 
library paths. Assuming that you have used the "scripts/cplgtdirs.*" shell 
scripts for making a copy of the user-modifiable Logtalk files, you will find 
in the "$LOGTALKUSER/libpaths" directory a sample file which, when loaded, 
defines the library paths for the Logtalk standard library and for all the 
supplied examples. This file may need to be edited to match your Logtalk 
installation and your Prolog compiler and operating-system requirements. For 
more details, see the file "$LOGTALKUSER/libpaths/NOTES".


6. CUSTOMIZING PROLOG CONFIGURATION FILES

Logtalk interfaces with a specific Prolog compiler via a configuration file 
that can be found on the "$LOGTALKUSER/configs" directory. These configuration 
files can be customized by changing the values of the default flags that are 
used by Logtalk when compiling source files. For a full description of these 
default flags, consult the "Running and debugging Logtalk programs" section of 
the User Manual. Some of the default flags that you may want to change are: 
"smart_compilation", "startup_message", "portability", "underscore_vars", 
"altdirs", and the set of documentation-related flags ("xmldocs", "xslfile", 
"xmlspec", and "xmlsref"). Be sure to read the "$LOGTALKUSER/configs/NOTES" 
file for Prolog specific notes; some Prolog compilers do not support the whole
range of compilation flag values.  


7. CUSTOMIZING DOCUMENTATION PROCESSING SCRIPTS AND SUPPORTING FILES

Logtalk provides, in the "$LOGTALKUSER/xml" directory, a set of shell scripts, 
CSS and XSLT style-sheets, and DTD and XML Schema files for processing the XML 
documenting files that are automatically generated when you compile source 
files. You may want to customize these CSS and XSLT files to modify the layout 
or style of the resulting PDF/(X)HTML files or to write new scripts and 
transformations to generate other formats. For more details, see the file 
"$LOGTALKUSER/xml/NOTES".