fix xminor bugs in manual

This commit is contained in:
Vítor Santos Costa 2014-03-27 15:34:25 +00:00
parent 683b5989ae
commit f7283f6b70
7 changed files with 7802 additions and 8279 deletions

6150
docs/builtins.tex Normal file

File diff suppressed because it is too large Load Diff

389
docs/install.tex Normal file
View File

@ -0,0 +1,389 @@
@c -*- mode: texinfo; coding: utf-8; -*-
@node Install, Run, Intro, Top
@chapter Installing YAP
@cindex installation
@menu
* Configuration Options:: Tuning the Functionality of YAP Machine
* Machine Options:: Tuning YAP for a Particular Machine and Compiler
@end menu
To compile YAP it should be sufficient to:
@enumerate
@item @command{autoconf}. Recent versions of YAP try to follow GNU
conventions on where to place software.
@itemize @bullet
@item The main executable is placed at @var{$BINDIR}. This executable is
actually a script that calls the Prolog engine, stored at @var{$LIBDIR}.
@item @var{$LIBDIR} is the directory where libraries are stored. YAPLIBDIR is a
subdirectory that contains the Prolog engine and a Prolog library.
@item @var{$INCLUDEDIR} is used if you want to use YAP as a library.
@item @var{$INFODIR} is where to store @code{info} files. Usually
@file{/usr/local/info}, @file{/usr/info}, or @file{/usr/share/info}.
@end itemize
@item @command{make}.
@item If the compilation succeeds, try @command{./yap}.
@item If you feel satisfied with the result, do @command{make install}.
@item @command{make install-info} will create the info files in the
standard info directory.
@item @command{make html} will create documentation in html format in the
predefined directory.
@end enumerate
In most systems you will need to be superuser in order to do @command{make
install} and @command{make info} on the standard directories.
@node Configuration Options, Machine Options, ,Install
@section Tuning the Functionality of YAP
@cindex syntax
Compiling YAP with the standard options give you a plain vanilla
Prolog. You can tune YAP to include extra functionality by calling
@command{configure} with the appropriate options:
@itemize @bullet
@item @command{--enable-rational-trees=yes} gives you support for infinite
rational trees.
@item @command{--enable-coroutining=yes} gives you support for coroutining,
including freezing of goals, attributed variables, and
constraints. This will also enable support for infinite rational
trees.
@item @command{--enable-depth-limit=yes} allows depth limited evaluation, say for
implementing iterative deepening.
@item @command{--enable-low-level-tracer=yes} allows support for tracing all calls,
retries, and backtracks in the system. This can help in debugging your
application, but results in performance loss.
@item @command{--enable-wam-profile=yes} allows profiling of abstract machine
instructions. This is useful when developing YAP, should not be so
useful for normal users.
@item @command{--enable-condor=yes} allows using the Condor system that
support High Throughput Computing (HTC) on large collections of
distributively owned computing resources.
@item @command{--enable-tabling=yes} allows tabling support. This option
is still experimental.
@item @command{--enable-parallelism=@{env-copy,sba,a-cow@}} allows
or-parallelism supported by one of these three forms. This option is
still highly experimental.
@item @command{--with-max-workers} allows definition of the maximum
number of parallel processes (its value can be consulted at runtime
using the flag @command{max_workers}).
@item @command{--with-gmp[=DIR]} give a path to where one can find the
@code{GMP} library if not installed in the default path.
@item @command{--enable-threads} allows using of the multi-threading
predicates provided by YAP. Depending on the operating system, the
option @command{--enable-pthread-locking} may also need to be used.
@item @command{--with-max-threads} allows definition of the maximum
number of threads (the default value is 1024; its value can be consulted
at runtime using the flag @code{max_threads}).
@end itemize
Next section discusses machine dependent details.
@node Machine Options, , Configuration Options,Install
@section Tuning YAP for a Particular Machine and Compiler
@cindex machine optimizations
The default options should give you best performance under
@command{GCC}. Although the system is tuned for this compiler
we have been able to compile versions of YAP under lcc in Linux,
Sun's cc compiler, IBM's xlc, SGI's cc, and Microsoft's Visual C++
6.0.
@menu
* Tuning for GCC:: Using the GNUCC compiler
* Compiling Under Visual C++:: Using Microsoft's Visual C++ environment
* Tuning for SGI cc:: Compiling Under SGI's @command{cc}
@end menu
@node Tuning for GCC, Compiling Under Visual C++, , Machine Options
@section Tuning YAP for @command{GCC}.
YAP has been developed to take advantage of @command{GCC} (but not to
depend on it). The major advantage of @command{GCC} is threaded code and
explicit register reservation.
YAP is set by default to compile with the best compilation flags we
know. Even so, a few specific options reduce portability. The option
@itemize @bullet
@item @command{--enable-max-performance=yes} will try to support the best
available flags for a specific architectural model. Currently, the option
assumes a recent version of @command{GCC}.
@item @command{--enable-debug-yap} compiles YAP so that it can be debugged
by tools such as @command{dbx} or @command{gdb}.
@end itemize
Here follow a few hints:
On x86 machines the flags:
@example
YAP_EXTRAS= ... -DBP_FREE=1
@end example
tells us to use the @code{%bp} register (frame-pointer) as the emulator's
program counter. This seems to be stable and is now default.
On Sparc/Solaris2 use:
@example
YAP_EXTRAS= ... -mno-app-regs -DOPTIMISE_ALL_REGS_FOR_SPARC=1
@end example
and YAP will get two extra registers! This trick does not work on
SunOS 4 machines.
Note that versions of GCC can be tweaked to recognize different
processors within the same instruction set, e.g. 486, Pentium, and
PentiumPro for the x86; or Ultrasparc, and Supersparc for
Sparc. Unfortunately, some of these tweaks do may make YAP run slower or
not at all in other machines with the same instruction set, so they
cannot be made default.
Last, the best options also depends on the version of GCC you are using, and
it is a good idea to consult the GCC manual under the menus "Invoking
GCC"/"Submodel Options". Specifically, you should check
@command{-march=XXX} for recent versions of GCC/EGCS. In the case of
@command{GCC2.7} and other recent versions of @command{GCC} you can check:
@itemize @bullet
@item 486:
In order to take advantage of 486 specific optimizations in GCC 2.7.*:
@example
YAP_EXTRAS= ... -m486 -DBP_FREE=1
@end example
@item Pentium:
@example
YAP_EXTRAS= ... -m486 -malign-loops=2 -malign-jumps=2 \
-malign-functions=2
@end example
@item PentiumPro and other recent Intel and AMD machines:
PentiumPros are known not to require alignment. Check your version of
@command{GCC} for the best @command{-march} option.
@item Super and UltraSparcs:
@example
YAP_EXTRAS= ... -msupersparc
@end example
@item MIPS: if have a recent machine and you need a 64 bit wide address
space you can use the abi 64 bits or eabi option, as in:
@example
CC="gcc -mabi=64" ./configure --...
@end example
Be careful. At least for some versions of @command{GCC}, compiling with
@command{-g} seems to result in broken code.
@item WIN32: GCC is distributed in the MINGW32 and CYGWIN packages.
The Mingw32 environment is available from the URL:
@url{http://www.mingw.org}
You will need to install the @command{msys} and @command{mingw}
packages. You should be able to do configure, make and make install.
If you use mingw32 you may want to search the contributed packages for
the @command{gmp} multi-precision arithmetic library. If you do setup YAP
with @code{gmp} note that @file{libgmp.dll} must be in the path,
otherwise YAP will not be able to execute.
CygWin environment is available from the URL:
@url{http://www.cygwin.com}
@noindent
and mirrors. We suggest using recent versions of the cygwin shell. The
compilation steps under the cygwin shell are as follows:
@example
mkdir cyg
$YAPSRC/configure --enable-coroutining \\
--enable-depth-limit \\
--enable-max-performance
make
make install
@end example
By default, YAP will use the @command{-mno-cygwin} option to
disable the use of the cygwin dll and to enable the mingw32 subsystem
instead. YAP thus will not need the cygwin dll. It instead accesses
the system's @file{CRTDLL.DLL} @code{C} run time library supplied with
Win32 platforms through the mingw32 interface. Note that some older
WIN95 systems may not have @file{CRTDLL.DLL}, in this case it should
be sufficient to import the file from a newer WIN95 or WIN98 machine.
You should check the default installation path which is set to
@file{/YAP} in the standard Makefile. This string will usually
be expanded into @file{c:\YAP} by Windows.
The cygwin environment does not provide @t{gmp} on the MINGW
subsystem. You can fetch a dll for the @t{gmp} library from
@url{http://www.sf.net/projects/mingwrep}.
It is also possible to configure YAP to be a part of the cygwin
environment. In this case you should use:
@example
mkdir cyg
$YAPSRC/configure --enable-max-performance \\
--enable-cygwin=yes
make
make install
@end example
YAP will then compile using the cygwin library and will be installed
in cygwin's @file{/usr/local}. You can use YAP from a cygwin console,
or as a standalone application as long as it can find
@file{cygwin1.dll} in its path. Note that you may use to use
@command{--enable-depth-limit} for Aleph compatibility, and that you may
want to be sure that GMP is installed.
@end itemize
@node Compiling Under Visual C++, Tuning for SGI cc, Tuning for GCC, Machine Options
@subsection Compiling Under Visual C++
YAP compiles cleanly under Microsoft's Visual C++ release 6.0. We next
give a step-by-step tutorial on how to compile YAP manually using this
environment.
First, it is a good idea to build YAP as a DLL:
@enumerate
@item create a project named yapdll using File.New. The project will be a
DLL project, initially empty.
Notice that either the project is named yapdll or you must replace the
preprocessors variable @var{$YAPDLL_EXPORTS} to match your project names
in the files @file{YAPInterface.h} and @code{c_interface.c}.
@item add all .c files in the @file{$YAPSRC/C} directory and in the
@file{$YAPSRC\OPTYAP} directory to the Project's @code{Source Files} (use
FileView).
@item add all .h files in the @var{$YAPSRC/H} directory,
@var{$YAPSRC\include} directory and in the @var{$YAPSRC\OPTYAP}
subdirectory to the Project's @code{Header Files}.
@item Ideally, you should now use @code{m4} to generate extra .h from .m4 files and use
@code{configure} to create a @code{config.h}. Or, you can be lazy, and
fetch these files from @var{$YAPSRC\VC\include}.
@item You may want to go to @code{Build.Set Active Configuration} and
set @code{Project Type} to @code{Release}
@item To use YAP's own include directories you have to set the Project
option @code{Project.Project Settings.C/C++.Preprocessor.Additional
Include Directories} to include the directories @var{$YAPSRC\H},
@var{$YAPSRC\VC\include}, @var{$YAPSRC\OPTYAP} and
@var{$YAPSRC\include}. The syntax is:
@example
$YAPSRC\H, $YAPSRC\VC\include, $YAPSRC\OPTYAP, $YAPSRC\include
@end example
@item Build: the system should generate an @file{yapdll.dll} and an @file{yapdll.lib}.
@item Copy the file @file{yapdll.dll} to your path. The file
@file{yapdll.lib} should also be copied to a location where the linker can find it.
@end enumerate
Now you are ready to create a console interface for YAP:
@enumerate
@item create a second project say @code{wyap} with @code{File.New}. The project will be a
WIN32 console project, initially empty.
@item add @var{$YAPSRC\console\yap.c} to the @code{Source Files}.
@item add @var{$YAPSRC\VC\include\config.h} and the files in @var{$YAPSRC\include} to
the @code{Header Files}.
@item You may want to go to @code{Build.Set Active Configuration} and set
@code{Project Type} to @code{Release}.
@item you will eventually need to bootstrap the system by booting from
@code{boot.yap}, so write:
@example
-b $YAPSRC\pl\boot.yap
@end example
in @code{Project.Project Settings.Debug.Program Arguments}.
@item You need the sockets and yap libraries. Add
@example
ws2_32.lib yapdll.lib
@end example
to @code{Project.Project Settings.Link.Object/Library Modules}
You may also need to set the @code{Link Path} so that VC++ will find @code{yapdll.lib}.
@item set @code{Project.Project Settings.C/C++.Preprocessor.Additional Include Directories} to include the
@var{$YAPSRC/VC/include} and
@var{$YAPSRC/include}.
The syntax is:
@example
$YAPSRC\VC\include, $YAPSRC\include
@end example
@item Build the system.
@item Use @code{Build.Start Debug} to boot the system, and then create the saved state with
@example
['$YAPSRC\\pl\\init'].
qsave_program('startup.yss').
^Z
@end example
That's it, you've got YAP and the saved state!
@end enumerate
The $YAPSRC\VC directory has the make files to build YAP4.3.17 under VC++ 6.0.
@node Tuning for SGI cc, , Compiling Under Visual C++ ,Machine Options
@subsection Compiling Under SGI's cc
YAP should compile under the Silicon Graphic's @code{cc} compiler,
although we advise using the GNUCC compiler, if available.
@table @code
@item 64 bit
Support for 64 bits should work by using (under Bourne shell syntax):
@example
CC="cc -64" $YAP_SRC_PATH/configure --...
@end example
@end table

1021
docs/load.tex Normal file

File diff suppressed because it is too large Load Diff

214
docs/run.tex Normal file
View File

@ -0,0 +1,214 @@
@c -*- mode: texinfo; coding: utf-8; -*-
@node Run, Syntax, Install, Top
@chapter Running YAP
@menu
* Running YAP Interactively:: Interacting with YAP
* Running Prolog Files:: Running Prolog files as scripts
@end menu
@cindex booting
We next describe how to invoke YAP in Unix systems.
@node Running YAP Interactively, ,Running Prolog Files,Run
@section Running YAP Interactively
Most often you will want to use YAP in interactive mode. Assuming that
YAP is in the user's search path, the top-level can be invoked under
Unix with the following command:
@example
yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename]
@end example
@noindent
All the arguments and flags are optional and have the following meaning:
@table @code
@item -?
print a short error message.
@item -s@var{Size}
allocate @var{Size} KBytes for local and global stacks. The user may
specify @t{M} bytes.
@item -h@var{Size}
allocate @var{Size} KBytes for heap and auxiliary stacks
@item -t@var{Size}
allocate @var{Size} KBytes for the trail stack
@item -L@var{Size}
SWI-compatible option to allocate @var{Size} K bytes for local and global stacks, the local stack
cannot be expanded. To avoid confusion with the load option, @var{Size}
must immediately follow the letter @code{L}.
@item -G@var{Size}
SWI-compatible option to allocate @var{Size} K bytes for local and global stacks; the global
stack cannot be expanded
@item -T@var{Size}
SWI-compatible option to allocate @var{Size} K bytes for the trail stack; the trail cannot be expanded.
@item -l @var{YAP_FILE}
compile the Prolog file @var{YAP_FILE} before entering the top-level.
@item -L @var{YAP_FILE}
compile the Prolog file @var{YAP_FILE} and then halt. This option is
useful for implementing scripts.
@item -g @var{Goal}
run the goal @var{Goal} before top-level. The goal is converted from
an atom to a Prolog term.
@item -z @var{Goal}
run the goal @var{Goal} as top-level. The goal is converted from
an atom to a Prolog term.
@item -b @var{BOOT_FILE}
boot code is in Prolog file @var{BOOT_FILE}. The filename must define
the predicate @code{'$live'/0}.
@item -c @t{IP_HOST} @t{port}
connect standard streams to host @t{IP_HOST} at port @t{port}
@item filename
restore state saved in the given file
@item -f
do not consult initial files
@item -q
do not print informational messages
@item --
separator for arguments to Prolog code. These arguments are visible
through the @code{unix/1} built-in predicate.
@end table
Note that YAP will output an error message on the following conditions:
@itemize @bullet
@item
a file name was given but the file does not exist or is not a saved
YAP state;
@item
the necessary amount of memory could not be allocated;
@item
the allocated memory is not enough to restore the state.
@end itemize
When restoring a saved state, YAP will allocate the
same amount of memory as that in use when the state was saved, unless a
different amount is specified by flags in the command line. By default,
YAP restores the file @file{startup.yss} from the current directory or from
the YAP library.
@cindex environment variables
@findex YAPBINDIR
@itemize @bullet
@item
YAP usually boots from a saved state. The saved state will use the default
installation directory to search for the YAP binary unless you define
the environment variable YAPBINDIR.
@findex YAPLIBDIR
@item
YAP always tries to find saved states from the current directory
first. If it cannot it will use the environment variable YAPLIBDIR, if
defined, or search the default library directory.
@findex YAPSHAREDIR
@item
YAP will try to find library files from the YAPSHAREDIR/library
directory.
@end itemize
@node Running Prolog Files, Running YAP Interactively, , Run
@section Running Prolog Files
YAP can also be used to run Prolog files as scripts, at least in
Unix-like environments. A simple example is shown next (do not forget
that the shell comments are very important):
@example
@cartouche
#!/usr/local/bin/yap -L --
#
# Hello World script file using YAP
#
# put a dot because of syntax errors .
:- write('Hello World'), nl.
@end cartouche
@end example
The @code{#!} characters specify that the script should call the binary
file YAP. Notice that many systems will require the complete path to the
YAP binary. The @code{-L} flag indicates that YAP should consult the
current file when booting and then halt. The remaining arguments are
then passed to YAP. Note that YAP will skip the first lines if they
start with @code{#} (the comment sign for Unix's shell). YAP will
consult the file and execute any commands.
A slightly more sophisticated example is:
@example
@cartouche
#!/usr/bin/yap -L --
#
# Hello World script file using YAP
# .
:- initialization(main).
main :- write('Hello World'), nl.
@end cartouche
@end example
The @code{initialization} directive tells YAP to execute the goal main
after consulting the file. Source code is thus compiled and @code{main}
executed at the end. The @code{.} is useful while debugging the script
as a Prolog program: it guarantees that the syntax error will not
propagate to the Prolog code.
Notice that the @code{--} is required so that the shell passes the extra
arguments to YAP. As an example, consider the following script
@code{dump_args}:
@example
@cartouche
#!/usr/bin/yap -L --
#.
main( [] ).
main( [H|T] ) :-
write( H ), nl,
main( T ).
:- unix( argv(AllArgs) ), main( AllArgs ).
@end cartouche
@end example
If you this run this script with the arguments:
@example
./dump_args -s 10000
@end example
@noindent
the script will start an YAP process with stack size @code{10MB}, and
the list of arguments to the process will be empty.
Often one wants to run the script as any other program, and for this it
is convenient to ignore arguments to YAP. This is possible by using
@code{L --} as in the next version of @code{dump_args}:
@example
@cartouche
#!/usr/bin/yap -L --
main( [] ).
main( [H|T] ) :-
write( H ), nl,
main( T ).
:- unix( argv(AllArgs) ), main( AllArgs ).
@end cartouche
@end example
The @code{--} indicates the next arguments are not for YAP. Instead,
they must be sent directly to the @code{argv} built-in. Hence, running
@example
./dump_args test
@end example
@noindent
will write @code{test} on the standard output.

View File

@ -310,7 +310,7 @@ enumeration is undefined.
Delete the named global variable. Delete the named global variable.
@end table @end table
@section Compatibility of Global Variables @subsubsection Compatibility of Global Variables
Global variables have been introduced by various Prolog Global variables have been introduced by various Prolog
implementations recently. YAP follows their implementation in SWI-Prolog, itself implementations recently. YAP follows their implementation in SWI-Prolog, itself

13
docs/yap.bib Normal file
View File

@ -0,0 +1,13 @@
@book{TheArtOfProlog,
Author = "Sterling, Leon and Shapiro, Ehud",
Title = "The Art of Prolog",
Publisher = "MIT Press",
Year = "1986" }
@Book{ProgrammingInProlog,
Author ="William F. Clocksin and Christopher S. Mellish",
Title ={Programming in Prolog},
Publisher ={Springer-Verlag},
Year =1986
}

File diff suppressed because it is too large Load Diff