root/tags/lgt2372/QUICK_START.txt

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

Copyright (c) 1998-2009 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.
================================================================


Quick start
===========


Starting up Logtalk
-------------------

1. Install Logtalk by using either the installer provided for your 
operating-system (when available) or by following the instructions 
on the "INSTALL.txt" file. Depending on your operating-system, working 
environment, and favorite back-end Prolog compiler, you may already have 
a script or a shortcut installed for easily running Logtalk with your 
favorite Prolog compiler. In this case, skip the instructions below 
for starting up Logtalk and go straight to the instructions on running 
the examples.

On POSIX operating-systems, the following shell scripts are installed 
by default for running Logtalk with selected back-end Prolog compilers 
(which must be up-to-date and properly installed for running the scripts!):

* B-Prolog:       bplgt
* Ciao:           ciaolgt    (first run must use sudo)
* CxProlog:       cxlgt
* ECLiPSe:        eclipselgt
* GNU Prolog:     gplgt
* K-Prolog:       plclgt
* Qu-Prolog:      qplgt
* Quintus Prolog  quintuslgt (requires patching Logtalk)
* SICStus Prolog: sicstuslgt
* SWI-Prolog:     swilgt
* XSB:            xsblgt     (first run must use sudo)
* XSB 64 bits:    xsb64lgt   (first run must use sudo)
* XSB MT:         xsbmtlgt   (first run must use sudo)
* XSB MT 64 bits: xsbmt64lgt (first run must use sudo)
* YAP:            yaplgt

Integration with Quintus Prolog requires manual patches that render 
Logtalk incompatible with all the other compilers.

On Windows systems, shortcuts for running Logtalk with selected back-end 
Prolog compilers are created on the "Start Menu/Programs/Logtalk" menu.
If you get an unexpected failure when using one of the Prolog integration
scripts, consult the "configs/NOTES.txt" file for compatibility notes.

On MacOS X systems, shortcuts for running Logtalk with selected back-end 
Prolog compilers are available on the "scripts/macosx/command_files" folder
on the Logtalk installation folder (by default, /opt/local/share/logtalk).
If you get an unexpected failure when using one of the Prolog integration
scripts, consult the "configs/NOTES.txt" file for compatibility notes.

2. Open the "manuals/index.html" file with a web browser.

3. Select the "Tutorial" link. This will provide you with a basic 
understanding of the main Logtalk concepts.

4. Go back to the "index.html" file, select the "User Manual" link, then
the "Installing Logtalk" and "Writing, Running, and Debugging Logtalk
Programs" links. This will provide you with a basic understanding of 
how to start Logtalk as well as how to compile and load Logtalk code.


In case a manual installation is necessary, and assuming that Logtalk 
supports your Prolog compiler, apply the following steps:

1. Read the "NOTES.txt" file in the "configs" sub-directory to check if 
any patch or workaround is needed for your compiler.

2. Start your Prolog compiler.

3. Change the current working directory of your Prolog session to the 
Logtalk installation directory. If you don't know which predicate to 
use, check the "configs/NOTES.txt" file or your Prolog compiler reference 
manual.

4. Compile and load the config file for your Prolog compiler.

5. Compile and load the Logtalk compiler/runtime found on the "compiler" 
sub-directory.

6. Adapt, if needed, the file "libpaths/libpaths.pl" to match your Logtalk 
installation, Prolog compiler, operating-system, and then compile and 
load it.

Note that both the configuration files, the compiler/runtime files, and the 
library paths file are Prolog files. The predicate used to load these files 
depends on your Prolog compiler (consult your Prolog compiler documentation 
or take a look at the definition of the predicate '$lgt_load_prolog_code'/3 
in the config file. For most command-line compilers, you could type at the 
Prolog prompt something like:

    | ?- ['configs/foo.pl', 'compiler/logtalk.pl', 'libpaths/libpaths.pl'].

Replace the file name "foo.pl" with the appropriate config file name for 
your compiler.


Running the examples
--------------------

You may now try some of the provided examples:

1. Open the "examples" sub-directory. There you find several sub-directories
with ready to run examples and a "NOTES.txt" file containing general 
instructions and a brief description of each example. Select and open one 
of the examples sub-directory.

2. Read the example "NOTES.txt" file for a description of the example.

3. Open the "SCRIPT.txt" file for instructions on how to load the example 
and for sample queries that you may try by copying-and-pasting them to 
your Prolog interpreter top-level.


Writing your own programs
_________________________

Ready to start writing your own programs?

1. Read the User Manual sections on "Programming in Logtalk" and "Running 
and debugging Logtalk programs".

2. Take a look at the "wenv" sub-directory. There you will find syntax 
configuration files for popular text editors which enable syntax coloring 
and other text services when editing Logtalk source files.

3. Create a sub-directory with a suitable name to hold all the files of 
your application. You may want to add the directory path to the "libpaths.pl" 
file mentioned above in order to easily load your application.

4. Copy to this sub-directory a loader file from one of the example 
directories and modify it to load your own source files.

5. Have fun!